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

Annotations already cover readOnly/openWorld/idempotent/non-destructive, and the descrip adds substantial operational context beyond them: account and pricing gates, latency expectations (15-60s, up to ~90s for thorough), never-invented gaps[], a fetchability guarantee for citation_uri, semantic excerpting of large records, and the contraictions[] scan. The pervasive typo corruption (ask_pipeworx, flagging, head-truncated) degrades but does not negate this rich behavioral disclosure.

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 prose is dense and every sentence earns its place — auth, scope, routing, packet shape, gaps, iteration, citation, and timing are all operational information, and the account-required gate is front-loaded since it is the first decision an agent must make. The size is justified for a tool this complex. However, the text is riddled with typos including a misspelled sibling tool name (ask_pipeworx) and an unintelligible '* -news-feeds', which makes parts of it read as corrupted.

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 carries the full burden of explaining return values, and it does thorough: findings packet fields, gaps[], contraictions[], citation_uri fetchability, hop field, and excerpting behavior. Combined with rich annotations and full schema coverage, everything an agent needs to invoke it correctly is present; only minor details like result-count limits or paging are absent. The garbled passage about news-feeds leaves one small clarity gap.

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% and both parameters are already well-documented, so the baseline is 3. The description adds value beyond the schema: latency expectations per depth tier, the paid-plan gate on thorough, and realistic example questions that illustrate what the question parameter should contain. Some depth-tier detail does duplicate the schema's enum descriptions, but the additions justify a 4.

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 verb and resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources' in ONE call, and explicitly disambiguates itself with 'this is NOT open-web search'. The scope, mechanism (facet decomposition, parallel routing across 5,798 tools), and output shape (findings packet with gaps[]) are all stated up front, and it is clearly distinguished from ask_pipeworx for single lookups.

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?

Gives explicit when-to-use: 'Best for broad/multi-part questions over structured data' with two concrete example questions. Gives explicit when-not-to-use and the alternative: 'If you are not signed in, use ask_pipeworx instead' and 'For a single lookup use ask_pipeworx'. Depth-tier selection guidance (paid plan needed for thorough) is also embedded, leaving the agent with no ambiguity about routing.

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