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

The description adds substantial behavioral context beyond the read-only/idempotent annotations: it explains the grading math, the automatic fallback routing, and—critically—clarifies the semantic difference between 'could_not_verify' (check did not happen) and 'unsupported' (no source). This is exactly the kind of nuanced disclosure an agent needs to avoid misinterpreting 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?

The description is long but densely packed and well-structured. The trigger phrases are front-loaded, followed by usage, processing details, output summary, and an 'IMPORTANT' caller note. Every sentence provides distinct value, and the format is highly scannable.

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 tool with no output schema, the description effectively covers the return values (verdict types, cited value, reasoning) and error semantics. It also explains the routing logic and tolerance behavior, leaving no major gaps for an agent to successfully invoke and interpret results.

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?

Although the schema already covers both parameters well, the description enriches them: it provides examples for 'claim', explains the default tolerance behavior, and explicitly recommends setting tolerance_pct to 1–2 for hallucination detection. This adds actionable guidance beyond the schema.

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 the tool's purpose: verifying natural-language factual claims against authoritative sources. It includes common user phrasings, explicitly differentiates between company-financial and other claims, and mentions the verdict outputs, making it distinct from sibling tools like ask_pipeworx_grounded.

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 says 'Use whenever the agent needs to check whether something a user said is factually correct' and goes on to detail the behavior for both financial and non-financial claims. This provides unambiguous when-to-use guidance and notes that it replaces multiple sequential calls, implying it should be preferred over composing those steps manually.

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