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

Annotations only declare readOnlyHint=false and openWorldHint=true, which are minimal. The description takes on the full burden and exceeds it: it discloses that the operation is atomic ('one transaction'), affects future trades (active listings paid to new wallet, past purchases stay verified), is idempotent (calling again with same wallet is not an error and re-checks history), and notes that no seller-written text appears in the reply. It also mentions conflict behavior (wallet registered to another profile) and the refusal path. This is rich behavioral context beyond the annotations.

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 description is long but every sentence carries essential information. It opens with the core purpose, then flows through prerequisites, atomicity, idempotency, and reply content. There is no filler or redundancy. The structure is logical and front-loaded with the most critical constraints (what's required) before side effects and idempotency details.

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 complex tool with 4 parameters, nested objects, no output schema, and significant side effects, the description covers everything an agent needs: prerequisites, failure modes (refusals, conflicts), atomicity, idempotency semantics, and scope of effect (future trades vs. past settlements). It even addresses edge cases like calling again with the same wallet. Nothing essential 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?

Schema coverage is 100%, so the schema already documents parameters. The description adds substantial meaning: it explains the challenge object's origin and signing requirement, clarifies that wallet_proof must use purpose update_wallet and subject profile_id, and details idempotency_key's behavior (same key on retry returns original result, different input conflicts, and secret-bearing replies shown once). It also warns that the API key alone is refused with a specific reason. This goes far beyond the schema's field descriptions.

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 states a specific verb ('Move your profile to a new wallet address') and a clear resource (profile wallet). It also distinguishes from related tools like rotateKey by explaining the migration context (key migration or compromised wallet key), which is not covered by any sibling. The purpose is unambiguous and actionable.

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 description explicitly lists required prerequisites: API key, signed challenge from getChallenge, and wallet_proof signed by the new wallet key. It states that missing either is refused, giving clear conditions for use. It does not explicitly name alternatives (e.g., rotateKey for key rotation without address change), but the context and prerequisites strongly imply when this tool is appropriate. The idempotency behavior and re-checking on repeat calls provide additional usage nuance.

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