OptiCat MCP AtlasContract · flow · evidence · ideas
System atlasProduct intelligencecompare_parts
Product intelligence · compare_parts

Compare exact catalog products

Compare two to four exact identities with original and normalized units, field outcomes and optional vehicle verification.

Run the example Inspect contract
Visual model · gates

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.

compare_partsArgumentsGenerated JSON Schema
read only
interactionInteractionContext | nulloptional
default null
requestComparePartsInputrequired
partsPartLookupInput[]required
brandstring | nulloptional
default null
part_numberstringrequired
min length 1
part_typestring | nulloptional

Optional readable part-type hint (e.g. 'Engine Oil Filter'). Used to prefer the intended category when a part number exists in multiple unrelated categories; best effort, never erases evidence.

default null
part_type_idinteger | nulloptional
default null
requested_fieldsattributes | dimensions | descriptions | country_of_origin | lifecycle | relationships | images | fitment | packaging | kits[]optional
vehicleComparisonVehicle | nulloptional
default null
Example MCP argumentsMatches the existing demo handoff
{
  "request": {
    "parts": [
      {
        "part_number": "WPK-822",
        "brand": "Aisin"
      },
      {
        "part_number": "WPK-823",
        "brand": "Aisin"
      }
    ]
  }
}
Compare Aisin WPK-822 and WPK-823 attributes
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 each requested exact identity.
Requires
parts
Produces
identities · clarifications
Validation
No implicit first-match selection.
02
getAutoCarePartDetailsRetrieve comparable product fields.
Requires
exact identity
Produces
original values · units · relationships
Validation
Compare only returned data.
03
getAutoCarePartApplicationsOptionally verify each part for a vehicle.
Requires
vehicle · exact identity
Produces
fitment decision
Validation
Specification agreement is not fitment.
Decision logic

Every important branch has a named outcome.

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

One product cannot be resolvedpartial

Preserve the other products and identify the unavailable one.

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 identitiesOriginal unitsNormalized valuesField outcomesIndependent fitmentEvidence references
Grounding guaranteesRules against invented certainty
  • No interchangeability inference
  • Missing products remain visible
  • One shared execution budget
Implementation sourcesSymbols behind the visual
Handlercompare_partspoc/opticat-mcp-v2/src/opticat_mcp_v2/expansion.py
Unit comparisoncompare_valuespoc/opticat-mcp-v2/src/opticat_mcp_v2/units.py
Host presentationfinalResultFromCataloglib/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

    Known entitled comparison examples require live adjudication

Next
Category-specific comparison defaults

Choose the most useful specifications after domain review.

Product concept · not implemented