Use normal language, catalog terminology, shorthand, or a follow-up question.
The wording is input, not catalog proof.Same catalog. A stronger boundary between data and answer.
Customers ask for an outcome, not an API operation. The language layer identifies the task; the MCP service retrieves and validates OptiCat evidence; the assistant explains only what that evidence supports.
Sequence diagram
How a customer sentence becomes a supported answer
The model interprets language. The service establishes catalog truth. Keeping those responsibilities separate is what makes the experience both fast and dependable.
01 · Customer Ask for an outcome02 · Host model Interpret intent and entitiesNormalize synonyms, formatting, and low-risk language variation; identify what remains ambiguous.
The model may interpret the request but may not create a vehicle, part, fitment, or relationship fact.03 · Task-level MCP Choose the customer taskCall vehicle search, VIN, fitment, interchange, supersession, or details—not a raw endpoint-shaped workflow.
Tool selection follows intent; tool output remains typed and reviewable.04 · OptiCat adapter Orchestrate API operationsResolve identity, retrieve required records and pages, and classify entitlement, empty, partial, and unavailable states.
Only current entitled API responses establish catalog truth.05 · Evidence gate Preserve and validateKeep totals, qualifiers, lifecycle, relationships, assets, warnings, and evidence attached to the record they govern.
Every firm claim needs matching evidence; incomplete retrieval cannot prove absence.06 · Assistant Answer, clarify, or abstainExplain supported results quickly, ask one material question, or state why the evidence is insufficient.
The final answer cannot add catalog claims that were absent from the tool result.
Data flow diagram
What may be interpreted- Intent and requested journey
- Synonyms and normal customer wording
- Punctuation and low-risk formatting
- Which returned ambiguity needs a question
API interaction diagram
What requires current evidence- Vehicle and exact part identity
- Fitment, qualifiers, and application notes
- Interchange, supersession, and lifecycle
- Completeness, entitlement, assets, and errors
NL
Different wording, the same supported task
Users do not need to know endpoint names, brand codes, base-vehicle IDs, or call order.
“brake pads for a 97 Mustang”
“need frt pads, stang 97”
“disc pads for my 1997 Ford Mustang”
search_parts_for_vehicleResolve the same vehicle/part task, then ask only for a returned qualifier that changes the products.
“what cars use Bosch 9619?”
“applications for 9619 by Bosch”
“will this plug fit my car?”
get_part_fitments / verify_part_fitmentResolve exact identity, preserve applications and conditions, then answer yes, no, conditional, or unverified.
“what replaces GM 19210284?”
“is there a newer number?”
“show a successor and aftermarket equivalents”
lookup_part_supersession / lookup_part_interchangesKeep lifecycle replacement and interchange as separate evidence-backed relationships.
Architecture diagram
The answer boundary moves into the service
The catalog foundation stays. Identity, completeness, errors, and evidence become portable controls that every host receives.
Three states, three different evidence labels
Original is reconstructed from supplied source and deployment artifacts. Current is implemented, with tool-level proof shown below. Customer-trial controls are planned and are not presented as production-ready.
Original POCA sound connection with a lossy answer boundary
Reconstructed from sourcePython, FastMCP, and direct OptiCat access were sensible choices. The risk appeared after retrieval, where deployment-specific tools shortened rich catalog responses into prose for the host model to interpret.
- 01Host agent
A separately installed prompt chose and sequenced tools.
- 02Drifting tool surfaces
16 FastMCP tools, 16 Lambda schemas, and a seven-tool gateway binding.
- 03Tool-local request logic
Each function assembled OptiCat calls and selected fields itself.
- 04OptiCat operations
The source catalog often returned richer identity and fitment data.
- 05Prose result
Caps, qualifiers, lifecycle, and error distinctions could disappear before the model answered.
Verification-first POCOne structured contract around catalog evidence
Implemented todayThe current web experience routes a customer request through a versioned remote MCP contract. Identity, paging, qualifiers, relationships, and failure classes are handled before the model explains the result.
- 01Question + context
The planner extracts intent and carries customer-selected identities across turns.
- 02Health + contract gate
The web app checks reachability, commit, and contract compatibility.
- 03Streamable HTTP MCP
The primary path calls one of eight task-shaped, read-only tools.
- 04Resolution + API budget
Shared resolvers and the OptiCat client own exact identity, calls, paging, and time limits.
- 05Normalization + validation
The service preserves qualifiers, lifecycle, typed relationships, errors, and completeness.
- 06Qualified answer + trace
Structured evidence becomes the customer answer and a redacted operational record.
Customer-trial architectureThe same verification core with operating controls
Planned — not implementedCustomer trials do not require a larger data platform. They require authorized partner access, one supported MCP surface, entitlement visibility, monitoring, release ownership, and a controlled correction loop.
- 01Authorized partner hosts
Named partners and approved assistants enter through scoped access.
- 02Partner + entitlement policy
Identity, catalog scope, VIN access, and limits are known before lookup.
- 03One canonical MCP contract
Every host sees the same versioned tools and evidence rules.
- 04Existing verification core
Resolvers, adapter, normalizers, and validation gates remain the center.
- 05Operational evidence
Version, latency, entitlement drift, failures, and releases are monitored.
- 06Support + controlled change
Corrections have an owner, an audit trail, and a tested release path.
Why
Why MCP is the right boundary for this catalog
MCP is useful here because the domain has exact read-only jobs, a source-of-truth API, and claims that must remain tied to returned evidence.
Natural language needs a bounded action layer
People ask in ordinary automotive language; MCP turns that request into a small set of exact catalog jobs instead of giving the model open-ended data access.
The work is naturally read-only
Search, decode, verify, and relationship lookups have clear inputs and low-risk side effects—the shape MCP tools handle well.
OptiCat stays the source of truth
The service calls the catalog directly. A vector database, copied inventory, or parallel retrieval platform would add drift without fixing fitment correctness.
One boundary can serve many hosts
The evidence rules travel with the MCP server, so a different model or interface cannot silently redefine completeness, identity, or fitment.
Every answer can be tested
Structured status, totals, qualifiers, warnings, and operation evidence make the path repeatable, inspectable, and suitable for a release gate.
Right-sized by design. OptiCat remains the catalog of record. The architecture does not need a vector database, a copied parts index, a workflow engine, or multiple agents to make these five journeys dependable.
Flow
Five requests, shown across all three versions
Open any journey to see the original tool path, the current MCP gates and evidence, and the operating controls required for customer trials.
01Customer request · “brake pads for a 1997 Ford Mustang”Vehicle → parts
Turn readable vehicle and part language into qualified, paged catalog candidates.
search_parts_for_vehicle
Vehicle → parts
Turn readable vehicle and part language into qualified, paged catalog candidates.
search_parts_for_vehiclesearch_parts_by_vehicle- 01Resolve by substring
Make and model facets stopped at the first plausible match.
- 02Search one page
The tool requested 20 parts and rendered only the first 10.
- 03Return prose
Some facet hints survived, but IDs, continuation, and per-part evidence did not.
- 01Resolve exact identities
Vehicle and part-type resolvers return one identity or catalog-backed choices.
- 02Search with scoped filters
Brand, attributes, ACES qualifiers, and customer selections stay in the request.
- 03Return candidates + boundary
Parts, open qualifier dimensions, total, returned count, paging, and evidence share one contract.
- 01Apply partner scope
Catalog entitlement and request limits are known before retrieval.
- 02Measure configuration coverage
Trials monitor which vehicle and qualifier combinations are answered or deferred.
- 03Release against approved cases
No change ships if it reintroduces unsupported candidates or silent truncation.
Evidence today
Vehicle IDs, part type, position, submodel, engine, paging, and completeness remain visible. The live path returned 208 matches, 50 rows, and real Sub Model choices.
02Customer request · “hvac filter for VIN 4T1BK1EB5GU235558”VIN → vehicle → parts
Decode one vehicle identity and continue the same request into the requested part search.
decode_vin_and_search
VIN → vehicle → parts
Decode one vehicle identity and continue the same request into the requested part search.
decode_vin_and_searchget_vehicles_by_vinsearch_parts- 01Decode in one tool
The host received vehicle prose from get_vehicles_by_vin.
- 02Compose a second tool
The host had to carry the inferred identity into a general part search.
- 03Depend on host judgment
VIN entitlement and missing configuration fields were not a shared response state.
- 01Validate + classify access
VIN syntax and key entitlement are checked without turning denial into no vehicle.
- 02Preserve the decode
Every returned non-base-vehicle field remains in structured metadata.
- 03Continue safely
One resolved base vehicle flows into the requested part type; multiple matches pause for clarification.
- 01Track VIN entitlement
Partner scope changes are visible before customer requests fail.
- 02Monitor decode fidelity
Trials compare returned configuration detail with the answer that reaches the user.
- 03Own incomplete decodes
Support can distinguish catalog limits from code or partner configuration issues.
Evidence today
VIN status, baseVehicleId, returned configuration fields, entitlement, and part-search continuation remain distinct. The VIN decoded live to a 2016 Toyota Avalon; the repaired continuation needs retest.
03Customer request · “What cars does Bosch 9619 fit?” · “Does GMB 730-0003 fit a 2013 Chevrolet Impala?”Part → fitment
Support both application browsing and an exact part-plus-vehicle decision without flattening qualifiers.
get_part_fitmentsverify_part_fitment
Part → fitment
Support both application browsing and an exact part-plus-vehicle decision without flattening qualifiers.
get_part_fitmentsverify_part_fitmentget_part_applicationscheck_part_fitment_for_vehicle- 01Retrieve applications
The browse tool rendered the first 10 rows regardless of the requested page size.
- 02Flatten fitment
Vehicle names and quantity survived while position, engine, notes, IDs, and paging could disappear.
- 03Let prose imply certainty
The host had to decide whether a partial row set proved that a part fit.
- 01Resolve part and vehicle
Exact product identity and exact vehicle identity are established independently.
- 02Compare ACES evidence
Requested qualifiers are matched with catalog synonyms; missing dimensions stay unevaluated.
- 03Return a bounded decision
Browse returns qualified applications; verify returns yes, no, conditional, or unverified with its evidence.
- 01Calibrate negative coverage
Customer trials measure when complete evidence is sufficient for a definitive no.
- 02Monitor qualifier drift
Changes in position, engine, trim, or drive data become release signals.
- 03Escalate disputed fitment
A named catalog owner adjudicates data-versus-code disagreements.
Evidence today
Applications retain vehicles, qualifiers, quantity, notes, and completeness; exact verification returns yes, no, conditional, or unverified. Bosch 9619 correctly remained partial at 50 of 93 rows.
04Customer request · “Show interchanges for Akebono EUR1924”Part → interchange
Preserve a useful catalog relationship without turning it into an unsafe equivalence or fitment claim.
lookup_part_interchanges
Part → interchange
Preserve a useful catalog relationship without turning it into an unsafe equivalence or fitment claim.
lookup_part_interchangesget_part_cross_references- 01Accept supplied identity
The tool required a brand code and number before reading part details.
- 02Format relationship rows
Cross-references were returned as prose without a shared validation envelope.
- 03Leave equivalence to the host
Interchange, compatible specification, and vehicle fitment could be conflated downstream.
- 01Resolve the complete source
Ambiguous number, brand, and product type combinations return choices first.
- 02Read typed relationships
OE and other relationship kinds remain labeled and preserve direction.
- 03Validate bounded targets
Category and comparable attributes are checked; vehicle application remains a separate requirement.
- 01Approve relationship policy
Partners see which relationship kinds may support which customer language.
- 02Measure target validation
Trials expose unvalidated candidates rather than hiding them beyond a cap.
- 03Keep fitment separate
Release tests prevent interchange from becoming an install recommendation without vehicle proof.
Evidence today
Source identity, typed relationship, target category/specification checks, and remaining validation are returned separately. Akebono EUR1924 returned ten direct relationships in live proof.
05Customer request · “What supersedes GM 19210284?”Part → supersession
Explain lifecycle and directional replacement evidence without relabeling a plain interchange.
lookup_part_supersession
Part → supersession
Explain lifecycle and directional replacement evidence without relabeling a plain interchange.
lookup_part_supersessionget_part_supersession- 01Read part details
The function pulled replaces and replacedBy arrays for a supplied identity.
- 02Format separate lists
The host received human-readable relationship prose without shared lifecycle semantics.
- 03Handle gaps conversationally
A missing successor could be treated like an active part or be filled from interchange evidence.
- 01Resolve exact lifecycle identity
The source part is established before any relationship claim.
- 02Traverse a bounded chain
Replaces and replaced-by direction are preserved with cycle detection and a hop limit.
- 03Label weaker evidence
Interchange-family evidence is a fallback only; missing explicit succession remains partial.
- 01Adjudicate lifecycle policy
Catalog owners approve what counts as explicit replacement evidence.
- 02Monitor chain changes
Replacement direction and cycles are checked as catalog versions move.
- 03Control customer wording
Trials prevent candidates or plain interchanges from being called the replacement.
Evidence today
Lifecycle, replaces/replaced-by direction, explicit relationship count, fallback kind, cycle protection, and a bounded chain remain visible. The explicit live chain still needs domain-approved retest proof.
Core
Two supporting tools complete the eight-tool surface
Readiness establishes whether a lookup can be trusted; product details preserve the complete record and its resources.
get_catalog_statusNeeds a live retestNo equivalent model-facing readiness contract separated accepted access, entitlement, and upstream availability before catalog work.
Probes catalog version, non-secret brand scope, and VIN entitlement, returning typed access or availability states instead of an empty catalog.
Scheduled readiness and entitlement history warns operators before partner conversations regress.
get_part_detailsLive, with a known boundaryThe tool returned a shortened overview: three descriptions, five attributes without units, relationship counts, and no dependable asset delivery.
One exact identity returns selected descriptions, attributes with units, lifecycle, typed relationships, origin, and usable part resources.
Customer trials monitor asset availability and product-field fidelity by catalog version and partner scope.
Why
Where the design changes customer outcomes
The same six changes apply across the journey-specific flows above.
Before → after → why the change is necessaryCross-journey synthesis
Before
The host model chooses the first plausible identity
After
The resolver returns one exact identity or a small set of real choices
Why
Prevents similar part numbers, brands, trims, and product categories from being silently mixed.
Before
Each tool formats its own shortened prose
After
Every tool returns the same structured evidence and completeness envelope
Why
The model can see totals, caps, warnings, qualifiers, and what remains unknown.
Before
Fitment is inferred during conversation
After
A dedicated verification gate returns yes, no, conditional, or unverified
Why
A definitive answer is allowed only when the vehicle and application evidence support it.
Before
Unavailable, not entitled, and zero results can look alike
After
The API adapter classifies each state before the assistant responds
Why
A service problem is never described as proof that a part or vehicle does not exist.
Before
Interchange is treated as one relationship lookup
After
Identity, category, relationship, product evidence, and vehicle application are checked in sequence
Why
A catalog relationship remains useful evidence without becoming an unsafe equivalence claim.
Before
Safety depends on one host prompt
After
The MCP server enforces the evidence boundary for every host
Why
The result remains dependable when the model, interface, or deployment changes.
Inspect every current contract
Open the MCP Tool Atlas The MCP Tool Atlas shows exact schemas, OptiCat operations, decision branches, live confidence, known gaps, and example requests for all eight tools.