List promotions

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds behavioral context by explicitly mentioning nextPageToken for pagination and the detailed return composition, which goes beyond the annotations. No contradictions exist.

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 a single sentence that conveys the purpose, return structure, and pagination succinctly. It is information-dense but not overly verbose; each element serves a purpose, though the long field list makes it slightly heavy.

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 fully covers the return values including field names and nested statuses, plus pagination via nextPageToken. The parameters are well-documented in the schema, and the tool's moderate complexity is adequately addressed. No significant gaps remain.

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 has 100% coverage for all three parameters, each with clear descriptions. The tool description does not add additional parameter semantics beyond what the schema provides, so the baseline score of 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 clearly states the tool lists promotions for an account, with a specific action verb 'Lists' and a defined resource. It details the return fields including nested structures like promotionStatus with destination statuses and itemLevelIssues, distinguishing it from sibling tools like get_promotion (single promotion) or list_products (different resource).

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 usage as a list operation for promotions but does not explicitly state when to use it versus alternatives such as get_promotion or insert_promotion. There is no mention of exclusions or specific scenarios, so guidance is only implicit.

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