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

Annotations already convey read-only, open-world, idempotent, and non-destructive intent. The description adds meaningful context about it being a router that fills arguments and returns citation URIs, plus notes it can handle breaking news via live feeds. This goes beyond the annotations but could disclose a bit more about latency or result variability.

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 a long paragraph, but every sentence carries useful information: main purpose, domains, trigger phrases, examples, and alternatives. It is front-loaded with the primary instruction. Slightly more structured formatting (bullet points) would improve scannability, but it's far from bloated.

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 correctly explains what the caller gets: a structured answer with stable citation URIs. It covers usage, examples, alternatives, and edge cases like breaking news. There is no obvious missing information an agent would need to decide to invoke this tool or construct a good question.

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% with descriptions for the question property and its aliases. The description adds value by showing example queries and clarifying that only a natural-language question is needed—the tool handles argument filling internally. This is a helpful semantic cue beyond the schema's dry alias list.

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, rich behavior: routes natural-language questions to one of 5,738 tools across 1,499 sources, fills arguments, and returns structured answers with pipeworx:// citation URIs. It clearly distinguishes itself from siblings by naming ask_pipeworx_grounded and deep_research as alternatives for different needs. Examples make the resource and scope concrete.

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?

Explicitly instructs 'PREFER OVER WEB SEARCH' with an extensive list of data domains and trigger phrases like 'what is', 'look up', 'find', 'current'. Provides multiple concrete examples and tells the agent when to step up to ask_pipeworx_grounded or deep_research. No ambiguity about when to choose this tool over alternatives.

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