audit_citations_tool

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains output fields, instructs agents to branch on structured fields rather than prose, describes high_risk_only filtering behavior, and warns that batch repairs must be proposed to the user rather than silently applied. It does not cover auth, rate limits, or error behavior, but the key operational behaviors are disclosed.

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 information-rich, with the core purpose front-loaded. Most sentences add meaningful guidance, but there are a few awkward phrases such as 'Set review_summary.suggested_fix_summary.auto_apply_allowed=false means...' which could be cleaner. Overall, it earns its length given the tool's complexity.

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 complexity, the lack of output schema, and the absence of annotations, the description covers a lot: input shape, key output fields, actionable guidance for agents, and high_risk_only behavior. The main gap is max_workers semantics and a bit more detail on what risk_ranking and per-citation report contain, but the description is largely sufficient for correct invocation.

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 must compensate. It thoroughly documents the citations parameter's object shape and the high_risk_only parameter's effect, but it does not explain max_workers at all beyond the schema's name and default. This partial coverage leaves one parameter semantically underspecified.

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 opens with a clear, specific statement: 'Verify MANY citations at once.' This gives a verb, resource, and scope, and the emphasis on 'many' differentiates it from sibling tools like verify_citation_tool, which appears to handle single citations. It also describes the returned report structure, reinforcing the tool's batch purpose.

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 clearly indicates the tool is for verifying many citations at once, which establishes a primary use case. It does not explicitly name alternatives or say when not to use this tool, but the batch-focused language and sibling list provide enough context for an agent to infer the appropriate selection.

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