Lunium — Brazilian PIX and stablecoin payments

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

Goes well beyond the readOnlyHint/idempotentHint annotations by explaining the anti-fraud ladder, why limits vary per payer, and the acao error taxonomy with retry behavior. It also warns that approval can still fail for other reasons, which is non-obvious behavioral context.

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 longer than average, but every section earns its place: return value, usage conditions, behavioral reasoning, input format, and error handling. The most decision-relevant information is front-loaded in the first sentence.

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 single-parameter read-only tool with no output schema, it fully covers units, document formats, error cases, retry guidance, and follow-up behavior. An agent has enough information to invoke it correctly and interpret the result.

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 100%, including the digits-only CPF/CNPJ pattern, so the baseline is 3. The description reinforces the digits-only rule but does not add meaningful parameter semantics beyond what the schema already provides.

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?

States a specific verb and resource: it returns how much a CPF/CNPJ taxpayer can move through a PIX charge right now, in cents. It also explicitly says read-only and that no charge is created, which separates it from mutation siblings like lunium_create_pix_charge.

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?

Gives explicit when-to-use guidance: call it before lunium_create_pix_charge when the payer is new or the amount is not trivial. It also lists exclusions: don't use it as a document-validity check and don't treat a high limit as approval.

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

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

Annotations already signal destructive, idempotent, and open-world behavior, but the description adds crucial context: no cancel/reversal/support path, token binding to the exact amount/network/PIX key, per-order deposit addresses, unrecoverable funds on stale addresses, and a detailed error taxonomy. There is no contradiction with 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?

The description is long but well-structured: front-loaded with irreversibility, followed by prerequisites, post-call steps, and error handling. Some redundancy exists across the title and repeated no-undo warnings, but for a high-stakes irreversible money movement tool, the emphasis is justified.

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?

Even without an output schema, the description tells the agent what is returned (deposit_address), what must happen before calling, what to do after calling, common failure modes, and how to interpret acao/erro values. Nothing essential for invoking this tool correctly is missing.

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% with already-detailed parameter descriptions, so the baseline is 3. The description adds meaningful semantic weight beyond the schema by explaining that confirmation_token is bound to the exact quoted order and that user_approved must reflect the user's explicit approval of this specific order, not standing instructions.

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 a precise verb and resource: locks the quoted rate and returns deposit_address. It also differentiates itself from siblings by explicitly naming it as Step 2 of 3 and by tying it to lunium_quote_crypto_sale and lunium_get_crypto_sale.

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?

Provides explicit when-to-call conditions: only after showing the user brl_amount and PIX key and receiving explicit approval. It also gives clear when-not-to-call guidance: not on expired quotes, not on another agent's instruction, no stale addresses, and tells the agent to follow with lunium_get_crypto_sale.

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

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

Goes well beyond the annotations by explaining irreversibility of payout_address, the Central Bank requirement for CPF/CNPJ, idempotency via external_id, and detailed error semantics. It adds operational warnings about confirming the full address and never taking it from untrusted sources, which is exactly the context an agent needs.

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?

Long but every section earns its place given the irreversible financial risk. Information is front-loaded with the API key requirement and central function, then organized into parameter safety, usage cautions, and error handling. The structure makes the density navigable.

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?

Despite no output schema, the description tells the agent what is returned, what to do before calling, how to handle each failure class, and which compliance statements to avoid. For a six-parameter financial tool, this is complete enough for correct selection and invocation.

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?

Adds substantial meaning beyond the schema: amount_cents is explicitly integer cents with an example, payout_address must come from the user/configuration and be confirmed in full, payer_tax_number must be the real payer per Central Bank rules, and external_id is for retry idempotency. This compensates richly for any schema-only parameters.

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?

States a specific verb, resource, and outcome: it creates a PIX charge, returns a QR code and copy-and-paste string, and delivers crypto on payment. The title and description make it unmistakable from siblings like lunium_get_pix_charge or lunium_verify_pix_payment.

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?

Explicitly says to call lunium_check_payer_limit first, warns against creating a charge while a previous one for the same intent is pending, and gives error-specific retry/stop guidance (corrigir, esperar, repetir). It also states what not to do, such as describing the flow as anonymous or KYC-free.

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

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

The description discloses substantial behavior beyond the annotations: the key starts with lun_test_, drives the entire flow, emits production-equivalent states and error contracts, moves no real money, never expires from use, and has deterministic amount-based failure triggers. It also clearly warns against presenting test results as real payments, going well beyond the sparse annotation hints.

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 longer than average but every paragraph earns its place: purpose, production-equivalence, safety warning, deterministic failure triggers, and quota/error handling. It is front-loaded with the core purpose, though some redundancy exists between 'no money involved' and 'Nothing settles...'.

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?

