OptiCat MCP AtlasContract · flow · evidence · ideas
MCP tool atlas · evaluated 2026-09-16

Ten catalog tools.
One evidence-backed answer.

These are the ten tools an AI assistant is allowed to call against OptiCat’s catalog — and the only ones. Every tool returns the same response format, which carries the answer together with its proof: what was asked, what the catalog returned, and how complete that evidence is.

Explore the tool map Open a tool contract
Contract integrityGenerated from the registered MCP surface

The input schemas and the shared response format on this page are generated from the Python MCP server itself—not hand-copied. What you read here is what is registered.

Read only Closed world
15MCP tools
8OptiCat operations in use
1Shared answer format
1Deferred on purpose
Orientation

Four terms explain everything on this page.

Every diagram below is built from the same four elements. Here is what each one means, in plain language.

What the assistant can doMCP tool

One of the ten actions an AI assistant is allowed to take against OptiCat’s catalog — and the only actions it can take. Each tool is shaped around a customer job, like “does this part fit my car?”, not around a raw API endpoint.

verify_part_fitment
The raw catalog underneathOptiCat operation

A call to OptiCat’s AutoCare web service. 8 of the 9 documented operations are wired in; a single tool often makes several operation calls to answer one question.

getAutoCarePartApplications
The one answer formatCatalogResponse — the evidence boundary

The single response format every tool returns: the answer plus its proof — an outcome status, a completeness report, and a record of every upstream call made. The assistant can explain what is inside this response; it cannot add claims of its own. That is why we call it the evidence boundary.

17 fields · evidence per call
How proven each tool isConfidence status

Our current grade for each tool based on what has actually been demonstrated against the live catalog: live verified, live with a known boundary, or needs a live retest.

evaluated 2026-09-16
Why it's built this way

Every rule here prevents a failure we observed.

The first OptiCat MCP server—sixteen tools returning free text—failed in specific, documented ways. This version is the post-mortem made executable: each rule on the right exists because the failure on its left actually happened.

v1 failure
Answers were paragraphs of text

The first server’s sixteen tools each returned a block of prose. Neither the assistant nor the host application could tell catalog data from narration, so nothing downstream could check an answer.

v2 rule
Every answer is a typed CatalogResponse

All fourteen tools return one structured format with a named outcome, the matching records, and an evidence entry for every upstream call. Answers are data that can be verified, not stories that must be trusted.

v1 failure
Results were silently cut off

Hard caps trimmed result lists to the first ten or twenty rows with no signal that anything was missing. “Here are the parts” could quietly mean “here are some of the parts.”

v2 rule
Every response reports its own completeness

Total found, number returned, whether the list was truncated, and how to fetch more ride on every response. A cut-off result is labeled partial — it can never impersonate a complete one.

v1 failure
“Does not fit” could be wrong

The old fitment check answered “does NOT fit” whenever it found zero rows — even when the real cause was a truncated search or an access error. A missing answer became a confident wrong answer.

v2 rule
A definitive “no” requires complete evidence

Fitment now returns four distinct states — yes, no, conditional, unverified — and “no” is only permitted when the full application set was retrieved and checked. Uncertainty is reported as uncertainty.

v1 failure
The first match was silently chosen

Ambiguous vehicles and part types were resolved by picking whichever candidate came back first, so a question about one car could be answered about another.

v2 rule
Exact match, or the tool asks

When more than one vehicle, part type, or product matches, the response is a clarification question carrying the real catalog choices. The system never guesses identity on the customer’s behalf.

v1 failure
Sixteen tools mirrored raw API endpoints

Tools were shaped like the vendor API, not like customer questions, and multi-step jobs — supersession chains, part images — simply broke between them.

v2 rule
Ten tools, each shaped around one customer job

Each tool owns a complete job — find parts for a vehicle, verify a fitment, trace a replacement chain — and runs its own multi-step resolution pipeline internally, within a budgeted number of upstream calls (twenty by default).

