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

Annotations declare readOnly, openWorld, idempotent, and non-destructive, but the description adds crucial behavioral nuance beyond that: it defines the meaning of 'could_not_verify' (check did not happen, must not be shown as evidence), distinguishes it from 'unsupported', and explains the fallthrough routing from SEC EDGAR/XBRL to the grounded pipeline. This prevents misinterpretation of 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 well-structured: it front-loads trigger phrases, then explains pipelines, verdicts, and error semantics. Each sentence carries operational value, though some phrasing could be tightened (e.g., the long parenthetical list of claim types). Overall, the length is justified by 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?

Despite having no output schema, the description fully enumerates all possible verdict values (confirmed, approximately_correct, refuted, inconclusive, unsupported, could_not_verify), describes the return contents (actual value with pipeworx:// citation, reasoning), and explains the distinct meanings of could_not_verify vs unsupported. It also mentions the structured vs grounded routing and the replacement of sequential calls, making it self-sufficient for callers.

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?

Since the input schema already covers 100% of parameters, the baseline is 3. The description goes beyond the schema by explaining how tolerance_pct overrides the implied tolerance, recommends 1–2 for hallucination detection, and notes the default is capped at 5. It also gives concrete examples for the claim parameter, adding real usage guidance.

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 performs 'natural-language claim verification against authoritative sources' and includes explicit trigger phrases like 'fact check' and 'verify the claim that…'. It also distinguishes itself from sibling tools by noting it replaces 4–6 sequential calls (NL parsing → entity resolution → data lookup → comparison), giving a specific verb+resource+scope.

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 says 'Use whenever the agent needs to check whether something a user said is factually correct' and differentiates the fast path for company-financial claims from the grounded pipeline for all other factual claims. However, it does not name or exclude specific sibling tools (e.g., ask_pipeworx_grounded, deep_research), so it lacks explicit alternatives but still provides clear context.

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