Agent-app MCP server for hou-tea.com — browse / recommend / buy authentic Chinese tea via x402 USDC, with progressive tool discovery, strict JSON Schemas, structured error model, request_id, and next_action hints.
Strong overall quality with comprehensive schemas, clear descriptions, and good composition patterns. Tools follow verb_noun naming conventions and include structured error handling with next_action guidance. The progressive tool discovery pattern (core + extended groups) is well-designed. Main gaps: missing parameter descriptions on a few tools, output schemas not formally documented, and a few parameter names could be more specific. All 10 tools have explicit registration with JSON Schema definitions visible in src/tools/registry.ts.
[meta] Fetch the agent card from /.well-known/agent — describes this MCP's tools, payment scheme, store identity, and available groups. Useful for initial agent discovery and capability negotiation.
Browse the hou-tea Chinese tea catalog. Returns products with name, price (USD/USDC), images, taste profile, fermentation level, season, and a ready-to-render `card` object.
Poll the status of a previously created order. Status transitions: pending_payment → verifying → confirmed (after on-chain USDC settlement). Use exponential backoff (~2s, 4s, 8s …, max ~60s).
Compare multiple products side-by-side (flavor profile, price, origin, brewing). Fetches full details and highlights differences for decision-making.
[meta] Reveal extended tools (compare / health-filter / agent-card) by adding them to tools/list. Optionally filter by `groups` or specific `tools`. Call this when the core 6 tools aren't enough for the user's intent. Idempotent.
Parameter descriptions missing or incomplete on several tools. 'buyer_list_token' (hou_tea_list_my_orders), 'status' (hou_tea_list_my_orders), 'store_id' (hou_tea_compare, hou_tea_filter_by_health), 'budget_max' (hou_tea_recommend), 'category' (hou_tea_browse) lack actionable descriptions. Rubric requires every parameter to have a description so LLMs understand what to pass.
Output schemas not formally documented. While tool descriptions mention what is returned (e.g., 'ranked products with explanation', 'brewing guide'), the actual JSON response structure is not specified in the tool definition. LLMs cannot reliably extract fields or plan downstream calls without knowing response field names and types.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 63 | 2026-07-28+ | v2 |
Returns origin story, brewing guide (water temp, steep time, ratio), health benefits, talking points, cultural context, and cross-sell suggestions for one product.
Filter teas by health attributes / constraints (caffeine, oxidation, allergens, condition-specific wellness). Returns matching products with health-focus tagging and benefit explanations.
Initiate an x402 USDC payment intent for a product. Returns HTTP 402-style payment requirements (recipient address, amount, Base chain network). Auto-includes buyer order grouping (`register_buyer_list_token` or env HOU_TEA_BUYER_LIST_TOKEN). The wallet MCP MUST POST the identical `buy_request_body` on retry plus header `X-Payment`.
List orders linked to the same buyer_list_token (x402-payment-middleware GET /api/v1/buyer/orders). Uses Authorization: Bearer token — no merchant API key.
Get curated tea recommendations from a natural-language query. Returns ranked products with explanation. Best entry point when the user asks 'recommend me a tea for X' or describes a mood / occasion / use-case.
hou_tea_filter_by_health 'conditions' parameter uses illustrative examples in description ('low-caffeine', 'high-antioxidants', 'sleep-friendly', 'anti-inflammatory') but does not formally constrain them to an enum in the JSON Schema. LLMs may hallucinate invalid condition values; the schema should use 'enum' to enforce valid options.
hou_tea_get_payment_requirements uses 'product_name' as a parameter, which is ambiguous and non-idempotent. If multiple products share a name, or names change, the tool may return the wrong price or fail. Should use 'product_id' or 'sku' for determinism and prevent accidental mismatches.
hou_tea_agent_card description does not explain what fields the response contains (e.g., tools[], groups[], payment_scheme, identity, etc.). This is a discovery tool, LLMs need to know what information is available before calling it, and what to expect in the response so they can extract it correctly.
No numeric min/max constraints on 'order_id' (hou_tea_check_order), 'skill_id' (hou_tea_explain), or 'query' (hou_tea_recommend) in their descriptions or schema. While required strings are specified, LLMs have no guidance on valid length or format, risking oversized or malformed inputs.