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

The description discloses the refusal contract with specific refusal_reason enums (not_in_source, no_tool_match, tool_error, data_truncated, llm_error) and the exact success payload shape. It also adds behavioral context beyond the annotations: it costs an extra LLM call, refuses when data doesn't directly answer, and is designed for high-stakes reads. Annotations are not contradicted; readOnlyHint and idempotentHint align with a read/extract operation.

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 dense but every sentence carries load-bearing information: mode, capability, data flow, return contract, refusal reasons, use cases, cost tradeoff, and preference guidance. It is front-loaded with the most important differentiator (hallucination-resistant) and ends with actionable routing advice. No wasted words.

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?

For a tool with 6 schema aliases and a rich behavioral contract, the description fully covers the decision space: what it does, how it differs from ask_pipeworx, when to use it, what it returns on success, what refusal reasons exist, and the cost consequence. The absence of an output schema is compensated by the explicit return shape in the description. An agent has everything needed to invoke and interpret this 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% and the schema already documents the question parameter plus aliases. The description adds context about what the question is used for (routing, filling arguments, fetching data) and that the output is grounded/extracted from tool results, which gives the parameter semantic weight beyond 'a question string.' However, it doesn't discuss question format beyond natural language, which the schema already covers.

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 this as a hallucination-resistant answer mode that retrieves data and extracts answers only from tool results. It specifies the exact verb ('extracts'), the resource (tool results across 5,743 tools/1,500 sources), and distinguishes it from ask_pipeworx in the first sentence. The contrast is explicit: same routing, but grounded extraction with refusal behavior.

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?

Explicitly states when to use ('whenever an answer will be quoted, cited, or acted on... financial verdicts, legal claims, medical lookups, public statements') and when not to ('prefer ask_pipeworx for casual lookups'). It also references the sibling tool ask_pipeworx by name and explains the cost tradeoff (one extra LLM call), which is clear decision guidance.

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