GET /recurringSales (Recurring Sale)

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

Annotations already declare readOnlyHint=true (safe read) and destructiveHint=false. The description adds the pagination behavior and array value format, but does not add significant behavioral content beyond what annotations provide. The warning about pagination version is useful but not extensive.

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?

Description is three sentences, each serving a purpose: stating the operation, explaining array behavior, and warning about pagination deprecation. No fluff, front-loaded with the core purpose.

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 list tool with no output schema, the description adequately covers the pagination mechanism (crucial for correct usage) and the array value format. It does not describe the return structure but that is typical for list operations. The warning compensates for some missing context.

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 baseline is 3. The description mentions that array parameters can have multiple comma-separated values and implies pagination parameters, but does not add meaningful detail beyond the schema's parameter descriptions. No extra semantics for parameter types or constraints.

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?

Description clearly states 'Listagem paginada de Vendas Recorrentes' (paginated listing of recurring sales), with a specific verb (listar) and resource (vendas recorrentes). It distinguishes from siblings like get_recurring_sale (single) and create/update/delete operations.

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?

Description specifies that items defined as arrays can have multiple values separated by comma, and provides a critical warning about pagination: the new pagination requires the limit parameter, otherwise the old model will be used until deprecated in 2026. This guides usage of the parameter effectively.

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