OptiCat MCP AtlasContract · flow · evidence · ideas
System atlasVehicle discoverysearch_parts_by_attributes
Vehicle discovery · attribute_search

Find products by specifications

Find catalog products by part type and unit-aware PIES attributes without requiring a vehicle.

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.

search_parts_by_attributesArgumentsGenerated JSON Schema
read only
interactionInteractionContext | nulloptional
default null
requestAttributeSearchInputrequired
attribute_filtersAttributeFilter[]required
include_maximumbooleanoptional
default true
include_minimumbooleanoptional
default true
maximumnumber | nulloptional
default null
minimumnumber | nulloptional
default null
namestringrequired

Catalog attribute name, resolved through PAdb evidence

min length 1max length 120
operatoreq | approx | range | gt | gte | lt | lteoptional
default "approx"7 allowed values
source_textstring | nulloptional

Original customer wording; not catalog evidence

default null
tolerancenumber | nulloptional

Relative tolerance for approximate equality only; default 0.01, disclosed in the result

default null
unitstring | nulloptional
default null
valuestring | number | integer | nulloptional
default null
brandsstring[]optional
cursor_markstring | nulloptional
default null
max_resultsintegeroptional
default 50min 1max 50
max_scannedintegeroptional
default 200min 1max 200
pageinteger | nulloptional
default null
part_typestringrequired
min length 1max length 160
Example MCP argumentsMatches the existing demo handoff
{
  "request": {
    "part_type": "Engine Air Filter",
    "attribute_filters": [
      {
        "name": "Height",
        "value": 55,
        "unit": "mm"
      }
    ]
  }
}
Find air filters with attributes: Height 55 mm
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
getAutoCareSearchResultsResolve the category and retrieve a bounded product set.
Requires
part_type · attribute_filters
Produces
parts · attribute_evaluation · continuation
Validation
Missing or incomparable data cannot establish a negative.
Decision logic

Every important branch has a named outcome.

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

Some candidates lack comparable datapartial

Keep verified matches and disclose unknowns.

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 evidence1 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 controls0 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
Exact product identitiesRecorded valuesUnitsUnknown countScanned coverageContinuation
Grounding guaranteesRules against invented certainty
  • No vehicle fitment inference
  • Missing values are unknown
  • Continuation is bound to the filters
Implementation sourcesSymbols behind the visual
Handlersearch_parts_by_attributespoc/opticat-mcp-v2/src/opticat_mcp_v2/expansion.py
Evidence policyattribute_evaluationpoc/opticat-mcp-v2/src/opticat_mcp_v2/policy.py
Host routingmcpToolForPlanlib/mcp.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

    Live attribute coverage and paging entitlement require validation

Explore
Category-specific specification aliases

Add reviewed aliases without guessing attribute IDs.

Product concept · not implemented