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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds behavioral context beyond that: it routes to the right tool among thousands, fills arguments, returns structured answers with stable pipeworx:// citation URIs, and includes a hallucination-resistant alternative and a fan-out alternative. It does not describe rate limits or response formatting in detail, but given the annotation coverage, the added value is strong.

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 dense and front-loaded with the most important routing guidance ('PREFER OVER WEB SEARCH'). It packs a huge amount of useful information into a few sentences and includes concrete examples. Minor deduction for a slightly run-on final sentence that jams together grounded, deep_research, and news-feeds guidance without clean punctuation, making that part harder to parse.

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 broad scope, no output schema, and 6 parameters (all aliases), the description covers the core completeness needs: what to ask, when to use it, examples, citation behavior, and alternatives. It lacks explicit mention of response format or potential limitations (e.g., time bounds, data freshness, citation format details), but those are partly covered by the mention of stable pipeworx:// citation URIs and the examples. For a general-purpose lookup tool, this is nearly complete.

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% because all six parameters are aliases for the same 'question' field, and the schema explicitly documents that. The description adds behavioral meaning: the question should be natural language and can be a lookup, factual query, or data request; it also gives three concrete examples in the schema. While the description itself does not enumerate the aliases, the schema fully covers the single meaningful parameter, so the combination is essentially complete.

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 ('ask', routes the question) and a precise resource: Pipeworx's 5,798 tools across 1,517 verified sources for authoritative structured data with citations. It explicitly differentiates from web search and covers a broad but clearly scoped domain: factual questions about real-world entities, events, or numbers requiring citations. The listed examples make its purpose instantly recognizable.

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 gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH for questions about current or historical data' and lists categories and trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'). It also provides when-not-to-use alternatives: for multi-part broad research use deep_research, for grounded citations use ask_pipeworx_grounded, and for breaking-news sentiment, the *-news-feeds packs. This is exceptionally clear routing.

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