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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description goes well beyond this by detailing the refusal mechanism, the exact return structure (answer, evidence, confidence, source, fetched_at, refusal_reason), the list of refusal reasons, and the extra LLM call cost. This enriches the agent's understanding of behavior without contradicting any annotation.

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 longer than average but every sentence contributes: purpose, routing equivalence, extraction behavior, return format, refusal reasons, use cases, and cost comparison. It is front-loaded with the core purpose and then layers details. Could be slightly tighter but is not verbose or wasteful.

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 complex tool with no output schema, the description covers the return format thoroughly, lists refusal reasons, explains the tradeoff versus a sibling, and gives clear usage criteria. An agent has enough to decide when to invoke it and what to expect, including edge cases like data truncation.

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 covers all 6 parameters with descriptions (all aliases for question), and the description doesn't add any new parameter semantics. Since schema coverage is 100% and the parameters are trivial aliases, the description doesn't need to compensate. Baseline 3 is appropriate because the description doesn't harm but also adds nothing beyond schema for parameters.

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 purpose — hallucination-resistant answering with extraction — and explicitly contrasts itself with ask_pipeworx by describing the same routing but with the added extraction step. The verb+resource is clear: it answers questions with grounded evidence. The sibling distinction is explicit and immediate.

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?

Provides explicit when-to-use criteria: high-stakes reads where the answer will be quoted, cited, or acted on. Also gives a when-not-to-use: casual lookups, with a direct recommendation to prefer ask_pipeworx. Additionally notes the cost tradeoff (one extra LLM call), which is actionable guidance for selection.

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