The hou-tea server lets AI agents browse, recommend, and purchase authentic Chinese tea using USDC via the x402 protocol.
Browse & filter the catalog (hou_tea_browse) — Filter teas by category (green, oolong, pu-erh, etc.), price range, season, and brewing difficulty, with full product details including taste profile and images.
Get recommendations (hou_tea_recommend) — Describe a mood or occasion and receive ranked, curated suggestions with explanations.
Deep-dive on a product (hou_tea_explain) — Get origin story, brewing guide (temp, steep time, ratio), health benefits, cultural context, and cross-sell suggestions.
Compare products (hou_tea_compare) — Side-by-side comparison of 2–4 teas across sensory profile, price, brewing difficulty, and use-case.
Filter by health conditions (hou_tea_filter_by_health) — Find teas safe for pregnancy, insomnia, caffeine sensitivity, etc.
Initiate a USDC payment (hou_tea_get_payment_requirements) — Generate an x402 payment intent returning the merchant's Base-chain USDC address and amount for a connected wallet MCP to execute.
Check order status (hou_tea_check_order) — Poll order status from pending_payment through confirmed after on-chain settlement.
View order history (hou_tea_list_my_orders) — Retrieve past orders using a buyer_list_token.
Progressive tool discovery — Core tools are exposed by default; extended tools (compare, health filter, agent card) are revealed on demand.
Fetch agent capabilities (hou_tea_agent_card) — Retrieve the full capability descriptor from /.well-known/agent for diagnostics and API discovery.
Integrates with Coinbase's payments MCP to handle USDC transactions for tea purchases, enabling AI agents to complete on-chain payments for orders initiated through the hou-tea catalog.
Agent-app MCP server for hou-tea.com — let your AI agent browse, recommend, and buy authentic Chinese tea with USDC via the x402 protocol.
Designed for Claude Desktop, Cursor, Cline, Continue, Zed, and any Model Context Protocol compatible AI agent.
v0.3.0-beta - server now ships as an agent app layer, not just a tool list: progressive tool discovery (core + extended), strict JSON Schemas, structured response/error envelopes (
ok,data,error,next_action,meta.request_id), stable error codes, explicit hand-off hints to wallet MCPs, and MCP Apps UI metadata backed by the public@hou-tea/agent-ui-contractpackage. See What changed in 0.3.0 below.
Exposes the hou-tea agent API as MCP tools so your AI assistant can shop on your behalf.
Default tools/list (core + meta) — always visible:
Tool | What it does |
| List tea catalog with filters (category, price, season, difficulty) |
| Natural-language recommendations: "warming tea for cold winter nights" |
| Deep dive on one product: brewing guide, story, health info |
| Initiate x402 payment intent (returns recipient + amount; auto |
| Poll order status after payment |
| List your x402 orders by |
| Reveal extended tools (compare / health-filter / agent-card) on demand |
Extended (revealed after hou_tea_discover_extended):
Tool | What it does |
| Side-by-side comparison of 2–4 candidates |
| Filter by conditions: pregnant, insomnia, caffeine sensitive |
| Fetch full agent capability descriptor (diagnostics) |
Payment is handled by an x402-capable wallet MCP (e.g. @coinbase/payments-mcp) — this server only emits payment intents, it never holds keys or signs transactions.
Related MCP server: l402-kit-mcp
Edit claude_desktop_config.json (Settings → Developer → Edit Config):
{
"mcpServers": {
"hou-tea": {
"command": "npx",
"args": ["-y", "@hou-tea/mcp-server@next"]
},
"coinbase-payments": {
"command": "npx",
"args": ["-y", "@coinbase/payments-mcp"],
"env": {
"EVM_PRIVATE_KEY": "0x..."
}
}
}
}Restart Claude Desktop. You should see "hou-tea" listed under tools.
Add to ~/.cursor/mcp.json or <project>/.cursor/mcp.json:
{
"mcpServers": {
"hou-tea": {
"command": "npx",
"args": ["-y", "@hou-tea/mcp-server@next"]
}
}
}Same npx -y @hou-tea/mcp-server@next invocation in their MCP config.
Hou Tea emits x402 payment requirements, but it does not hold keys or sign
transactions. For agent-native checkout, pair this MCP with an x402-capable
wallet MCP such as @coinbase/payments-mcp:
{
"mcpServers": {
"hou-tea": {
"command": "npx",
"args": ["-y", "@hou-tea/mcp-server@next"]
},
"coinbase-payments": {
"command": "npx",
"args": ["-y", "@coinbase/payments-mcp"],
"env": {
"EVM_PRIVATE_KEY": "0x..."
}
}
}
}Fund the wallet with Base USDC before asking the agent to buy. After the first
successful purchase, copy the returned buyer_list_token into
HOU_TEA_BUYER_LIST_TOKEN so future order history queries stay scoped to the
same buyer identity.
After install, ask your agent:
"Recommend a warming tea for winter nights, around $30."
The agent will call hou_tea_recommend, return real products with prices and brewing notes, then offer to buy.
"I'll take the first one."
The agent calls hou_tea_get_payment_requirements, gets back a 402 with the merchant's Base-chain USDC address and amount, plus a buy_request_body field (includes register_buyer_list_token or your saved buyer_list_token). The retry POST to /pay/api/v1/buy after paying must use that exact JSON body plus the X-Payment header — otherwise buyer grouping breaks. If you've also installed @coinbase/payments-mcp with a funded wallet, configure it to forward the same body. After the first successful purchase, copy buyer_list_token from the JSON response into MCP env HOU_TEA_BUYER_LIST_TOKEN so hou_tea_list_my_orders and future checkouts stay under one identity.
All settings via environment variables (optional):
Env var | Default | Purpose |
|
| Override API host (e.g. for staging). |
|
| Override x402 middleware host. |
|
| Default store_id. |
| (none) | Optional |
| (none) | After first successful |
|
| Set to |
Most users need none of these — the public catalog and x402 buy endpoint are open. For buyer order history, set HOU_TEA_BUYER_LIST_TOKEN once you have it from a confirmed purchase.
The next beta exposes MCP Apps metadata for hosts that can render structured
tool results. The shared UI contract is public:
npm i @hou-tea/agent-ui-contractThe contract currently defines:
Component | Used by |
|
|
|
|
|
|
Tool descriptors include _meta.ui.component, _meta.ui.schemaVersion,
_meta.ui.resourceUri, and _meta.ui.resultMappingId. MCP hosts can read the
matching resource URI and inspect the embedded agent-ui/v1 manifest.
Public discovery:
Agent Card: https://hou-tea.com/.well-known/agent
Agent App docs: https://shop.hou-tea.com/agents
UI schema JSON: https://shop.hou-tea.com/api/agent-ui-contract
Tools do not appear: restart the host app after editing MCP config, then
run npx -y @hou-tea/mcp-server@next --help in a terminal to confirm npm can
download the package.
Payment fails: confirm the wallet MCP is installed separately, the wallet
has Base USDC, and the retry POST uses the exact buy_request_body returned
by hou_tea_get_payment_requirements.
Order history is empty: set HOU_TEA_BUYER_LIST_TOKEN from a confirmed
purchase response. Without it, hou_tea_list_my_orders cannot scope the
buyer safely.
Corporate network blocks npm: install once with
npm i -g @hou-tea/mcp-server@next and point the MCP config command to
hou-tea-mcp.
┌─────────────────┐ ┌────────────────────┐
│ Claude / Cursor │ │ hou-tea.com │
│ │ HTTPS │ /api/agent/* │
│ ┌─────────────┐ │ ──────► │ (catalog/ │
│ │ hou-tea MCP │ │ ◄────── │ recommend/etc.) │
│ └─────────────┘ │ └────────────────────┘
│ │
│ ┌─────────────┐ │ HTTPS ┌────────────────────┐
│ │ payments MCP│ │ ──────► │ /pay/api/v1/buy │
│ │ (Coinbase) │ │ ◄ 402 ─ │ x402-middleware │
│ └─────────────┘ │ │ │
│ │ │ Base │ verifies on- │
│ └─────────┼──────►──┤ chain tx, marks │
│ USDC transfer │ chain │ order confirmed │
└─────────────────┘ └────────────────────┘git clone https://github.com/hou-tea/hou-tea-mcp-server.git
cd hou-tea-mcp-server
npm install
npm run build
node dist/index.js # speaks MCP over stdio
npm run test:unit # offline unit tests (envelope + registry)
npm run test:smoke # live HTTP smoke (hits hou-tea.com)
npm run test:mcp # full MCP stdio smoke (build + spawn)This release adds the public Agent UI protocol layer:
Public MCP Apps manifests. Core buying tools now advertise UI metadata
through _meta.ui, including component name, agent-ui/v1 schema version,
resource URI, and result mapping ID.
Shared npm contract. @hou-tea/agent-ui-contract is published as the
single source of truth for component manifests, TypeScript types, MCP UI
resource names, and result mappings.
Manifest-backed UI resources. MCP resources/read responses now embed
the exact component manifest in HTML so compatible hosts can render product
grids, payment review cards, and order timelines without scraping text.
External discovery surfaces. The Agent Card and public /agents page
point agents and developers to npm packages, schema JSON, MCP install
snippets, and wallet pairing instructions.
This is a next-tagged beta; install with:
npm i @hou-tea/mcp-server@next
# or, in MCP config: "args": ["-y", "@hou-tea/mcp-server@next"]The 0.1.x line keeps working - tool names are unchanged, but the next beta
adds structured envelopes, progressive discovery, and UI metadata.
Anthropic's Skills + MCP guidance pushes MCP servers from "a flat list of tools"
toward an agent app layer: progressive discovery, strict schemas,
program-friendly responses, and explicit hand-off to other MCPs.
This release brings that posture to @hou-tea/mcp-server:
Progressive tool discovery. Default tools/list returns 6 core tools
hou_tea_discover_extended. Extended tools (hou_tea_compare,
hou_tea_filter_by_health, hou_tea_agent_card) are revealed on demand.
Calling an extended tool before discovery returns a structured error:
{ "ok": false,
"error": { "code": "extended_not_revealed",
"retryable": true,
"hint": "Call hou_tea_discover_extended …" } }Structured envelope on every call.
{
"ok": true,
"data": { /* tool payload */ },
"next_action": [
{ "tool": "hou_tea_explain", "reason": "...", "args_hint": { "skill_id": "..." } }
],
"meta": { "request_id": "req_…", "tool": "hou_tea_recommend",
"took_ms": 412, "server_version": "0.2.0-beta.0" }
}Errors share the same envelope with ok: false and a stable error.code
(bad_request, unauthorized, not_found, conflict, timeout,
rate_limited, server_error, network_error,
missing_buyer_list_token, extended_not_revealed, unknown_tool,
internal_error). Each error also carries retryable and a hint.
Strict JSON Schema. Every inputSchema sets
additionalProperties: false, with required, enum, pattern,
minItems / maxItems etc. — so agent-side validators can rely on it.
Hand-off hints to wallet MCP. hou_tea_get_payment_requirements
returns the 402 buy_request_body plus a next_action block that points
the agent to an x402 wallet MCP (e.g. @coinbase/payments-mcp) and then
back to hou_tea_check_order.
Traceability. Every response carries meta.request_id so you can
include it in support tickets / logs.
This is a next-tagged beta; install with:
npm i @hou-tea/mcp-server@next
# or, in MCP config: "args": ["-y", "@hou-tea/mcp-server@next"]The 0.1.x line keeps working — tool names are unchanged, only the result
shape and the default tools/list size are different.
Chinese tea has 1500+ years of cultural depth and a global market larger than coffee. But until now, AI agents either (a) hallucinated product names from training data, or (b) failed to scrape JavaScript-rendered storefronts. This MCP gives agents a direct, authoritative, agent-native path to a real catalog with real prices and real on-chain settlement.
If you're building an AI shopping agent, a tea recommendation app, or just want your Claude to be able to actually buy you tea — this is for you.
MIT © hou-tea
[core] 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.
| Name | Required | Description | Default |
|---|---|---|---|
| category | No | ||
| price_min | No | ||
| price_max | No | ||
| season | No | ||
| difficulty | No | ||
| per_page | No | ||
| page | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It describes return fields but fails to disclose behavioral traits such as read-only intent, idempotency, rate limits, or any side effects, leaving the agent uncertain about safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no extraneous words, front-loaded with '[core]', and efficiently conveys the tool's primary function and output.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no output schema, and no annotations, the description is severely incomplete. It lists return fields but provides no parameter guidance, pagination details, or behavioral context, leaving major gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, requiring the description to compensate. The description omits any explanation of the 7 parameters (category, price_min, etc.), leaving the agent without guidance on how to use them for filtering.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's verb ('Browse') and resource ('hou-tea Chinese tea catalog'), and lists specific return fields (name, price, images, etc.), distinguishing it from siblings like hou_tea_recommend which suggests recommendations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for general browsing of the catalog but does not specify when to use this tool vs alternatives like hou_tea_discover_extended, nor provides exclusions or when-not-to-use scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[core] 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).
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses status transitions and backoff strategy, but omits potential side effects or authentication needs. It adds value beyond schema but is not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, 37 words, front-loaded with purpose. No wasted words, efficient structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool (1 param, no output schema, no annotations), the description covers status transitions and polling strategy, but could mention what the response contains to be fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter order_id is not described beyond its existence. With 0% schema description coverage, the description should compensate but adds no detail about the parameter's format or semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Poll' and resource 'status of a previously created order', distinguishing it from sibling tools like hou_tea_browse or hou_tea_explain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use (polling order status) and explicit timing advice (exponential backoff), but does not explicitly mention when not to use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[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.
| Name | Required | Description | Default |
|---|---|---|---|
| groups | No | Reveal all tools in these groups. Default: ['extended']. | |
| tools | No | Reveal a specific subset of extended tools by name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility. It discloses that the tool modifies the tool list, states it is idempotent, and marks it as a meta operation. This is good but could be more detailed about side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (two sentences) and front-loaded with the key purpose. Every sentence earns its place with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (2 optional parameters, no output schema) and high schema coverage, the description covers purpose, usage scenario, behavior (idempotent), and parameter filtering options. It is complete for the intended use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% as both parameters have descriptions. The tool description adds 'Optionally filter by groups or specific tools,' which mostly restates the schema. Baseline 3 is appropriate since no significant extra meaning is added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Reveal extended tools' and provides specific examples (compare / health-filter / agent-card). It explicitly distinguishes from the 'core 6 tools' mentioned, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a clear usage trigger: 'Call this when the core 6 tools aren't enough for the user's intent.' It does not explicitly mention when not to use it, but the context is sufficient for an agent to decide appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[core] Returns origin story, brewing guide (water temp, steep time, ratio), health benefits, talking points, cultural context, and cross-sell suggestions for one product.
| Name | Required | Description | Default |
|---|---|---|---|
| skill_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It lists the types of information returned but does not mention that the tool is read-only or that it does not modify data. For a 'return' tool, this is sufficient but not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with a bracket marker and effectively lists key content. While not extremely concise due to the enumeration, there is no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a single required parameter and no output schema, the description adequately summarizes the output content. However, it fails to explain the parameter and does not provide any behavioral context beyond the content list.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the 'skill_id' parameter. It only says 'for one product' without connecting it to the parameter. The agent is left to guess that skill_id identifies the product.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Returns') and clearly states the resource (origin story, brewing guide, health benefits, etc. for one product). It distinguishes from siblings like hou_tea_browse (listing) and hou_tea_recommend (suggestions) by focusing on detailed explanation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when detailed info on a single product is needed, but it does not explicitly state when to use this tool versus alternatives like hou_tea_discover_extended or hou_tea_recommend. No when-not guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[core] 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.
| Name | Required | Description | Default |
|---|---|---|---|
| product_name | Yes | ||
| unit_price | Yes | Decimal string e.g. '30.00' | |
| quantity | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the tool initiates a payment intent, auto-includes buyer order grouping, and requires the wallet to POST the identical request body with an X-Payment header on retry. It does not mention side effects or error cases but provides key behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (3 sentences) and front-loaded with the core purpose. Each sentence adds value, covering initiation, return details, and wallet action. Slightly technical but no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description adequately explains the return (payment requirements) and required follow-up. However, it lacks error handling, output format, and success/failure behavior, leaving gaps that an agent might need.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33%, with only unit_price having a description. The description does not mention any parameters, failing to compensate for the low coverage. Parameters like product_name and quantity have no description in either schema or description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool initiates an x402 USDC payment intent for a product, returning payment requirements with recipient address, amount, and network. This distinguishes it from sibling tools like hou_tea_browse and hou_tea_check_order, which handle browsing or order checking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives. While the purpose implies it's for initiating payment, there is no mention of prerequisites or when to use other tools like hou_tea_recommend or hou_tea_explain.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[core] List USDC/x402 orders associated with the buyer_list_token (returned from a successful purchase or stored in env HOU_TEA_BUYER_LIST_TOKEN). No merchant API key required.
| Name | Required | Description | Default |
|---|---|---|---|
| buyer_list_token | No | ||
| status | No | ||
| limit | No | ||
| offset | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It mentions the operation is a list (read) and authentication requirement, but it doesn't clarify error handling, pagination behavior, or any side effects, which is insufficient for a tool with four parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. It includes a useful [core] tag and front-loads the purpose. It could be slightly more structured but is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero schema descriptions and no output schema, the description is too brief. It omits return format, pagination details, error cases, and parameter constraints. A more complete description is needed for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should explain parameter meanings beyond names. Only buyer_list_token is hinted at in the description; status, limit, and offset are not explained. This is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists orders associated with a buyer list token, specifying the resource and filter. However, it doesn't differentiate from sibling tools like hou_tea_check_order or hou_tea_browse, which could help an agent decide which tool to use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when to use it (after successful purchase, token from env) and notes no merchant API key is required. But it doesn't give explicit guidance on when not to use it or mention alternatives, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[core] 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.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| budget_max | No | ||
| occasion | No | ||
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must fully disclose behavioral traits. It mentions 'curated' and natural-language processing but does not state whether the tool is read-only, if it modifies any state, or if any permissions/authentication are needed. The behavior beyond the basic purpose is insufficiently described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the core purpose and provide usage context. No unnecessary words; every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description covers the basic function and typical use case but omits details about parameters (especially budget_max and occasion) and the exact return format beyond 'ranked products with explanation'. It is minimally complete but could be enhanced.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. Only the query parameter is implicitly described as a natural-language query. The remaining parameters (budget_max, occasion, limit) are not explained, leaving the agent to infer meaning solely from parameter names and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it provides tea recommendations from a natural-language query and returns ranked products with explanation. It distinguishes itself from sibling tools like hou_tea_browse (general browsing) and hou_tea_discover_extended (extended discovery) by focusing on personalized recommendations and being the best entry point for recommendation requests.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly indicates it is the best entry point when the user asks for a recommendation or describes a mood/occasion/use-case. While it does not mention when to avoid this tool, it provides clear context for its use relative to other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool serves a unique function: browsing catalog, checking orders, discovering extended tools, explaining products, initiating payment, listing orders, and recommending teas. No functional overlap exists.
All tools follow the 'hou_tea_verb_noun' pattern in snake_case, e.g., hou_tea_browse, hou_tea_check_order, hou_tea_discover_extended. Naming is uniform and predictable.
With 7 tools, the surface is well-scoped for a tea e-commerce server covering browsing, recommendations, explanations, payments, and order management. No excess or deficiency.
The core workflow of browse, recommend, explain, pay, and track orders is covered. However, there is no explicit order creation tool (though payment initiation implies it) and missing cancellation/update capabilities, which are minor gaps.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Agent-commerce MCP server for x402/USDC payments and affiliate splits on Base.
MCP server for Boson Protocol — on-chain agentic commerce for physical & digital goods.
Monetize any MCP server: x402 paywall, pay-per-call billing in USDC on Base, agent marketplace.
Hosted AgentLux MCP server for marketplace, identity, creator, services, and social flows.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/jackrain19743/hou-tea-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
