scan_broken_refs

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

With no annotations provided, the description takes on the transparency burden. It discloses the read-only nature, explains that bindings are resolved against the live model, and describes the output (broken refs report location plus repair suggestions). It does not mention permissions or potential failure modes, but for a scan tool this is reasonably transparent.

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 dense and packs in multiple pieces of information: what it does, what it resolves, what output it provides, the reportSource note, the alternative repair tool, and read-only status. Every sentence earns its place; it is slightly long but not wasteful.

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?

Given the tool's moderate complexity, two parameters with full schema coverage, and no output schema, the description covers the essential behavior: what it scans, how it resolves, what it returns, and the alternative for repair. It is complete enough for an agent to decide when to use it and what to expect.

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 100%, so the parameters are already well-documented. The description adds a brief note about reportSource types but that information is essentially the same as the schema property description, so no significant extra value is provided beyond the schema baseline.

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 clearly states it flags report bindings pointing at missing model fields, and enumerates the binding types (projection, filter, sort, conditional-formatting). It also explicitly distinguishes itself from the sibling fix_broken_visuals by framing this as a diagnostic read-only scan.

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 explicitly mentions 'Repair legacy sessions with fix_broken_visuals', giving a clear alternative for the repair use case. It also implicitly defines when to use this tool (to scan/flag issues) and emphasizes read-only, though it does not spell out explicit 'when not to use' scenarios beyond that.

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