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

Annotations declare readOnlyHint=true, so the safety profile is already known; the description adds useful context by disclosing that paid packs incur x402 Base USDC costs, which is genuinely actionable behavioral information. Still, it does not describe response format, error conditions, or what happens when neither source_id nor pack_id is supplied, so the burden beyond annotations is only partially met.

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?

Two sentences with the purpose front-loaded ahead of the pack list; no wasted words. The lengthy but functional enumeration of free vs. paid packs earns its place because it encodes availability and cost distinctions the agent needs, keeping the overall structure tight.

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 an 8-parameter tool with nested objects (filters with time/region_ids/compare clauses) and no output schema, the description should cover return format and effective requirements, but it does neither. It leaves implicit that at least one of source_id or pack_id is needed (all params are optional) and does not disclose response shape, so an agent is left with gaps despite strong schema coverage.

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%, so the schema already documents all 8 parameters with meaningful descriptions (source_id examples, pack_id pointing to get_catalog, limit maximum/minimum). The description adds the API-contract pointer but no parameter-level detail beyond the schema, so the baseline 3 is appropriate.

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 opens with a specific verb+resource: 'Generic structured query for direct source_id or pack_id access', which precisely states what the tool does and how it is invoked. It also names the API contract (POST /api/v1/query/dataset) and the pack taxonomy, clearly distinguishing it from siblings like get_catalog (listing) and get_pack (pack retrieval).

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 implies the tool is for direct source_id or pack_id data access and enumerates the available free and paid packs, which helps an agent know when the tool is usable. However, it never explicitly states when NOT to use it or names alternatives (e.g., 'use get_catalog to discover pack_id first'), leaving routing between siblings to inference.

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