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

Beyond the readOnly/idempotent/openWorld annotations, the description discloses the full execution model (routing across 7,157 tools from 1860 sources, argument filling, then extraction), the success payload shape, the complete refusal-reason enum, and the llm_error refusal_cause breakdown. The cost delta versus the sibling is also stated, which annotations cannot convey.

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?

Front-loaded with the core differentiator ('hallucination-resistant answer mode'), then return shape, then refusal modes, then usage guidance. Dense but nearly every clause carries information; the parenthetical refusal_cause taxonomy is the only passage verging on over-detailed for a tool selector.

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?

With no output schema, the description fully specifies both success ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}) and refusal payloads, plus the cost model. For a complex routing-plus-LLM tool, nothing an agent needs to decide or interpret results is missing.

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 aliases and prefer_tool semantics in full. The description adds context that arguments are auto-filled from the question and that unknowns are refused rather than guessed, but it does not restate or enrich individual parameter contracts. Baseline 3 is appropriate when the schema does the heavy lifting.

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?

States a specific verb and resource — a grounded, hallucination-resistant answer mode that routes, fetches, then extracts only from tool output — and explicitly contrasts with the sibling ask_pipeworx (same routing, extra LLM call). An agent can distinguish this from ask_pipeworx, ask_pipeworx_beta, and deep_research without opening schemas.

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?

Gives explicit when-to-use triggers (answers that will be quoted, cited, or acted on: financial verdicts, legal claims, medical lookups, public statements) and an explicit when-not (prefer ask_pipeworx for casual lookups, framed as a one-LLM-call cost tradeoff). Alternatives and selection criteria are named outright.

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