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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the main risk is selection rather than side effects. The description adds materially useful behavioral context beyond annotations: it routes to a wide source ecosystem, fills arguments, returns pipeworx:// citation URIs, works on every tier, and is a single fast call. No contradiction with annotations exists, though edge-case behavior for unanswerable or ambiguous questions is not described.

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 information-dense and front-loaded with the primary directive ('PREFER OVER WEB SEARCH'). The examples and sibling-tool guidance all earn their place for a default entry-point tool. It could be tightened slightly, but there is no filler or redundant restating of schema details.

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 one-parameter natural-language router with no output schema, the description explains the return format well enough: structured answer with stable citation URIs. It also covers domains, examples, and escalation paths to relevant siblings. Minor gaps include failure behavior for unanswered questions and explicit handling of non-factual/opinion queries, but overall the agent has enough context to select and invoke the 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 coverage is 100% and the schema describes `question` as accepting natural language plus aliases, so the baseline is 3. The description adds value by giving concrete trigger phrases and many example queries that clarify what kinds of content are appropriate, such as 'current US unemployment rate' and 'active clinical trials for GLP-1.' This helps an agent understand that a broad factual question is intended, not a structured command.

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 gives a specific, informative statement of what the tool does: it routes natural-language questions to one of 5,944 tools across verified sources, fills arguments, and returns structured answers with stable citation URIs. It also clearly distinguishes this tool from siblings like ask_pipeworx_grounded and deep_research. This goes far beyond the generic title 'Ask Pipeworx.'

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 is explicit about when to prefer this tool over web search, when it should be the default entry point, and exactly when to 'step up' to ask_pipeworx_grounded or deep_research. It names the alternative tools and the conditions that select them, leaving little to inference.

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