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

Annotations already declare read-only, idempotent, non-destructive, and open-world behavior, so the bar is lower; yet the description adds substantial context beyond that. It explains crucial semantics: the distinction between could_not_verify (a failed check, not evidence) and unsupported (no source found), the verdict enum, and the structured citation/reasoning payload. This is exactly the kind of behavioral nuance an agent needs.

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?

Despite being longer than average, the description is information-dense and well structured: trigger phrases, a use-case statement, routing logic, return format, and a critical caller warning. Every sentence contributes meaningful guidance, and important caveats are clearly marked with 'IMPORTANT for callers'.

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?

With no output schema, the description fully carries the burden of explaining return values and error semantics, and it does so thoroughly. It covers the full verdict list, citation behavior, reasoning, the special meanings of could_not_verify and unsupported, and even explains why this tool replaces multiple sequential calls. This is complete for an agent to decide when and how to invoke it.

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 schema already documents both claim and tolerance_pct with examples and defaults. The description adds some context about the nature of the claim parameter and mentions exact percent-delta math for financial claims, but it does not materially expand on tolerance_pct beyond what the schema already says. Baseline 3 is appropriate.

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 concrete trigger phrases and a clear verb+resource ('verify the claim that...'), immediately distinguishing validate_claim from siblings like ask_pipeworx or deep_research. It precisely scopes the tool to natural-language factual claim verification and further differentiates the company-financial fast path from the general grounded pipeline.

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?

It explicitly states when to use the tool ('Use whenever the agent needs to check whether something a user said is factually correct') and distinguishes the two internal routing paths. However, it does not explicitly name alternative tools for when not to use it, such as deep_research or ask_pipeworx_grounded, so it falls short of a full when-not/alternatives matrix.

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