recover_customer_keyExplains where a lost customerKey can be found: a key issued with an order is written in the order confirmation email sent to the registered address (each order placed without a key has its own key). For keys that cannot be found there, it points to contact_gyotak. This tool does not look up, verify or send anything.
| Name | Required | Description | Default |
|---|---|---|---|
| phone | Yes | Phone number used at registration |
Changes observed during successful MCP inspections.
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive, closed-world, and the description reinforces this by stating it performs no lookup, verification, or sending — useful context that removes any expectation of a side effect. It leaves one behavioral question open: why a phone number is required if nothing is looked up, which matters for a tool that takes a personal identifier.
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?
Three short sentences: what it explains first, the fallback routing second, the negative scope last. Zero filler and nothing buried.
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?
For a single-parameter, no-output-schema informational tool, the description covers what the agent gets back (an explanation plus a pointer to contact_gyotak) and what it will not get (no lookup or send). The one missing piece is the purpose of the required phone argument, which the description neither explains nor acknowledges.
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 100%, so the phone parameter is already documented as 'Phone number used at registration'; baseline is 3. The description adds no meaning about how the phone is used — and its claim of 'does not look up anything' makes the required identifier's role genuinely unclear rather than merely redundant.
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?
A specific verb and resource are stated: the tool explains where a lost customerKey lives (order confirmation email to the registered address, per-order keys). It also pre-empts the misleading name 'recover' by declaring 'This tool does not look up, verify or send anything,' so an agent will not mistake it for a retrieval tool.
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 usage context is clear: call when a customerKey is lost, and for keys not found in the confirmation email it routes the agent to the sibling contact_gyotak. No explicit exclusion against other plausible siblings such as get_order_history or my_orders, which might also surface order details, so it stops short of full when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.