Meus cards abertos

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

Annotations already mark the operation as read-only, idempotent, and non-destructive, so the description needs to add operational behavior. It does by revealing two execution modes, the server-side API calls, and the performance limitation (pesado, limited to 8 boards) — valuable context not available in annotations.

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?

Three short sentences front-load the purpose, then provide usage preference, internal flow, and a warning. Every sentence earns its place and there is no filler.

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 read-only listing tool with optional parameters and no output schema, the description covers purpose, preferred invocation, fallback behavior, and limitations. Nothing essential for correct invocation is missing; return shape is implied by 'cards' and the card endpoint.

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 descriptions already cover busca, atrasado, and board_uuid (75% coverage). The description adds meaning by explaining why board_uuid matters, including the exact GET /api/user resolution and the aggregation fallback, which goes beyond the schema's single recommendation line.

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 this is a shortcut to the authenticated user's open cards ('cards abertos do usuário autenticado') and explains the server resolves member_id via /api/user, which is a specific scoped resource. That distinguishes it from the generic sibling bticket_list_cards.

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 gives explicit preference: pass board_uuid to avoid aggregation, and warns not to use aggregation if not needed ('Não use agregação se não precisar'). It also discloses the heavy cost and 8-board limit of the fallback, so an agent can decide when this tool/parameter path is appropriate.

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