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

Annotations are readOnlyHint=false and destructiveHint=true, which already indicate mutation and potential data loss. The description adds context: it creates a pending proposal (non-destructive, temporary), requires user approval before confirmation, and mentions no UI button—important for chat context. It doesn't disclose all side effects (e.g., fee effects) in detail, but it adds sufficient value beyond 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 dense but structured logically: it opens with the core action, proceeds to sub-behaviors (fee, description, returns), and closes with a critical MCP note. Every sentence adds value, but the multiple clauses in the first sentence could be split for easier scanning. It's slightly long but well-organized.

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?

Given the tool's complexity (10 params, no output schema, two-step workflow), the description covers the essential context: the proposal lifecycle, parameter dependencies (currency vs. account), and the return value's purpose. It doesn't detail return format or error handling, but it provides enough for an agent to call it correctly. Missing details like date format are in the schema, so this is adequate.

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 80%, so the schema provides robust parameter descriptions. The description adds critical semantics: it explains the 'as-is' vs. 'exchangeRate' behavior, the fee currency and recording as an expense, and clarifies that amounts are in MAJOR units and never pre-multiplied—essential for correct invocation. This goes beyond the schema's basic descriptions, demonstrating high value.

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 clearly states the tool's purpose: 'Propose a transfer between two of the user's accounts'—a specific verb and resource. It details the action (propose, not execute), distinguishes it from record (confirm_proposal), and differentiates it from siblings like propose_asset_convert and propose_transaction. The inclusion of key details (same-currency, cross-currency, fee) adds specificity.

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?

Explicitly states when to use: 'Always include a short user-supplied description; optionally include a fee...' and clarifies the two-step workflow: 'only CREATES a pending proposal; nothing is recorded until confirm_proposal is called.' It also names confirm_proposal as the follow-up and implies when not to use (for executing directly). This is thorough, with clear context and no ambiguity.

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