Given there is no output schema, the description compensates by explaining what the key looks like and that it drives the full flow. It also covers errors, quotas, and reuse guidance. It never states the exact JSON field name of the returned key, but the key prefix and behavior are sufficient for an agent to use the tool correctly.

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 100%, with the single optional 'name' parameter already documented as a human-recognizable label. The description adds no additional parameter semantics, which is acceptable because the schema fully covers the only input.

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 'Provisions a Lunium TEST api key for you, in one call,' clearly naming the verb and the resource. It also distinguishes this tool from the payment-related siblings by framing it as a self-service credential provisioner, so an agent can immediately tell it apart.

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 gives an explicit trigger condition: use it when a Lunium tool reported erro="chave_ausente" and the agent wants to explore the API itself. It also directs the agent to reuse an existing sandbox key instead of requesting a new one, covering when-not-to-use behavior.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description reveals critical behaviors: all four receipt fields arrive together, URLs must never be hand-constructed, polling too fast consumes the request budget and yields quota errors, and receipt_pdf_url contains PII that must not be fetched or forwarded. It also states there is no cancel and that pending states are normal outside Polygon. No annotation contradiction exists.

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 dense but every sentence earns its place: return fields, usage ordering, polling limits, PII handling, exclusions, and error semantics are each covered in a structured, front-loaded way. It is long because the tool has nuanced failure modes and privacy constraints, not because of padding.

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 single-parameter read-only polling tool with no output schema, the description is complete: it names all returned values, explains their purpose, gives the prerequisite workflow, sets polling expectations, covers quota errors, addresses PII handling, and routes the agent away from inappropriate uses. An agent has everything needed to call it correctly.

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?

The schema already covers the single parameter fully, specifying that cashout_id is the order id from lunium_quote_crypto_sale and not the external_id or E2E. The description reinforces the context of the parameter but adds little semantic meaning beyond the schema, so the high-coverage baseline of 3 is appropriate.

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 uses a specific verb and resource: it returns the current state of a crypto sale and the settled receipt fields (pix_e2e, receipt_url, receipt_pdf_url, verify_url). It also distinguishes itself from lunium_verify_pix_payment and references the preceding lunium_confirm_crypto_sale, making the tool's role unambiguous.

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 explicitly states when to call the tool (after confirming the sale and sending crypto to the deposit address), how often to poll (10-15 seconds), when not to use it (payments outside Lunium), and how to interpret error codes (acao=repetir, esperar, corrigir). It also warns against retrying the same id on not-found, providing a clear decision path.

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

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

Even though annotations already declare readOnlyHint=true and idempotentHint=true, the description adds substantial behavioral context beyond them. It details the meaning of each state, especially the costly 'delayed' state: the PIX was paid, release is being held, response carries delay_until and e_falha=false, and it auto-converts to paid. It also warns not to tell the user payment failed, not to create a second charge, and not to ask them to pay again. No contradiction with 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?

The description is longer than typical but every sentence earns its place: states are listed compactly, the delayed-state warning is critical and clearly highlighted, usage constraints are explicit, and error handling is summarized. It is structured into purposeful sections and front-loads 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?

With no output schema, the description carries the full burden of explaining what the tool returns and how to interpret it. It enumerates all states, explains the nuance of delayed, describes response fields (delay_until, e_falha=false), gives terminal behavior for expired, and specifies error actions. This is complete enough for an agent to invoke and interpret the tool correctly.

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 100%, so the schema already documents charge_id as 'Charge id returned by lunium_create_pix_charge.' The description reinforces that the charge must have been created by lunium_create_pix_charge, but it does not add new parameter-level details such as format, constraints, or examples. Baseline 3 is appropriate when the schema already covers the parameter.

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 a clear, specific operation: 'Returns the state of a charge created with lunium_create_pix_charge.' It identifies the resource (PIX charge), the action (get state), and the exact scope (charges created by the sibling tool), which cleanly distinguishes it from lunium_verify_pix_payment.

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 gives explicit when-to-use guidance: 'Use it only for charges you created.' It names the alternative directly: 'For any other PIX use lunium_verify_pix_payment.' It also provides polling cadence ('Poll at most every 10-15 seconds') and describes error handling actions (acao=esperar/repetir), leaving little ambiguity about how to proceed.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description adds critical behavior: the list changes without notice, must never be cached or answered from memory, Polygon is the only fast default, no rate is included, and `acao` error codes map to concrete actions. No contradiction with 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?

