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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the safety profile is partly covered. The description adds real context beyond that: the report is free, all answers are weighted equally, and it is stored only as an aggregate count with nothing recorded against the case — a meaningful disclosure about data retention and privacy for a write 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?

Front-loaded with the action and the enum values, then two short sentences on cost and retention. The third sentence is more persuasion than instruction, but it earns its place by justifying why the agent should prompt for this data.

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?

There is no output schema, so the description needn't explain returns, and it covers purpose, trigger, cost and retention well. It is silent on what repeated submissions do (idempotentHint=false), which is a minor gap for a mutation tool whose storage behavior it otherwise goes out of its way to describe.

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 67%, with the outcome enum richly documented in the schema itself and amount_written_off explained there. The description reinforces the outcome concept but adds no semantics for case_id and never mentions amount_written_off, so it does not compensate for the coverage gap. Baseline 3 for partial coverage where the schema does most of the work.

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: 'Record what happened after the patient sent the dispute letter,' and enumerates the possible outcomes. It is unambiguous about what the tool does, though it never explicitly distinguishes itself from siblings like get_case or get_case_outputs (none of which overlap, so the risk is low).

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?

Gives a clear trigger condition — use it after a dispute letter has been sent — and the closing sentence motivates the value ('only these reports show whether saying so to a billing office changes anything'). It stops short of stating when not to use it or naming alternatives, but no sibling covers this use case.

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