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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds the bulk execution capability (accepts offer_ids for batched execution) and provides domain context about offers being the price unit targeted by order bumps. However, it does not disclose pagination behavior, default ordering, or any rate limitations. The note 'Flattened action: list' clarifies behavior but is already implied by the tool name. Overall, it adds some context beyond annotations without contradicting them.

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 moderately concise but includes a domain lecture (what an offer is, how bumps point to offers) that is tangential to how to call the list tool. The purpose is front-loaded, but the 'Ações' section could be streamlined. The flattened action note and bulk support note are useful but add to the length. Overall, it is somewhat verbose for a simple list endpoint, but not excessively so.

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 and 10 parameters, the description should provide richer guidance. It lists the filters but does not explain response format, pagination details (e.g., how many results per page), or default ordering. The bulk support is mentioned but not how offer_ids interacts with other filters. The domain explanation is helpful but does not compensate for missing operational details. An agent would likely need to experiment or consult other documentation to use the tool effectively.

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 description coverage is 0%, so the description carries the full burden. It lists filter names (product, status, type, search, ordering, limit, page) but does not explain their semantics beyond the names. It adds value for offer_ids by mentioning bulk support, but other parameters like 'status' and 'type' are only covered by enums in the schema, not the meaning or expected usage. Pagination parameters (limit, page) are not described in terms of defaults or max values. No parameter gets a full explanation, leaving the agent to infer.

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 'Leitura de ofertas na Cakto' (reading offers), which clearly states a specific verb and resource. It also explains the domain concept of an offer, and the flattened action note clarifies that this tool performs the 'list' action, distinguishing it from the sibling 'get' action. However, the 'Ações: list, get' section initially presents both actions, which could confuse an agent about whether this tool handles both, though the flattened action disambiguation mitigates that.

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 does not explicitly state when to use this tool versus alternatives like cakto_offers_get. It mentions that 'get' requires offer_id, but does not say 'use this tool for listing multiple offers, use get for a single offer'. The guidance is implied by the existence of separate sibling tools, but there is no explicit exclusion or routing directive. The bulk support note hints at batched use cases but does not clarify when batch vs. single filtering is appropriate.

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