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

Annotations already mark readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description builds on this by disclosing the refusal mechanism with specific refusal_reason values (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), the response shape including an evidence verbatim quote and confidence, and the extra-cost behavior. This goes well beyond the annotations and fully conveys how the tool behaves on failure.

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 most important clause ('Hallucination-resistant answer mode for high-stakes reads') is front-loaded, followed by routing, mechanism, return format, refusal reasons, and usage guidance. It is long, but nearly every sentence earns its place — the refusal_reason enum and the sibling-comparison cost note are directly actionable. The '5,721 across 1,497 sources' detail is somewhat extraneous but supplies scale context. Slightly dense, hence 4 rather than 5.

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, enumerating the success response {answer, evidence, confidence, source, fetched_at, refusal_reason:null} and each failure shape. Combined with full schema coverage on parameters and complete annotation coverage, everything an agent needs to call this tool correctly and interpret its result is present. No gaps.

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 does not add parameter-specific meaning, but the input schema fully documents the required 'question' string and all five aliases (q, text, input, query, prompt). Since the schema carries the entire parameter burden, 3 is appropriate — the description focuses on behavioral semantics rather than parameter syntax, which is acceptable at full coverage.

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 the specific purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It states the verb (extract answers), the resource (results of the right tool routed from 5,721 tools), and the distinguishing behavior — using ONLY what the tool result contains. It explicitly contrasts with the sibling ask_pipeworx ('Same routing as ask_pipeworx'), so an agent can tell them apart without opening schemas.

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?

Provides explicit when-to-use guidance ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') with concrete domains (financial verdicts, legal claims, medical lookups, public statements). It also states when NOT to use it ('prefer ask_pipeworx for casual lookups') and exposes the cost trade-off (one extra LLM call), which is exactly the kind of routing information an agent needs.

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