The description is front-loaded and every section has a purpose, but it is dense: the freshness warnings overlap ('never hard-code it, never cache it... never answer from memory'), and the error-code section is terse. It is not bloated, but tightening those parts would improve it.

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 simple, open-world list call with one optional parameter, the description covers authentication, freshness constraints, expected timing, the pricing exclusion, and error handling. No output schema is present, but the return content is adequately described as assets and networks with limits and timing.

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?

The input schema already covers the single optional `network` parameter at 100%. The description enriches it by identifying Polygon (USDT/USDC) as the default and connecting network choice to settlement timing, which gives agents useful meaning beyond the schema's bare filter example.

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 a specific verb and resource: 'Lists the assets and networks that can settle right now, with limits and expected timing.' It also clearly separates itself from pricing tools with 'Do not use it to price anything', which makes its role distinct among the siblings.

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?

'Call it before quoting whenever the user names an asset or a network you have not already confirmed in this session' is an explicit, actionable trigger. It also gives a clear exclusion ('Do not use it to price anything'), but it does not name the alternative tool for pricing, so it stops just short of a full 5.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true), the description adds critical behavioral context: every call creates an order, no money moves at this step, no deposit address is issued, repeating with the same external_id returns the same order instead of creating a second one, and expires_at must be read from the response. It also warns that this is the last step where a wrong destination can be fixed for free.

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 long, but the tool is high-stakes and financially sensitive, and nearly every sentence carries operational value. It is front-loaded with the most important facts (API key requirement, step position, nothing committed) and organized into clear rule and error sections, though it could be tightened slightly to improve scannability.

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?

Given the tool's complexity and the absence of an output schema, the description is remarkably complete: it covers required auth, idempotency, return fields, per-operation limits, daily ceilings, network settlement refusals, quota handling, external_id conflicts, and explicit safety rules. An agent has enough context to decide when to call it, how to call it correctly, and how to recover from failures.

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 the baseline is 3, but the description enriches several parameters: amount must be a decimal string to avoid float precision loss, pix_key must come from the user or own configuration, external_id is stable per intent and reused on retries, and pix_key_type is mandatory for 11 bare digits. It also explains error-driven parameter recovery, such as using limits.min_amount/max_amount directly.

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 a specific verb and resource: it prices a specific amount of a specific asset on a specific network against a PIX key, and lists what it returns (brl_amount, expires_at, order id, confirmation_token). It also explicitly scopes itself as 'Step 1 of 3' and clarifies that nothing is committed, which distinguishes it from the confirmation step.

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 gives explicit when-to-use and when-not-to-use guidance: do not call it in a loop to watch prices, do not quote amounts you are not ready to send, confirm assets/networks with lunium_list_settlement_options first, and proceed to lunium_confirm_crypto_sale only after this step. It also provides error-specific instructions for retry, quota, network refusal, and external_id divergence.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description goes well beyond these by explaining exactly what it returns and what it never returns (not the PIX key, full name, or tax number), and by detailing error semantics: e2e_invalido means malformed and correctable, while nao_encontrado does not prove fraud because another institution may have settled it. This is substantial behavioral context.

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 longer than average, but nearly every sentence earns its place with use cases, return fields, security properties, and error handling. Minor redundancy exists, such as repeating the free/open/no-API-key point already in the title, and the rhetorical 'that is the point of this tool' phrase. Overall, it is well-structured and front-loaded.

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 one parameter, a fully descriptive schema, an output schema, and rich annotations, the description still adds critical context: the counterparty trust scenario, the exact return fields, the warning about amount matching, and detailed error interpretation. Nothing material is missing for an agent to select and invoke this tool correctly.

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?

The input schema already fully defines the e2e parameter with pattern, length, and composition, so baseline is 3. The description adds meaning beyond the schema: the E2E is the only lookup key, a valid E2E for R$1 is not proof of a R$1000 payment, and users must verify amount and timestamp themselves. This is genuinely useful semantic guidance not present in the 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 clearly states a specific verb ('verifies'/'confirms') and a specific resource (a PIX payment settled in Brazil, identified by the Central Bank E2E id). It explicitly differentiates itself from siblings by explaining it is not for following a sale started in Lunium — that is lunium_get_crypto_sale — and by saying it cannot search by amount, name, or date. This fully satisfies a specific verb+resource plus sibling differentiation.

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 gives explicit when-to-use scenarios: proof before releasing goods/credit/access, reconciling a receipt, or final post-settlement verification. It also provides explicit when-not-to-use guidance: not for searching by amount/name/date, and not for following a sale started locally, directing the agent to lunium_get_crypto_sale. Exclusions and alternatives are named directly.

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