Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower, and the description still adds a full state machine that annotations cannot express. It discloses that payment instructions may be embedded in the result, that a wallet link is a one-time prerequisite, and that exact-amount sending is required before verification.

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?

A single dense sentence pair that is well front-loaded: purpose first, then the tri-state enumeration in the order an agent will branch on. Every clause carries actionable content, though the long parenthetical for 'payable' slightly compresses readability.

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?

An output schema exists, so return values need not be enumerated, yet the description still explains the one result field that drives behavior (payment.state) and the downstream calls for each value. Nothing an agent needs to invoke this tool and act on its result is missing.

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?

There is only one parameter and the schema already documents it at 100% coverage with a UUID pattern, so the baseline would be 3-4. The description adds only the gloss that a handshake_id refers to an agreed trade, which is minor added meaning.

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 gives a specific verb and resource ('check one Handshake') and defines the domain term ('an agreed trade'), immediately separating it from the sibling list_handshakes. It also states the scope of what is returned ('what your side still needs to do'), so an agent knows this is a single-item status lookup rather than a listing.

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 routes the agent explicitly by state: 'covered' means call confirm_handshake, 'payable' means link_wallet then send then verify_handshake_payment, 'settled' means no action. This is exactly when-to-use-which-alternative guidance tied to a concrete decision variable, with no inference required.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.