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

Annotations only include readOnlyHint=false and others false, which are not very informative. The description adds value by specifying that CPF/CNPJ is required, minimum value, and that it returns specific fields, which gives the agent behavior expectations beyond the annotations. No contradiction.

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 concise and front-loaded with the main purpose and outputs. It adds essential constraints (CPF/CNPJ, min value) and bulk support in a compact way. No unnecessary sentences.

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 14 parameters and no output schema, the description provides the core output structure and key constraints, but it doesn't explain optional parameters like shipping_methods or discount_cents, nor does it detail the payment flow. It is adequate but not fully complete for a complex tool.

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 compensates by explaining key outputs and requirements, but it does not elaborate on individual parameters like discount_cents, days_due_date, or notification_url. It covers the core purpose but leaves many optional parameters undocumented.

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's purpose: emitting a Pix charge via PagHiper, and lists the specific outputs (pix_code.emv, qrcode_base64, qrcode_image_url, transaction_id). It distinguishes itself from siblings like paghiper_create_boleto by focusing on Pix and mentions required payer CPF/CNPJ and minimum value.

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 mentions bulk support for order_ids, indicating a usage variant, but does not explicitly when to use this tool vs paghiper_create_boleto or paghiper_cancel_pix. It implies it's for creating Pix charges but lacks exclusions or alternatives.

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