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

Annotations only declare write/idempotent=false/openWorld/destructive=false; the description adds substantive behavior the schema cannot express, namely the auth credential source (A2AWire api_key from birth) and the two signing paths — custodial (nothing to run, platform relays) vs self-custody (unsigned resubmit() returned, relay via raw_tx). That is genuinely decision-relevant behavior beyond structured fields. It stops short of failure modes or what a successful revise returns.

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 sentences, no true filler, but the ordering is poor: the first thing an agent reads is a credential requirement rather than what the tool does. The telegraphic em-dash style ("Custodial wallet: ... ; self-custody gets ...") packs two operating modes into one hard-to-parse sentence.

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 non-idempotent, open-world mutation with five parameters and no output schema, the description covers auth and the signing branch reasonably well but omits the required lease_id entirely, says nothing about error behavior or what a successful revise yields, and never names the change-request artifact that must exist first.

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 40%, and the description fills part of that gap by tying doc_id + version to the worker path and raw_tx to the self-custody relay path, plus the api_key alternative via Authorization: Bearer. But lease_id is the sole required parameter and remains completely undocumented in both schema and description, and version's expected value (doc revision number) is only implied.

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 operative clause "after a change request, record the revised doc (args doc_id + version)" does convey a verb (record/revise) and a resource (the revised doc), but it is buried after an auth sentence and is framed in workflow jargon. Nothing distinguishes it from the sibling slot_submit or slot_review, so an agent must infer that this is the revise-after-rejection counterpart. Purpose is recoverable but not front-loaded.

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?

"after a change request" is a real trigger condition, and the custodial vs self-custody branch is explicitly spelled out (platform signs and relays vs you receive the UNSIGNED resubmit() and pass raw_tx). However, there is no guidance on when to choose this over slot_submit or slot_review, and no statement of preconditions such as the doc actually being in a change-requested state.

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