Browse a category

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

Annotations only declare readOnly/openWorld; the description adds substantial context beyond that: per-platform parameter support, unit consumption ranges (1 unit vs 1–2 units for amazon), and billing behavior ('a call that fails is not billed'). Those cost and pagination traits materially affect call planning and are not in any structured field.

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 purpose sentence is front-loaded and the platform table is dense with zero filler; pagination and billing are one line each. The opening sentence is a fragment and the block-list format is slightly telegraphic, but no line is wasted.

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 a nested free-form params object, multi-platform dispatch, and no output schema, the description covers what's needed to construct a valid call: id source, per-platform params, paging, and cost. It stops short of describing the shape of returned product records, though that is partly inferable from the 'products' framing.

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 schema is effectively a free-form params bag with additionalProperties: {}, so the description must define the real parameters — and it does, enumerating each platform's accepted params with * marking required ones (categoryId*) and noting optional fields like currency, facets, sort. Without this text the tool would be uncallable.

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 the specific resource and scope ('The products in one category, with no keyword'), which immediately separates it from the keyword-based search_products sibling. The title supplies the verb, and the description pins down the retrieval semantics.

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 an explicit prerequisite route ('Get category ids from list_categories') and pagination instructions ('For the next page pass params.page = 2, 3, …'). The 'no keyword' phrasing implies the alternative is a keyword search, but it never names search_products as the when-to-use-this-instead sibling.

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