Take a store off the map. Money is integer minor units (cents). Calling this changes nothing: it returns a preview of what would change and a confirmation link. Only the merchant, on that page, can make it happen.
| Name | Required | Description | Default |
|---|---|---|---|
| store | Yes | The store's name. It leaves the map; the location and its pickup stay. |
Changes observed during successful MCP inspections.
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations present, the description adds real value beyond them by disclosing the two-step preview/confirm model and that the caller cannot effect the change itself. There is mild tension with readOnlyHint=false, but this is resolved if the confirmation-link creation is itself the state change, so it does not rise to a contradiction.
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 mutation-behavior sentences are front-loaded and earn their place, but the money/units sentence is irrelevant to a tool with a single string parameter and reads as copy-paste from another definition, adding confusion rather than value.
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 one-parameter, non-destructive tool with no output schema, the description covers the invocation flow and the limits of the caller's power adequately. It omits whether the removal is reversible and does not point at the complementary store_locator_set tool.
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% and the schema already explains that the store name leaves the map while the location and pickup stay. The description adds no parameter detail of its own, and its 'Money is integer minor units (cents)' sentence refers to a parameter that does not exist here.
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 opening sentence states a specific verb and resource ('Take a store off the map'), which is clearly the inverse of the sibling store_locator_set. It does not name that sibling explicitly, and the stray sentence about integer minor units muddies an otherwise crisp purpose statement.
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?
It clearly explains the context of invocation: calling it produces a preview and a confirmation link, and only the merchant on that page can complete the removal. It stops short of naming alternatives such as store_locator_set for re-adding or store_locator_stores for listing.
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.
