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

Annotations already establish the safety profile (readOnly, idempotent, non-destructive). The description adds substantial behavior beyond that: the grounded-extraction guarantee ('using ONLY what the tool result contains'), the exact success return shape with verbatim evidence quote, and — most valuable — the explicit refusal contract enumerating five refusal_reason values when the data doesn't directly answer. This tells the agent that a null answer is a legitimate, trustworthy outcome rather than a failure, which is critical behavioral context for a grounded tool.

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?

Every sentence earns its place: what it is, how it works, success return shape, failure/refusal contract, when to use, and cost tradeoff. The differentiating trait is front-loaded in the first clause, and the refusal reasons and use-case examples are compact lists rather than prose. Dense but efficient — no filler, no repetition of schema or annotation content.

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?

The tool has complex behavior (internal routing across 5,908 tools, grounded extraction, refusal semantics) and no output schema, so the description must explain return values itself — and it does so thoroughly with both success and refusal shapes enumerated. Given the simple single-parameter input, the rich annotation set, and the detailed return contract, nothing an agent needs to invoke this tool correctly or interpret its output is missing.

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% — the schema fully documents the single conceptual parameter (question) and its six aliases. The description adds marginal context by explaining that the question gets routed internally to pick a tool and fill arguments, which hints at how the question is interpreted, but this is behavioral context rather than parameter semantics. With the schema carrying the full load, the 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 opens with a specific, differentiating trait — 'Hallucination-resistant answer mode for high-stakes reads' — and explains the mechanism (routing to 5,908 tools, then extracting answers only from tool results). It explicitly names the sibling it must be distinguished from (ask_pipeworx) and states the exact difference: same routing, grounded extraction. An agent can reliably tell this tool apart from ask_pipeworx, ask_pipeworx_beta, and deep_research without opening any schema.

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: 'Use 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 names the alternative tool (ask_pipeworx) and the exact condition that selects it ('prefer ask_pipeworx for casual lookups'), including the cost tradeoff of one extra LLM call. Nothing is left to inference.

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