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

Annotations already mark it read-only, idempotent, non-destructive, and closed-world. The description adds substantial behavioral context: it is not paginated, returns a small fixed number of buckets per dimension, includes zero-count categories, counts no_connection_declared and no_payment_declared, and requires no payment or account.

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 core purpose is front-loaded, but the description is bloated with full enumerations of categories, connection types, and payment types that already appear in the schema. The opening sentence is also very long and introduces 'import source' without later detailing it. It is usable but does not tightly earn every sentence.

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 12-parameter, non-paginated aggregation tool with no output schema, the description does well: it explains bucket behavior, zero counts, and shared filters with search_listings. It stops short of fully describing every returned dimension, such as import source or payment-network buckets, leaving minor gaps.

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 most parameter meaning is already in the schema. The description still adds value by clarifying that q and max_price are the same as in search_listings and specifying that max_price is a USD amount matched only against recognized USD stablecoins. It does not add detail for every parameter, but it meaningfully extends the schema on price filtering.

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 operation: facet counts of matching listings grouped by dimensions. It distinguishes itself from search_listings by explaining it is for seeing what's out there before narrowing a search, rather than paging through listings. The verb+resource framing is clear.

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?

It explicitly says to use this before deciding how to narrow a search and as an alternative to paging through everything with search_listings. It names search_listings as the related tool and explains the shared filter semantics. The when-to-use guidance is direct and actionable.

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