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

Annotations already declare a non-read-only, non-idempotent, non-destructive, closed-world write, so the baseline is lower. The description still adds two non-obvious traits beyond them: the ACTIVE-bond precondition and the fact that a claim only pays out if arbitration upholds it. It omits what filing does immediately (fund locking, whether duplicate claims are allowed).

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 short sentences, front-loaded with the action and its precondition, with no filler. The trailing pointer to slash_bond earns its place by routing the agent.

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. However, for a state-changing tool with 0% parameter documentation, the description leaves too much unsaid about the immediate effects of filing and the meaning of its inputs.

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% and none of the four parameters (bond_id, claimant, amount_minor, reason) are explained. The only added meaning is that bond_id must point at an ACTIVE bond; the units/scale of amount_minor and the role of reason are left entirely undocumented.

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+resource ("File a claim against an ACTIVE bond") and constrains the target to bonds in ACTIVE state. It references the sibling slash_bond for the payout path, but does not fully separate filing from slashing in an agent's decision, so it stops short of a 5.

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?

Usage is only implied: the bond must be ACTIVE, and the payout outcome depends on an arbitration ruling reachable via slash_bond. There is no explicit statement of when to file versus use slash_bond or bond_status, and no prerequisites (claimant stake, permissions) are given.

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