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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context: self-aggregating signal from CF analytics-engine, no PII, and caching behavior (5min-1h). This exceeds the minimum but doesn't detail edge cases like rate limits or exact data freshness boundaries.

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 well-structured with an opening summary, output statement, bulleted use cases, and technical notes. It is moderately long but each sentence adds distinct value, and the core function is front-loaded. Not as tight as a two-sentence description but appropriately detailed for a multi-purpose tool.

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 simple read-only analytics tool with one optional parameter and no output schema, the description covers purpose, use cases, data source, privacy, and caching. It gives enough information for an agent to decide when and how to invoke it, and what to expect in return, making it fully contextual.

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?

The input schema already fully documents the 'window' parameter with enum values and descriptions (shorter vs longer windows). The description reiterates the window options and adds caching behavior, but it provides no additional parameter-specific meaning beyond what the schema already states. Baseline 3 applies due to 100% schema coverage.

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 the tool returns top tools, top packs, and total call volume over a window, opening with a specific purpose ('What other AI agents are calling on Pipeworx right now'). This distinguishes it from sibling tools like discover_tools and ask_pipeworx by focusing on aggregate usage trends.

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 'Useful for' section provides three explicit use cases (discovering hot data sources, confirming canonical choice, aligning with current demand), giving clear contextual guidance. However, it does not name alternative tools or explicitly state when not to use it, so it falls short of a full 5.

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