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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description adds marginal behavioral info. It clarifies that recipient_id is required for balance and that bulk execution is supported. However, no details about response structure or pagination behavior are provided, leaving holes.

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 cluttered with an unnecessary list of actions (list, get, default, etc.) that are not relevant to this specific flattened 'balance' tool. The bulk support line is useful, but overall the description is verbose and could be condensed to focus solely on balance functionality.

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?

No output schema is provided, and the description does not describe the return format or structure of the balance data. The tool has 6 parameters, and the description only covers two (recipient_id and recipient_ids). Given the lack of schema coverage and output schema, the description is insufficient for an agent to fully understand the tool's behavior.

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 must compensate. It only implicitly mentions recipient_id and recipient_ids, but does not explain data, page, size, or account. For a tool with 6 parameters, this is insufficient. The description adds little meaning beyond the raw schema.

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 mentions the balance action and states 'saldo do recebedor (requer recipient_id)', which clearly indicates it retrieves a recipient's balance. However, the initial general context about 'Recebedores (split/marketplace)' and listing multiple actions adds confusion, making it less immediate. It does not explicitly differentiate from sibling tools like pagarme_recipients_get or pagarme_recipients_list, but the action name and focus on balance imply its specific purpose.

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 specifies that balance 'requer recipient_id', giving a clear requirement. It also mentions bulk support with recipient_ids. However, it does not provide explicit guidance on when to use this tool versus alternatives (e.g., pagarme_recipients_get for general recipient info). The usage context is implied but not fully articulated.

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