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

The description contradicts itself on the core action (delete vs create). It does not disclose side effects, idempotency, or safety profile. With empty annotations, the description carries full burden but fails to provide coherent behavioral information.

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 short, but the first two lines are redundant and contradictory, wasting space. The @param structure is useful, but the content is confused, and the return description is vague ('a json object').

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?

Despite having an output schema, the description only says 'a json object', offering no details on the response structure or error behavior. The tool's scope (wallet vs account, deletion semantics) is obscured by contradictions. With four required params and no annotation support, this description is critically incomplete.

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?

The @param lines add some meaning beyond the schema, e.g., explaining that account_fk is a database ID not an address, and beneficiary_id comes from /beneficiary/list. However, account_fk is contradictory ('may not be 0' followed by 'may be 0'), and the explanation of 'account on which the beneficiary is set' is unclear. This does not adequately compensate for the 0% schema coverage.

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 opens with 'Deletes a beneficiary' but the very next line says 'Creates a beneficiary on this wallet or on this account'. These are contradictory actions, making the tool's actual purpose unclear and misleading. No clear differentiation from sibling tools like beneficiary_add.

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?

There is no guidance on when to use this tool vs alternatives. In fact, the false 'Creates a beneficiary' line actively suggests incorrect usage. No mention of prerequisites or scenarios for removal.

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