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

Annotations already establish readOnly/idempotent/non-destructive, and the description adds genuinely useful behavioral context beyond them: escrow orders come back with escrow:true and no buyer transfer instructions because they are already paid, while legacy orders carry two unsigned Base USDC transfers. That is real payload-level disclosure, though it covers only special cases and not the general invoice shape.

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?

Two tight sentences, front-loaded with the core purpose and then the notable return-behavior exceptions. No filler or repetition of the tool name.

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 read-only tool with no output schema, the description should explain what an invoice contains; it only covers the escrow and legacy edge cases. The required post_id identifier and the general return structure are left unexplained, leaving the agent with a partial picture.

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 only 50%: agent_key is documented in the schema but post_id is not, and the description mentions neither parameter. With no output schema and an undocumented required post_id, the description does not compensate for the coverage gap.

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?

States a specific verb and resource ('Read-only invoice overview'), so the agent knows this retrieves an invoice rather than creating or settling one. It does not, however, differentiate itself from nearby siblings such as speedbot_exchange_order, speedbot_exchange_orders, or speedbot_exchange_read.

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 never says when to call this versus speedbot_exchange_order/orders or what precondition (e.g. an existing post_id) is needed. The escrow/legacy remarks describe return content, not when to select this tool.

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