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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds crucial context beyond them: the exact refusal behavior (CONFLICT with approval_locked: true), the race-safety guarantee ('the lock is pinned into the delete itself'), and the admin+ requirement for the alternative. This is exactly the operational detail an agent needs before invoking a destructive tool.

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?

Three tight sentences with the restriction, the error behavior, and the alternative all front-loaded; no filler, and the most decision-relevant constraint (draft/rejected only) leads.

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?

The description fully covers the safety profile, refusal semantics, and the alternative route for a destructive operation with no output schema — strong coverage for its core purpose. The remaining gap is the unexplained 22-parameter schema, which slightly undersells completeness for such a wide input surface.

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 only 5% across 22 parameters, so the description should compensate — but it says nothing about the parameters. It never explains what the 21 optional fields (status, vendor, amount_cents, etc.) do in a delete call, whether they act as filters or are ignored, or that only 'id' is required. This leaves a major ambiguity unresolved.

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 ('Deletes'), resource ('an expense you created'), and precise scope ('draft and rejected rows only'), which distinguishes it cleanly from siblings like expense_reject or expense_update. An agent can tell exactly what this tool does and on which rows without opening the schema.

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 names when the tool refuses (pending, approved, reimbursed rows) and routes the agent to the correct alternative: 'NEXT: expense_reject it first (admin+) if it must leave the books.' Both the exclusion condition and the alternative path with its permission requirement are spelled out.

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