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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description's added value is the shape of the returned evidence – key changes followed by an hour-by-hour or day-by-day billed-vs-actual comparison – which tells the agent what form the data takes. It does not clarify whether this is a cached retrieval or an on-demand computation, nor any cost/latency implications.

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?

A single sprawling sentence that leads with a purpose clause rather than the operation, and buries the useful detail (hourly/daily billed-vs-actual comparison) mid-sentence. It is information-dense but poorly front-loaded and hard to parse quickly.

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 explained, but for a one-parameter tool with zero schema description coverage the definition should still say what the tool does and when to reach for it. Editors and agents get an atmospheric picture of the evidence without a clear statement of the operation or call conditions.

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 0% and the single required parameter (incident_id) is only labeled 'Incident Id'. The description adds nothing – no mention of which incident to pass, where to obtain the ID (e.g., from list_incidents), or whether the incident must be in a particular state.

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 conveys the resource and its content – an incident's evidence, comprising key changes plus an hourly (or daily) comparison of provider billing against the company's own code, laid out as columns and rows. But it never states an action verb ('returns', 'compiles') and opens with an oblique use-case clause ('What a provider's refund process asks for'), so the agent must infer that this is a read that produces a reconciliation table. It also does nothing to distinguish it from siblings like get_incident, reconciliation_status, or explain_change.

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 only usage signal is the embedded phrase about a 'refund process', which weakly implies dispute/chargeback contexts, but no explicit when-to-use, when-not-to-use, or which sibling to prefer is given. With get_incident and list_incidents available, the agent has no basis for choosing this tool.

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