v1 failure
Qualifiers, units, and lifecycle were discarded

Fitment qualifiers (“front axle only”), attribute units, and product lifecycle status were dropped on the way through — the exact details a parts professional needs to trust an answer.

v2 rule
The details that decide fitment are first-class fields

ACES qualifiers, attribute values with units, lifecycle status, and asset links travel through the response as structured fields, so nothing that could change the answer is flattened away.

The path of a question

How a question becomes an answer with proof.

Every question travels the same seven stages. The assistant never talks to the catalog directly—it calls one of the ten tools, and the tool does the resolving, calling, and checking before anything comes back.

  1. 01
    BrowserNatural-language question
  2. 02
    PlannerIntent + typed entities
  3. 03
    MCP clientRegistered tool contract
  4. 04
    ResolversHuman labels → catalog IDs
  5. 05
    OptiCat API8 operations in use
  6. 06
    Validation gatesIdentity · completeness · qualifiers
  7. 07
    CatalogResponseEvidence-backed answer
Interactive tool map

Pick a tool. See which catalog operations it reaches.

Search by what a customer is trying to do, filter by family or confidence, and hover a tool to light up the OptiCat operations it calls. Every path ends at the same CatalogResponse.

01
MCP toolswhat the assistant calls · 15 visible
FoundationNeeds a live retest
resolve_catalog_entitiesEntity resolver

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

2 operation steps
FoundationNeeds a live retest
get_catalog_statusCatalog status

Prove that OptiCat is reachable, classify access correctly, expose reference-data versions, and describe the configured key’s non-secret brand and VIN scope.

3 operation steps
Vehicle discoveryNeeds a live retest
search_catalog_jobParts jobs

Build a category-by-category parts job

1 operation steps
Vehicle discoveryNeeds a live retest
read_catalog_resultCaptured results

Browse exact captured catalog records

1 operation steps
Vehicle discoveryNeeds a live retest
evaluate_catalog_selectionSelected records

Explain, compare or verify exact records

1 operation steps
Vehicle discoveryNeeds a live retest
get_vehicle_resourcesApplication resources

Open supplier vehicle resources within the validated vehicle, category, brand and application scope.

2 operation steps
Vehicle discoveryNeeds a live retest
search_parts_for_vehicleVehicle search

Resolve readable vehicle and part-type language to catalog identities, apply optional brand and attribute constraints, and return paged candidates without hiding fitment qualifiers.

5 operation steps
Fitment evidenceNeeds a live retest
get_part_fitmentsPart applications

Resolve one exact catalog product and fan out its paged ACES application rows with vehicle identity, quantity, notes, and qualifiers intact.

2 operation steps
Fitment evidenceNeeds a live retest
verify_part_fitmentVerify fitment

Resolve the part and vehicle independently, retrieve filtered ACES applications, and return yes, no, conditional, or unverified without guessing through qualifier gaps.

4 operation steps
Part relationshipsNeeds a live retest
lookup_part_interchangesInterchanges

Return only explicit PIES interchange relationships and validate a bounded candidate set through identity, category, product evidence, and vehicle-verification boundaries.

3 operation steps
Part relationshipsNeeds a live retest
lookup_part_supersessionSupersession

Resolve a starting product and traverse only replaces/replaced-by evidence through a bounded, cycle-safe chain while keeping interchange fallbacks distinctly labeled.

2 operation steps
Vehicle discoveryNeeds a live retest
decode_vin_and_searchVIN search

Validate and decode a VIN, preserve every returned configuration detail, require selection when several vehicles resolve, and optionally bridge into the same bounded part taxonomy/search path.

3 operation steps
Product intelligenceNeeds a live retest
get_part_detailsPart details

Resolve one exact product and expose the selected PIES record: identity, descriptions, unit-bearing attributes, lifecycle, origin, extended information, typed relationships, and classified assets.

