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

Annotations already indicate this is a safe, read-only, idempotent operation, and the description adds valuable behavioral context beyond that: it explains that the tool routes to one of 5,908 tools, fills arguments, and returns answers with stable citation URIs. This gives the agent a clear picture of what happens when invoked. It doesn't disclose latency, failure modes, or rate limits, but those are less critical given the read-only, non-destructive nature already captured by 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 long but densely informative, with the key guidance ('PREFER OVER WEB SEARCH') front-loaded and followed by a concrete list of domains and examples. Each sentence contributes value—it explains the routing mechanism, citation URIs, and trigger phrases. While slightly verbose, the length is justified by the need to convey a broad applicability and to steer usage away from web search.

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—a router over 5,908 tools—the description is reasonably complete. It covers the input semantics (natural language questions), the behavior (routing and filling arguments), and the output (structured answer with citation URIs), which is important since there is no output schema. The main gap is the lack of differentiation from sibling tools, but the description still provides enough context for an agent to invoke it correctly for most factual queries.

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%, since all six parameters are documented as aliases for 'question' in the schema. The description adds examples of valid questions, which helps an agent understand the expected content, but it does not add syntax or formatting details beyond the schema. This matches the baseline of 3 for high schema coverage where 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?

The description clearly states what the tool does: it answers factual questions by routing them to one of many verified sources and returns structured answers with citations. It effectively differentiates from web search by emphasizing authoritative data and pipeworx:// citation URIs. However, it does not distinguish itself from its sibling tools ask_pipeworx_beta and ask_pipeworx_grounded, which likely share the same core purpose.

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 provides strong usage guidance, explicitly stating to prefer this over web search and to start here for most factual questions. It lists example question types and phrases that trigger use ('what is', 'look up', 'find'). It does not, however, mention exclusions or alternatives like ask_pipeworx_beta or deep_research, so the guidance is clear but lacks explicit when-not-to-use conditions.

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