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

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses what the data actually is: pipeline-computed, not self-reported, over a frozen window, and explicitly non-causal ('says a metric moved, not that the change caused it'). It also defines each verdict's meaning and the harm reporting convention, which is exactly the behavioral context an agent needs to interpret results.

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 core semantics, then cleanly sectioned into Verdicts, Recipes, and Args, so an agent can stop early. It is somewhat long, but each block (verdict glossary, causal disclaimer) earns its space; no padding stands out.

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?

For a 7-param read tool with no output schema, the description covers selection, filtering, pagination, and interpretation semantics well. It does not describe the shape of a returned row beyond the verdict vocabulary, and the cursor's meta.next_cursor is only implied, leaving a small gap.

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?

With schema description coverage at only 14%, the description carries the load and does so: it documents brand_id, the four verdict values with their interpretations, family as a verb-family narrowing, days as a 1-3650 window, limit 1-200 default 50, and cursor as an opaque meta.next_cursor token. Only user_intent is undocumented here, and that one carries its own schema description.

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 opening states a specific verb/resource: measured before-and-after change from completed work, computed by the pipeline. This is distinguishable from siblings like get_changes or get_actions, though the description never explicitly contrasts them, so the agent must infer the boundary from recording semantics.

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 'Common recipes' block gives concrete call patterns ('Did our work pay off', 'What went backwards') that map intent to invocation. It lacks explicit when-not-to-use guidance or named alternatives among the many sibling get_* tools, so it stops short of 5.

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