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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, but the description adds no reliable behavioral context about what the tool itself does, whether its output is safe to act on, or what side effects occur. Instead it embeds instructions about a different action (place then cancel an order) and an unverifiable claim that 'Pitbi never asks for anything else,' which reads as directive text rather than disclosure. This does not directly contradict the annotations, but it muddies rather than clarifies behavior.

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?

It is short in raw length but poorly structured: the subject (a proof order payload) appears in the first clause and is then abandoned for multi-clause verification instructions and imperatives aimed at the agent. Sentences mix description with commands, so the reader must disentangle what the tool does from what it is being told to do.

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 described, but the description still fails to establish the tool's contract: it never states that api_key identifies the account being proven, nor what the proof is for. For a security-adjacent tool whose description also issues 'GUARANTEED limits' and 'do NOT place it' directives, the omission of who calls it and why is a substantive gap.

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 0% for the single required api_key parameter, so the description was the only place to explain which account key is expected, whether it must match a declared account, or how it relates to the 'declared Decibel account.' It never mentions api_key at all, spending its words on order fields that are not in the schema, so the one real parameter is left entirely unexplained.

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 opening phrase 'The proof order for your declared Decibel account' vaguely gestures at producing a proof payload, but the tool name is prove_account and the schema accepts only api_key, so it never actually says what this tool does or returns. The rest of the text describes a separate order-placement workflow (market_addr, price_units, size_units, time_in_force, client_order_id) that has nothing to do with the single parameter the tool accepts, leaving the agent unsure whether this tool places orders or just emits a proof object.

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 gives procedural instructions ('Place it, cancel it by client_order_id at once') rather than stating when to invoke prove_account versus siblings such as link_portfolio, register_agent, or rotate_api_key. No prerequisites, no trigger condition, and no exclusion criteria are given, so an agent cannot infer the correct call context.

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