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

Annotations already declare readOnly, openWorld, and idempotent behaviors, and the description adds substantial context beyond them: the meaning of could_not_verify (a non-result with verification_error, not evidence), the distinction between unsupported and refuted, the structured SEC EDGAR fast path versus grounded fallback, and the verdict vocabulary. This gives callers crucial behavioral understanding well beyond the annotations.

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 with relevant examples, routing logic, return details, and error semantics. It is front-loaded with natural-language trigger phrases and each sentence adds value; however, it could be slightly more concise by moving the 'Replaces 4–6 sequential calls' detail to the end. Overall, the length is justified 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?

There is no output schema, so the description must explain return values—and it does with a full list of verdicts, the actual value with a pipeworx:// citation, and reasoning. The description also covers error semantics (could_not_verify with verification_error), fallback behavior, and parameter overrides, making it complete for safe and 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 100%, with both claim and tolerance_pct fully described in the schema. The description adds some context (e.g., tolerance override for hallucination detection, exact percent-delta math), but it does not substantially enhance the parameter semantics beyond what the schema already provides, so a 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 uses specific action phrases like 'fact check' and 'verify the claim that…' and clearly identifies the resource: natural-language claim verification against authoritative sources. It distinguishes itself from sibling tools by explicitly explaining that it replaces 4–6 sequential calls (NL parsing → entity resolution → data lookup → comparison).

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 says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear use context. It also differentiates between company-financial claims and other factual claims, describing the fallback routing, but it does not explicitly state when NOT to use this tool versus alternatives like deep_research or ask_pipeworx_grounded.

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