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

The description goes well beyond the readOnly/idempotent annotations by disclosing the exact response contract, including the success fields {answer, evidence, confidence, source, fetched_at, refusal_reason:null} and the explicit refusal reasons such as 'not_in_source' and 'data_truncated.' It also reveals the grounded extraction behavior and the extra LLM call cost, which are not inferable from annotations alone. There is no contradiction with 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 dense but every sentence serves a purpose: the first sentence defines the behavior, the middle specifies the response contract and refusal reasons, and the final sentence gives usage guidance and tradeoffs. The critical differentiator appears immediately, and the detailed return shape is necessary because there is no output schema.

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?

Given the tool's complexity and the absence of an output schema, the description is remarkably complete: it covers routing scope, grounding behavior, success and refusal return shapes, explicit use cases, and the cost comparison to the sibling. An agent has everything needed to decide when to call it and what to expect from it.

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%, and the schema already documents all six parameters as aliases for the natural-language question. The description does not add parameter-level detail, but because the schema handles parameter semantics fully, a baseline 3 is appropriate and no compensation is needed.

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 a precise characterization: 'Hallucination-resistant answer mode for high-stakes reads.' It names the action (extract the answer), the resource (Pipeworx tool routing across sources), and the boundary ('using ONLY what the tool result contains'), which clearly distinguishes ask_pipeworx_grounded from its sibling ask_pipeworx and other tools.

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 this tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' and when not to: 'prefer ask_pipeworx for casual lookups.' It also gives the cost-based tradeoff, 'Costs one extra LLM call vs ask_pipeworx,' making the decision criterion explicit rather than implied.

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