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

Annotations already declare read-only, idempotent, and non-destructive behavior, so the description adds substantial non-obvious context: the SEC EDGAR fast path with exact percent-delta math, the automatic fallback to a grounded pipeline with verbatim evidence, and the specific return verdicts. The critical distinction between could_not_verify (verification failure) and unsupported (no source coverage) is disclosed, which deeply informs expected behavior 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 well-organized, front-loaded with usage signals and followed by a logical breakdown of behavior, return values, and caller caveats. Each sentence carries useful information—examples, decision paths, error semantics, and efficiency rationale. It is not minimal, but the density and structure keep it valuable without waste.

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 explains the expected return values: verdict types, the grounded/structured actual value with citation, and reasoning. It also covers error handling (verification_error with stage/detail) and how the tool routes claim types. The guidance on interpreting verdicts and the overall workflow makes the description complete for an agent to invoke and use the tool 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%, but the description add meaningful semantics beyond the schema. It explains that tolerance_pct overrides wording-implied tolerance, caps at 5 by default, and recommends 1–2 for hallucination detection. For claim, it provides diverse examples showing expected natural-language input. This significantly enhances parameter understanding and practical use.

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 user phrasings, then clearly defines the tool as 'natural-language claim verification against authoritative sources.' It distinguishes itself from siblings by describing its two-path behavior (SEC EDGAR/XBRL for company financials, grounded pipeline for anything else) and by noting it replaces multiple sequential calls. The purpose is specific, actionable, and readily differentiates the tool.

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,' providing direct when-to-use guidance. It also differentiates claim types (company-financial vs. other) and offers important caller guidance about interpreting could_not_verify versus unsupported. However, it does not name alternative tools or explicitly state when not to use it, so it falls just short of full exclusion guidance.

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