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

Beyond the annotations, the description discloses the full refusal contract, including the exact refusal_reason enum values, the success response shape with evidence as a verbatim quote, and the extra LLM call cost. It also clarifies that the tool never invents facts and returns an explicit refusal when data does not directly answer. No contradiction with annotations was found.

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: purpose, routing mechanism, output and refusal format, usage guidance, and cost tradeoff. The description is dense but not bloated, and the high-stakes framing is front-loaded while the cost comparison is placed at the end where it supports the routing decision.

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?

This is a complex tool with no output schema, but the description covers the success response shape, the refusal response shape, all refusal reasons, the routing behavior, the cost implication, and when to use it over the sibling. An agent that reads this description has enough information to invoke the tool correctly or decide not to.

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%, so the schema already documents all six parameter aliases. The description says it 'fills arguments' and accepts a natural-language question, which adds context about tool behavior but no new parameter-level semantics beyond what the schema provides. 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 immediately defines a specific purpose—hallucination-resistant answer mode for high-stakes reads—and explains the mechanism: route to the right tool, fill arguments, fetch data, then extract the answer only from the tool result. It clearly distinguishes this from the sibling ask_pipeworx by contrasting its grounded extraction 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?

Explicit when-to-use guidance is given: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete domains listed. It also names the alternative and the condition for choosing it: 'prefer ask_pipeworx for casual lookups' because this mode costs one extra LLM call.

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