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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, but the description adds critical behavioral context beyond that: refusal states with refusal_reason enumerations, the extraction-only-from-tool-result constraint, and the extra LLM-call cost. It could mention more about latency or cached evidence, but it is already substantively transparent and does not contradict 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 dense and information-rich, but it front-loads the core purpose and behavior before the usage guidance and cost tradeoff. Every sentence earns its place, though it is slightly long and could tighten the enumeration of refusal reasons, which also appear implicitly in the refusal shape.

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 one parameter and no output schema, the description thoroughly explains success response fields, refusal response fields, routing behavior, when to use it, and when not to. Minor gaps: it doesn't state approximate latency or explain the relationship with ask_pipeworx_beta, but it is overall complete for an agent to select and 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?

The schema contains one question parameter with five documented aliases and 100% coverage, so the description need not add much. The description does reinforce that the question goes through routing and that the answer is grounded only in the tool result, but it does not add parameter-level meaning beyond the schema. Baseline 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 opens with 'Hallucination-resistant answer mode for high-stakes reads' and elaborates a concrete verb+resource: it routes to the right source tool, fetches data, then extracts the answer using ONLY the tool result. It also explicitly distinguishes itself from sibling 'ask_pipeworx' by naming the same routing and the extra extraction step.

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 gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with domain examples. It also states the tradeoff ('Costs one extra LLM call vs ask_pipeworx') and directs casual lookups to ask_pipeworx. This is clear routing among siblings.

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