2 operation steps
Vehicle discoveryNeeds a live retest
search_parts_by_attributesAttribute search

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

1 operation steps
Product intelligenceNeeds a live retest
compare_partsProduct comparison

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

3 operation steps
02
OptiCat operationsthe raw catalog calls underneath
getAutoCareVehicleResults4 tools
getAutoCareSearchResults12 tools
getAutoCareVersion2 tools
getAutoCareBrandsLastUpdatedDates1 tool
getAutoCareVehiclesByVIN2 tools
getAutoCareVehicleAssets1 tool
getAutoCarePartApplications3 tools
getAutoCarePartDetails5 tools
03
CatalogResponsethe evidence boundary
CatalogResponse26 top-level fields

Outcome, completeness, domain records, clarification, warnings, errors, and an evidence record for every upstream call.

Open the schema
The shared answer format

CatalogResponse: one format, 26 fields, uncertainty included.

Every tool answers in this format. Alongside the results it reports how complete they are, what clarification is still needed, and every upstream call that produced them. Expand any field to inspect its registered type.

Outcome3 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 + completeness3 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 evidence6 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 controls3 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.
Observability2 active
errorCatalogError | null
No nested fields. This value uses the type shown above.
evidenceEvidenceRecord[]
No nested fields. This value uses the type shown above.
Today and next

What you can rely on now—and what we're building.

Confidence is graded per tool against the live catalog, dated 2026-09-16. Nothing here is aspirational: the groups below are today's state, and the work that moves tools up is named.

Live verified0 of 15

This tool has returned correct, evidence-backed answers from the production OptiCat catalog.

You can rely on it today. The live example on its detail page is a real production result, not a fixture.
No tools currently in this state.
Live, with a known boundary0 of 15

The tool works against the live catalog, but one documented limit remains — for example, the account returns only part of a large result set.

You can rely on what it returns. When a boundary is hit, the response says so explicitly instead of pretending the answer is complete.
No tools currently in this state.
Needs a live retest15 of 15

The behavior is implemented and covered by tests, and a fix has landed since the last live run. It keeps this status until an agreed live example passes end-to-end.

Treat its answers as provisional for now. Each tool's detail page names the exact retest that will promote it.
Entity resolver resolve_catalog_entitiesCatalog status get_catalog_statusParts jobs search_catalog_jobCaptured results read_catalog_resultSelected records evaluate_catalog_selectionApplication resources get_vehicle_resourcesVehicle search search_parts_for_vehiclePart applications get_part_fitmentsVerify fitment verify_part_fitmentInterchanges lookup_part_interchangesSupersession lookup_part_supersessionVIN search decode_vin_and_searchPart details get_part_detailsAttribute search search_parts_by_attributesProduct comparison compare_parts
Gaps being closed28 documented gaps across the ten tools

Every tool’s detail page lists its own known gaps, and each one is tracked in the optimization backlog. The highest-priority live retests on the promotion path:

  • Agree ground-truth supersession chains with OptiCat, then retest the GM 19210284 lineage end to end.
  • Prove an entitled, image-bearing product record live and confirm its asset links actually resolve.
  • Rerun the repaired fitment decision for GMB 730-0003 live so verify_part_fitment can leave the retest queue.
Product concepts9 on the near-term list · 14 exploratory

Each tool page pairs its gaps with product concepts—ideas like a readiness history, an application heatmap, or a media and document viewer. Every concept is labeled “Product concept · not implemented” until it ships, so ideas never masquerade as features.

Deferred on purpose1 of 9 catalog operations not wired in

Deferred is a decision, not an omission: these operations stay out of the customer answer path until their entitlement and data-governance rules are approved—and each has a written reason.

getSearchResults

Combines OptiCat and TecDoc data under separate entitlement and provenance rules.

Keep deferred until TecDoc scope, ranking, and data governance are approved.