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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description reveals the exact success return shape with fields like evidence and confidence, and details the refusal contract with specific refusal_reason enums. It also discloses the 'EXTRACTS the answer using ONLY what the tool result contains' behavior and the extra LLM call cost, giving the agent a rich behavioral model before invocation.

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 compact yet information-dense, with every clause earning its place: mode, routing, extraction constraint, success/refusal shapes, use cases, and cost tradeoff. The most important differentiator (grounded, refusal-capable) appears first, and the alternative tool is cited naturally rather than requiring the reader to infer it.

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 alias parameters, rich annotations, and no output schema, the description fully compensates by explaining the return contract, refusal scenarios, and expected usage context. It covers what an agent needs to decide whether to call this tool, what to pass, and what to expect back, including failure modes.

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%, with each parameter labeled as an alias for 'question' and the question parameter explaining it accepts natural language with aliases. The tool description itself adds no parameter-specific meaning, but since the schema fully documents the parameters, the baseline of 3 applies.

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 names a specific, distinctive behavior: a hallucination-resistant answer mode that extracts the answer only from the retrieved tool result. It clearly differentiates from the sibling ask_pipeworx by emphasizing grounded answers with evidence and refusals, and explicitly says it uses the same routing as ask_pipeworx while adding a strict extraction guarantee.

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?

The description explicitly states when to use the tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete domains like financial verdicts, legal claims, medical lookups, and public statements. It also gives the alternative condition: 'prefer ask_pipeworx for casual lookups' and explains the cost tradeoff of one extra LLM call, making the selection decision explicit.

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