Email a payment link. 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 |
|---|---|---|---|
| note | No | A line from the shop, printed above the button. | |
| orderNumber | Yes | The human order number, e.g. 1003. |
Changes observed during successful MCP inspections.
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds real context beyond the annotations: it explains that the call produces a preview plus a confirmation link and that the merchant must act on that page for anything to happen — a two-phase commit an agent could not read off readOnlyHint=false / idempotentHint=false. There is mild tension between "changes nothing" and readOnlyHint=false/idempotentHint=false (emails are still sent, so repeat calls are not free), but it is not a clean contradiction since the claim is scoped to store data.
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?
Four short sentences, front-loaded with the action and then the crucial caveat about what the call actually does. The money-units sentence is the one piece that does not earn its place in this tool's context.
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?
With no output schema, the description correctly takes on the burden of describing the return (a preview of changes plus a confirmation link) and the human-in-the-loop step. Missing elements are minor: no statement of what the customer email contains or whether repeated calls send duplicate emails.
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%, so the schema already documents both parameters (orderNumber as human order number, note as a line printed above the button), making 3 the baseline. The description's only numeric guidance — "money is integer minor units (cents)" — does not apply to any parameter this tool actually takes, so it adds no parameter meaning 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 first sentence states a specific verb+resource ("Email a payment link") and the rest clarifies the two-phase nature of the operation, which distinguishes it from siblings like orders_mark_paid or orders_note. It does not name any sibling explicitly, so an agent must still infer the boundary itself.
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?
Usage is implied rather than stated: the schema description says the link is for an "unpaid order," so the precondition is discoverable, but the tool description itself gives no when-to-use / when-not guidance and never points to orders_mark_paid or other payment alternatives. Minimum viable.
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.
