OptiCat MCP AtlasContract · flow · evidence · ideas
System atlasFoundationresolve_catalog_entities
Foundation · entity_resolution

Resolve what the customer means

Confirm partial vehicle, manufacturer, category and part identities before a product lookup.

Run the example Inspect contract
Visual model · funnel

Follow the implementation from request to evidence.

Every node corresponds to a real resolver, operation, validation boundary, or response surface in the current code.

Registered input contract

The exact arguments the MCP server accepts.

This schema is generated from the registered Python tool. Required fields, defaults, nested models, and constraints are not maintained by hand.

resolve_catalog_entitiesArgumentsGenerated JSON Schema
read only
interactionInteractionContext | nulloptional
default null
requestCatalogResolveInputrequired
brandstring | nulloptional
default null
domainsvehicle | brand | part | part_type[] | nulloptional
default null
makestring | nulloptional
default null
make_hintstring | nulloptional
default null
modelstring | nulloptional
default null
model_hintstring | nulloptional
default null
part_numberstring | nulloptional
default null
part_typestring | nulloptional
default null
submodelstring | nulloptional
default null
yearinteger | nulloptional
default null
year_abbreviatedbooleanoptional
default false
Example MCP argumentsMatches the existing demo handoff
{
  "request": {
    "year": 2017,
    "model": "Jetta",
    "make_hint": "Volkswagen",
    "part_type": "brake pads"
  }
}
Brake pads for a 2017 Jetta
Operation sequence

What each upstream call needs—and earns.

Conditional calls are labeled. Validation describes the exact rule that allows evidence to advance to the next stage.

01
getAutoCareVehicleResultsValidate proposed vehicle identities.
Requires
year · model or model hint
Produces
base vehicle · choices
Validation
Explicit make wins over AI hints.
02
getAutoCareSearchResultsResolve brands, categories and exact parts.
Requires
supplied entity text
Produces
catalog identities · choices
Validation
No product availability or fitment conclusion.
Decision logic

Every important branch has a named outcome.

These are response decisions in the implemented service—not possible future behavior.

Required detail absent or candidates ambiguousclarification_required

Preserve successful resolutions and ask only for the missing identity.

Response anatomy

One shared schema, highlighted for this tool.

Bright fields are populated by this path. Dimmed fields remain part of CatalogResponse but are not a normal output of this tool.

Outcome1 active
statusResultStatusrequired
No nested fields. This value uses the type shown above.
summarystringrequired
No nested fields. This value uses the type shown above.
reason_codeReasonCode | null
No nested fields. This value uses the type shown above.
Context + completeness1 active
queryobject
No nested fields. This value uses the type shown above.
metadataobject
No nested fields. This value uses the type shown above.
completenessCompleteness
next_cursorstring | nulloptional
default null
next_pageinteger | nulloptional
default null
pages_fetchedintegeroptional
default 0
paging_modenone | page | cursor | capped | unknownoptional
default "none"5 allowed values
returnedintegeroptional
default 0
source_end_reachedbooleanoptional

This response reached the known end of the source query, even when earlier pages were returned separately.

default false
totalinteger | nulloptional
default null
truncatedbooleanoptional
default false
Domain evidence0 active
vehiclesVehicleIdentity[]
No nested fields. This value uses the type shown above.
partsPartRecord[]
No nested fields. This value uses the type shown above.
relationshipsRelationshipRecord[]
No nested fields. This value uses the type shown above.
relationship_outcomeRelationshipOutcome | null
No nested fields. This value uses the type shown above.
fitmentFitmentDecision | null
No nested fields. This value uses the type shown above.
interchange_validationsInterchangeValidation[]
No nested fields. This value uses the type shown above.
Conversation controls2 active
clarificationClarification | null
No nested fields. This value uses the type shown above.
pending_clarificationsClarification[]

Every open clarification dimension in one round (clarification stays = the first). Ask them together instead of one round trip per dimension.

No nested fields. This value uses the type shown above.
warningsstring[]
No nested fields. This value uses the type shown above.
Observability1 active
errorCatalogError | null
No nested fields. This value uses the type shown above.
evidenceEvidenceRecord[]
No nested fields. This value uses the type shown above.
What reaches the answerPreserved output families
vehicle identitymanufacturer identitypart categorypart identitymissing detailsinterpretations
Grounding guaranteesRules against invented certainty
  • Hints require catalog confirmation
  • Missing years are never invented
  • Resolution is not fitment verification
Implementation sourcesSymbols behind the visual
Resolver serviceresolve_catalog_entitiespoc/opticat-mcp-v2/src/opticat_mcp_v2/resolver_api.py
Language readerreadCatalogLanguagelib/catalog-language-resolver.ts
HTTP facaderesolveCatalogRequestlib/catalog-resolver.ts
Boundaries and ideas

What is known, and what could become possible.

Current gaps stay separate from product concepts so the visual never implies that an idea has already shipped.

Known gapsVerified limitations in the current path
  1. 01

    A genuinely absent year or ambiguous model still needs customer input

Explore
Resolution diagnostics

Compare language latency with catalog validation latency.

Product concept · not implemented