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

Annotations already mark readOnly/openWorld/idempotent, so the baseline is high. The description adds valuable behavioral context: it will refuse when the data doesn't directly answer, returns a refusal_reason enum, extracts using only tool-result content, and costs one extra LLM call. Nothing contradicts 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 information-dense but front-loads the core purpose and refusal behavior, then gives usage guidance and a cost trade-off. It is slightly long, but every sentence carries useful distinction or safety-relevant information, so it earns a 4 rather than a 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?

For a question-answering tool with a rich schema and clear safety annotations, the description covers purpose, alternatives, refusal behavior, cost, return shape, and trigger conditions. There is no obvious missing context that an agent needs to select or invoke it 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 all six parameter aliases plus the canonical question parameter. The description adds no additional parameter-level meaning beyond what the schema provides, so a 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 states a specific mode ('hallucination-resistant answer mode for high-stakes reads'), names the resource (Pipeworx), and explicitly contrasts with ask_pipeworx. It goes beyond a generic verb+resource by stating its purpose and how it differs from the sibling.

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?

It explicitly says when to use ('use whenever an answer will be quoted, cited, or acted on...'), gives example domains (financial verdicts, legal claims, medical lookups, public statements), and specifies preference for the lighter alternative for casual lookups. This is exactly the when/when-not guidance expected.

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