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

Annotations already convey readOnly, idempotent, open-world, and non-destructive behavior, and the description builds on this by explaining the refusal behavior and output shape: success returns {answer, evidence, confidence, source, fetched_at}, while failure returns explicit refusal_reason values. It also discloses a key non-obvious trait: the answer is extracted only from tool results, never invented.

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 with no filler: it leads with the core behavior, includes the exact return and refusal shapes, states use cases, and closes with the cost tradeoff. Every sentence contributes to correct selection and invocation.

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?

Despite no output schema, the description fully specifies the success and failure return structures, making invocation behavior predictable. It also addresses routing, sibling differentiation, cost, and usage context, leaving no meaningful gap for an agent to call this tool 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 description coverage is 100% and the single required parameter 'question' plus its five aliases are fully described in the schema. The tool description adds no parameter-level meaning, but none is needed because the schema already clarifies that aliases are accepted and natural language is expected.

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 verb and resource: it is a 'hallucination-resistant answer mode' that routes like ask_pipeworx, fetches data, and 'EXTRACTS the answer using ONLY what the tool result contains.' It explicitly distinguishes itself from ask_pipeworx by emphasizing grounded answers and explicit refusals rather than generation.

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 gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' and 'the agent must not invent facts.' It also gives a concrete when-not-to-use instruction: 'prefer ask_pipeworx for casual lookups,' and even names the cost tradeoff of one extra LLM call.

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