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

Beyond the readOnly/idempotent annotations, the description discloses critical behavioral nuances: the distinction between could_not_verify (check did not happen, carries verification_error, not evidence) and unsupported (no source found), the two-path execution, and the return structure (verdict, actual value with citation, reasoning). This is valuable context that annotations do not provide.

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 lengthy but information-dense: it front-loads trigger phrases, states the core use case, explains the two routing paths, lists return values, and highlights the crucial caveats. Every sentence earns its place and the structure is logical, moving from what it does to how it behaves to important caller warnings.

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 has no output schema, the description fully covers the return semantics (verdict set, actual value with citation, reasoning) and error handling (could_not_verify vs unsupported). It also explains the internal pipeline and the tool's value proposition, making it self-contained for an agent to invoke and interpret results correctly.

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 coverage is 100%, so the baseline is 3. The description mentions 'exact percent-delta math' and tolerance behavior indirectly, but it does not add any parameter details beyond what the input schema already provides for 'claim' and 'tolerance_pct'. The description is not compensating for missing schema info.

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 identifies the tool as a claim verification tool with specific trigger phrases ('Is it true that…', 'fact check', 'verify the claim that…') and a precise scope: natural-language claim verification against authoritative sources. It distinguishes itself by producing a verdict (confirmed/refuted/etc.) and being an aggregated pipeline that replaces 4–6 sequential calls, setting it apart from the broader ask_pipeworx family.

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 gives an explicit 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the routing logic (company-financial claims go to SEC EDGAR/XBRL, other claims fall through to the grounded pipeline). However, it does not explicitly name alternative tools or state when NOT to use this tool, so it lacks full exclusions.

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