Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
This MCP server ecosystem demonstrates significant gaps in definition quality across both the TypeScript (checkout-mcp, core-mcp) and Python (agent orchestration) components. While tool naming follows verb_noun conventions and schemas are partially present, descriptions are generic and lack the specificity required for reliable LLM tool selection. Parameter documentation is inconsistent, many parameters lack descriptions entirely or are overly terse. The ecosystem spans 17 tools across multiple servers, but only 3 tools have descriptions exceeding 50 characters. Most critically, the source code provided shows tool definitions in TypeScript files (cart/index.ts, checkout/index.ts, catalog/index.ts) without visible implementation details for parameter descriptions or output schemas. The evidence.* tools appear to serve an audit/compliance function but lack clarity on when/why to invoke them. Error handling guidance is absent from all tool descriptions.
Generic, minimal descriptions across most tools. 14 of 17 tools have descriptions under 50 characters or lack substantive context. Examples: 'Create a new shopping cart', 'Add item to cart', 'Get brand details from KG' provide no guidance on WHEN to call the tool, WHAT it returns, or HOW it differs from similar tools. LLMs cannot reliably discriminate tool selection with such minimal descriptions.
Parameter descriptions are missing or trivial for evidence.* and checkout.* tools. The 'context' object in evidence.create_snapshot is typed as 'object' with nested properties (user_id, session_id, mission_id, objects) but lacks guidance on what each field means, when they are required, or what their expected values are. The 'consents' object in checkout.create_draft_order has typed boolean properties but no descriptions of what each consent signifies or why acknowledgment is required.
Recommendations
Expand tool descriptions to 50 - 200 characters with clear WHAT/WHEN/WHY guidance. Example: 'Add an item to the shopping cart. Specify the SKU (product variant), quantity, and any selected options (color, size, etc.). Call this after cart.create() to populate the cart before checkout.'
Document output schemas for all tools. For catalog.search_offers, specify: 'Returns: {offers: [{offer_id, title, price, currency, merchant_id, rating, availability_status}], total_count, next_offset}'. This enables chaining.
Add parameter descriptions to nested/object parameters. For evidence.create_snapshot.context, document: 'user_id: the authenticated user making the purchase; session_id: unique session identifier; mission_id: the high-level shopping mission/order ID; objects: contextual data (cart state, selected items, address chosen, etc.)'
Document error modes and recovery guidance in each tool description. Example for checkout.create_draft_order: 'Fails if cart is empty (use cart.add_item first), address is invalid (validate with address service), or shipping option unavailable for destination (check get_availability). Returns HTTP 400 with error code and message.'
Add tool annotations (readOnlyHint, destructiveHint, idempotentHint) to all tools. Mark cart.remove_item and checkout.create_draft_order as destructiveHint=true (irreversible). Mark catalog.* tools as readOnlyHint=true. Mark cart.create as idempotentHint=true (repeated calls with same user_id return same cart).
Clarify the evidence workflow. Add a tool-level comment: 'Evidence tools capture audit/compliance context. Typical flow: create_snapshot() to capture current state, then attach_to_draft_order() to bind evidence to finalized order. For regulatory compliance (PCI, GDPR), evidence is mandatory.'
Spec posture evidence
Inferred effective spec: <=2025-11-25.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Missing or incomplete output schema documentation. While input schemas are visible for all 17 tools, the response/output structure is not documented in the provided tool descriptions. For example, catalog.search_offers is described as returning results but the exact fields (offer_id, price, availability_status, merchant_info) are not enumerated. This forces LLMs to call tools without knowing what to expect, breaking the response-chaining pattern.
Evidence tools (evidence.create_snapshot, evidence.attach_to_draft_order) lack clarity on purpose and workflow. Descriptions do not explain WHEN an agent should invoke these tools, what 'evidence' means in the context of order execution, or how they integrate with the checkout flow. The relationship between create_snapshot and attach_to_draft_order is not documented, should one be called before the other? Are they mutually exclusive with draft order creation?
No error handling guidance in tool descriptions. None of the 17 tools include guidance on what errors might occur, how to recover, or what the LLM should do if a call fails. For example, checkout.create_draft_order might fail if the cart is empty, address is invalid, or shipping option is unavailable, but the description does not hint at these failure modes or recovery steps. This violates the recovery-guide pattern.
Inconsistent parameter naming conventions. catalog tools use destination_country (good, specific), but cart/checkout tools do not accept country as a parameter despite being region-aware (shipping_option_id suggests region-specificity). This inconsistency forces agents to reason about which tools accept which region constraints.
Stateful tool workflows implied but not documented. The checkout flow appears to require: cart.create → cart.add_item(s) → checkout.compute_total → checkout.create_draft_order → evidence.create_snapshot → evidence.attach_to_draft_order. This multi-step dependency chain is not documented in any tool description, forcing the agent to infer the correct sequence or rely on external prompting.
catalog.get_kg_relations uses an opaque 'relation_types' parameter (array of strings with no enum constraint). The description says 'Filter by relation types' but does not enumerate what relation types are valid. This invites hallucinated relation type names and failed calls.
No tool annotations present. None of the 17 tools declare readOnlyHint, destructiveHint, or idempotentHint attributes. This prevents MCP clients from understanding which tools are safe to retry, which require confirmation, or which have side effects. The current MCP spec (2026-07-28) supports tool annotations, they should be used.
Enumerate valid values for open-ended parameters. For catalog.get_kg_relations, constrain relation_types to an enum: ['manufacturer', 'variant_of', 'related_product', 'frequently_bought_together', 'substitute', 'review', 'category_membership']. Align with actual KG schema.
Add step-by-step guidance to complex multi-tool workflows. In checkout.create_draft_order description: 'Prerequisites: (1) cart.create(user_id), (2) cart.add_item(s) with selected SKUs, (3) checkout.compute_total() to finalize amounts. Then call this to create draft order.' This prevents agents from calling tools out of sequence.
Standardize region/country handling. All tools that are region-sensitive should accept destination_country parameter or document regional constraints. E.g., cart.create might default to the user's home country, but should allow override.
Add pagination guidance to catalog.search_offers. Note: 'Results capped at limit=50. Use offset parameter to page through results. limit=1-100 (default 50). Return total_count so client knows if more results exist.'
Document required vs. optional consents in checkout.create_draft_order. Specify: 'consents.tax_estimate_ack (boolean, required): user acknowledges estimated taxes. consents.return_policy_ack (boolean, required): user agrees to return policy. consents.compliance_ack (boolean, optional): user consents to data handling for compliance.'
Add a discovery tool or document for help. Consider adding a tool like 'catalog.help_search_filters()' to enumerate available category_id values, sort options, and brand names. Or document these as separate resources/prompts.