fusion_validate_report

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

Annotations already declare readOnly, idempotent, open-world, and non-destructive. The description adds substantial behavior beyond that: every expectation is evaluated without short-circuiting, the diff is a repair signal, common failure modes map to concrete root causes, and cross_check returns as one failed expectation by design. It also discloses the honest limits about ground-truth consistency and service-account visibility.

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?

The description is long, but the length is justified by the tool's complexity. It front-loads the core purpose, uses bullet lists for failure-mode triage, and ends with a compact Args section. A little trimming of the philosophical framing ('trustworthy rather than merely plausible') would make it tighter, but no sentence is pure filler.

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 validation tool with 6 parameters, no schema-level descriptions, and high behavioral nuance, the description covers everything an agent needs: full parameter semantics, failure interpretation, repair ownership, environment limitations, and the meaning of a passing fixture. The existence of an output schema relieves it of documenting return shapes, and it appropriately leaves expectation object schemas open while giving concrete examples of valid ground-truth sources.

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%, so the description carries the full burden—and it pays off. The Args section explains every parameter in plain terms, adds the relationship that expectations and fixture are mutually exclusive, clarifies max_rows is applied locally because the report applies no cap, and notes that omitted params take defaults. This far exceeds what the bare schema offers.

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 sentence, 'Run a registered report once and check its results against known ground truth,' names a specific verb, resource, and outcome. It further distinguishes itself as 'the validation path that works on a pod without lexical substitution,' separating it from sibling report/validation tools without needing to read their schemas.

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 description gives strong context on when to use the tool: supply trusted ground truth and get all failures in one pass. It also explains what cross_check will do in this environment and instructs to vary bind values to test filter tightness before assuming data security issues. It never explicitly names a competing sibling such as fusion_validate_query or fusion_run_report, so it stops short of a full when-to-use-vs-alternatives statement.

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