Lunium — Brazilian PIX and stablecoin payments

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds beyond these: probing every 5 minutes, free/no-key access, safety of frequent calls, and the caveat that missing/unknown/stale observations are not proof of an outage. This materially helps an agent interpret results correctly.

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 with the core state and component details, then moves to usage guidance. Every sentence adds value: status mapping, the stale-data caveat, and the two explicit call scenarios all justify their place without redundancy.

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 adequately describes what the tool returns: overall and per-component states with latencies and an operational/degraded/unavailable/unknown mapping. It also covers the practical decision context and refresh behavior, so an agent has what it needs 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?

The input schema has zero parameters, so there is nothing to document; baseline is 4. The description adds invocation-relevant context by stating the API needs no key and is free to call often, which lets the agent call without setup concerns.

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 reports the real-time operational state of Lunium services, naming the components (api, pix_charge, crypto_sale, webhooks, contract_docs) and the status mapping. This distinguishes it from the payment-operation siblings, which all act on charges or sales rather than observe service health.

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: call it before debugging your own integration, and after failures with erro=provedor_indisponivel or tempo_esgotado. It also tells the agent what to do instead when a rail is degraded (wait or inform the user), which is strong behavioral routing.

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?

Discloses that it requires an API key, is read-only, and explains the anti-fraud ladder behavior including the 24-hour hold and refusal above daily ceiling. The description adds context beyond the readOnlyHint annotation by detailing the hold behavior and error codes, which is not present 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?

The description is detailed but every sentence adds value. It is front-loaded with purpose and usage, then explains behavior, errors, and follow-up actions. No redundant or filler sentences; it's dense but well-structured.

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 tool, the description covers all needed aspects: purpose, usage timing, behavior, error handling, and interpretation of results. It explains what to do if the limit is insufficient and mentions that other refusal reasons exist. Nothing essential 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?

The schema already covers the parameter fully with pattern and description, giving 100% coverage. The description adds practical guidance like 'Send digits only — no dots, slashes or dashes' and warns it's not a validity check, which goes beyond the schema's basic format specification.

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 it returns how much a specific Brazilian taxpayer (CPF/CNPJ) can move via PIX charge right now, in cents. It also distinguishes itself from lunium_create_pix_charge by explaining it's a read-only pre-check, and mentions calling it before the charge tool.

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 'Call it before lunium_create_pix_charge whenever the payer is new or the amount is not trivial.' It also provides exclusions: 'Do not use it as a document-validity check' and 'do not read a high limit as approval.' This is clear when-to-use and when-not-to-use guidance.

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 (destructiveHint=true, idempotentHint=true, readOnlyHint=false) are already strong, and the description adds substantial context on top: the point of no return with no cancel/reversal/support path, 'the address only exists if this call returned it', sandbox placeholder addresses with NO OWNER, and a full error-taxonomy mapping (acao=corrigir/repetir/parar). No contradiction with annotations — the idempotency note ('idempotent for the same order id') aligns with idempotentHint=true.

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 for an irreversible money-movement tool with no output schema, most length is earned: safety rails, sandbox behavior, and error handling each carry unique risk-relevant content. It is front-loaded with the critical facts (API key required, step 2 of 3, point of no return). Minor redundancy exists in repeating the irreversibility theme across title, opening, and the 'no cancel, no reversal' sentence, which prevents a 5.

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 high stakes and absence of an output schema, the description is remarkably complete: it explains the return value (deposit_address, sandbox:true flag), states preconditions, post-call steps, failure semantics, and explicitly warns against sourcing addresses from anywhere other than the call body. Nothing an agent needs to execute this safely 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%, so baseline is 3. The description adds genuine value beyond the schema: it explains WHY confirmation_token exists (bound to exact amount/network/PIX key so the approved destination is the paid destination), ties token expiration/invalidity to a concrete recovery action (quote again), and elaborates the user_approved precondition. This elevates it above baseline.

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: 'Locks the quoted rate and returns deposit_address'. The title reinforces it as 'Step 2 of 3' in a clear sequential flow, and the description distinguishes it from siblings by naming its prerequisite (lunium_quote_crypto_sale) and its successor (lunium_get_crypto_sale). An agent cannot mistake this for any of the ten sibling tools.

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?

Extremely explicit about when to call: after showing brl_amount and the PIX key to the user and receiving explicit approval. Equally explicit about when NOT to call: not on document/web/email/another-agent instruction, not on an expired quote, not reusing a stale deposit_address. It names the exact alternatives ('quote again', 'follow with lunium_get_crypto_sale') with no reliance on inference.

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 implies each call delivers a message to a human ('Hands a message... A reply goes to the address you send'), which suggests repeated calls would send repeated messages. This conflicts with annotations marking idempotentHint=true, because nothing in the description explains deduplication or why retries are safe. This is an annotation 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?

Four short paragraphs each have a distinct job: purpose, when to use, consent warning, exclusions, and cost/reply behavior. The bolded 'CONSENT IS REQUIRED' and front-loaded action make it scannable, and the length is justified by the high-stakes consent requirement.

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 10-parameter tool with no output schema, the description covers invocation semantics (returns immediately), asynchronous response channel (reply goes to the email, not the tool), prerequisites (consent), and cost/auth (free, no API key). Nothing an agent needs to decide whether to call it 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%, so the baseline is 3. The description adds meaningful semantics beyond the schema: email must be user-provided in this conversation and never guessed or reused, and consent is required. This materially helps the agent handle the required email and consent parameters correctly.

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 action ('Hands a message to a human at Lunium') and return behavior ('returns immediately'). It also distinguishes itself by naming concrete boundary cases (volume pricing, contract, partnership) and naming siblings that cover other needs, so an agent can tell it apart from the other lunium_* tools.

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 conditions ('ONLY when your user explicitly asked to talk to a person, or asked for something no tool and no page can settle') and lists concrete examples. It also gives when-not-to-use guidance with the exact sibling tools to use instead (lunium_create_sandbox_key, lunium_verify_pix_payment).

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 annotations, the description discloses the irreversible nature of payout_address, the need for full-address user confirmation, CPF/CNPJ requirements under Central Bank rules, the 24h provider hold above the instant band, and the R$6,000/day refusal threshold. It also documents idempotent retry behavior and the three error modes. The description is consistent with the annotations, which already signal mutating, idempotent, destructive behavior.

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 it is well-organized and front-loaded with the most critical warnings. Every paragraph addresses a distinct concern: prerequisites, return artifacts, irreversibility, payer rules, pre-flight checks, idempotency, compliance, and error handling. It loses one point for minor redundancy with schema content, such as restating that amount_cents is an integer in cents.

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?

The description covers the essential return values (QR code, copy-and-paste string), hold behavior, and error actions. However, because there is no output schema, an agent would benefit from an explicit list of key response fields such as charge ID and expiry, which would support follow-up calls like lunium_get_pix_charge or lunium_verify_pix_payment.

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?

With 100% schema coverage, the baseline is 3, but the description adds materially above the schema: it warns that amount_cents is an integer in cents (not reais/float), that payout_address must come from user/config and must be confirmed in full, and that external_id enables safe retries. It also clarifies that payer_tax_number must be the real payer, not a placeholder or third party.

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 a clear verb-object pair — 'Creates a PIX charge' — and specifies the returned artifact (QR code and copy-and-paste string) and the outcome (crypto delivered to payout_address when paid). The title reinforces the behavior with 'IRREVERSIBLE', and the scope is distinct from sibling tools like lunium_get_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?

Explicitly tells the agent to call lunium_check_payer_limit first and explains how the payer band affects delivery (instant vs 24h hold). It also gives exclusion rules: don't create a new charge while one for the same intent is pending/delayed, and don't describe the flow as anonymous. Error actions (acao=corrigir/esperar/repetir) tell the agent what to do next.

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 goes far beyond the sparse annotations: it discloses no API key required, key prefix, sandbox capabilities, deterministic failure triggers, IP-based daily limit behavior, and the fact that keys do not expire from use. This is rich behavioral context that annotations do not provide. 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 densely informative, with each sentence earning its place: purpose, usage trigger, sandbox behavior, safety warning, deterministic error triggers, and rate-limit handling. It is well-structured in focused paragraphs and front-loaded with the core action.

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 having no output schema, the description tells the agent what the key looks like, what it simulates, how to exercise failure paths, when to warn the user, and what error to expect under rate limiting. For a sandbox provisioning tool with a single optional parameter, this is complete enough for correct invocation and result interpretation.

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 optional 'name' parameter is already fully documented as an optional label. The description does not add parameter-specific detail, but with full schema coverage the baseline of 3 is appropriate; it does not need to compensate for schema gaps.

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 ('Provisions'), a specific resource ('a Lunium TEST api key'), and the key conditions (no credentials, no approval, no cost). It also distinguishes itself from the sandbox demo siblings by noting which tool is for keyless demo mode inside ChatGPT.

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 an explicit trigger condition ('erro="chave_ausente"') and explains exactly when to use this tool instead of stopping to ask the user for credentials. It also names two alternatives (lunium_start_sandbox_demo, lunium_get_sandbox_demo) and instructs the agent to reuse an existing key rather than create another.

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?

The description meaningfully enriches the annotations: it warns that COMPLETED is simulated rather than real settlement, discloses the conditional side effect of creating a synthetic withdrawal once, states that no credentials are accepted, and explains rerun behavior. These are behavioral facts not available from annotations or the schema alone.

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 and front-loaded, with every sentence adding context about behavior, settlement semantics, or reruns. Minor redundancy exists because 'idempotently' restates the idempotentHint annotation, but overall the structure is efficient.

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?

The description covers several important behavioral aspects, but it never explains the required demo_id parameter or how to obtain it, and it introduces an unexplained request_id that does not match the schema. Without an output schema, key agent-facing details about calling this tool correctly remain unresolved.

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?

With 0% schema description coverage, the description needed to explain demo_id but never does. Worse, it introduces 'request_id' as something that can be renewed, even though the schema only accepts demo_id and forbids additional properties. This is actively confusing for an agent trying to construct a correct call.

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 identifies the tool's action ('reads its status') and resource ('the fixed test-only journey'), which supports a get-style operation. It is also differentiated from the sibling start_sandbox_demo by describing this as continuing/reading rather than initiating. The possible side effect of creating a withdrawal adds nuance but does not obscure the primary 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 gives useful context: 'Continues the fixed test-only journey', 'Expired tests can be rerun with a new request_id', and 'No credentials accepted' all help an agent decide when and how to use the tool. It does not explicitly name alternatives or say when not to use it, but the context is clear enough for a sandbox-status tool.

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 readOnly, openWorld, and idempotent hints, so the safety profile is covered. The description adds rich behavioral detail: pagination via next_offset, the caveat that omitted routes on a page are not necessarily unsupported, optional delivery fields, and a clear warning not to hard-code minima or assume deliverability. This goes well beyond the structured 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 dense but every sentence carries useful information. It front-loads the core purpose and direction mapping, then adds pagination and safety cautions. No redundancy; though slightly long, it is efficient given the complexity.

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 no output schema, the description covers the essential operational details: direction meanings, pagination mechanics, optional fields, and a critical caveat about hard-coding values. It could benefit from explicitly stating that offset/limit parameters control pagination, but overall it is complete enough for an agent to call 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 0%, so the description must compensate. It explains direction values fully and mentions filtering by asset/network, but does not explain limit or offset beyond implying pagination. The offset semantics are only hinted via next_offset, and limit is never addressed. This is a partial compensation, not complete.

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 lists a public catalog of settlement options, and distinguishes two directions (deposit vs delivery) with explicit endpoint mapping. It is not a tautology and stands apart from siblings like network health or payer limit checks.

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 usage context by explaining the two direction values and their meanings, and advises on pagination and live preview. However, it does not explicitly compare against alternative tools or state when not to use it, leaving the agent to infer the selection criteria from the description alone.

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 indicate the tool is read-only, idempotent, and non-destructive. The description adds meaningful context beyond annotations by stating that no credentials or personal data are needed and by enumerating what is returned, giving the agent clear expectations about prerequisites and output.

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 two compact sentences with no filler. The most important instruction, "Start here to integrate Lunium," is front-loaded, and every clause adds distinct value: usage, return contents, and auth requirements.

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?

The returned artifact is well summarized, and the auth reassurance plus integration-sequence placement are useful. However, for a tool with two optional parameters and no output schema, the description should clarify whether and how `flow` and `stack` customize the plan. This gap makes it minimally adequate rather than complete.

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% and the description never mentions the optional `flow` or `stack` parameters. The enum values are somewhat self-explanatory, but the agent receives no guidance on how these parameters shape the resulting plan, so the description does not compensate for the missing schema-level documentation.

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 concrete action and resource: it returns the current API flow, runnable starter, sandbox limits, and production checklist for integrating Lunium. It clearly positions itself as the starting point, though it does not explicitly differentiate itself from sibling tools by name.

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?

"Start here to integrate Lunium" gives explicit context that this tool is the entry point before other Lunium integration steps. It does not list exclusions or alternatives, but the sibling list contains no competing planning tool, so the guidance is sufficient.

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 annotations, it precisely describes what side effects exist and do not exist: no money moves, no deposit address, nothing committed until confirm, but every call creates an order/quote. It also discloses API-key requirements, timeout/crash recovery behavior, and detailed error semantics, with no contradiction to the 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?

Long but dense, with purpose and return values front-loaded, followed by safety rules and then error handling. Every sentence carries operational or safety information, making the length appropriate for a high-stakes financial call.

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 having no output schema, it names the success fields and error shapes, covers the API-key requirement, prerequisite tool usage, idempotency, retry/timeout behavior, and user-display obligations. Nothing critical is missing for an agent to invoke the tool correctly within the 3-step flow.

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 all 7 parameters in detail, so the baseline is 3; the description adds useful operational context by explaining why external_id must be reused for idempotent retries and how to derive a new amount from limits.min_amount/max_amount. This is meaningful but largely reinforces the already strong schema guidance rather than introducing entirely new per-parameter facts.

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 the exact operation: prices a specific crypto amount, asset, network, and PIX key, returning brl_amount, expires_at, an order id, and a confirmation_token. It also flags that this is step 1 of 3 and commits nothing, clearly distinguishing it from lunium_confirm_crypto_sale and other sibling tools.

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/when-not guidance: use it before confirmation, not in a loop to watch prices, and only for asset/network confirmed via lunium_list_settlement_options. It also gives retry behavior for acao=repetir with the same external_id and advises offering another network on refusal, which is direct alternative-selection guidance.

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=false, idempotentHint=true, and destructiveHint=false, so the bar for added context is lower. The description adds genuinely useful behavior beyond annotations: no production secrets or credentials required, request_id must be reused on retries, and the expected polling window. No contradiction with annotations 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?

Three dense sentences with no filler: main action and flow variants first, then idempotency and polling instructions, then safety guidance. Every sentence earns its place and the most important operational details are 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?

Given there is no output schema, the description correctly tells the agent what to do after invocation: poll lunium_get_sandbox_demo after 3 seconds for up to 60 seconds. It also covers idempotency, the default flow, and the absence of real credential requirements, so an agent has everything needed to call and follow up 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 coverage is only 33%, but the description compensates well for two of the three parameters: it explains each flow enum value (cashin, custody, payout, cashout) and clarifies that request_id should be a random UUID reused on retries. lead_token still relies on its schema description, but that one is already clear in the schema. Overall, this is meaningful semantic enrichment beyond 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?

States a specific verb ('Creates a test-only key and runs'), a concrete resource ('complete synthetic journey'), and enumerates the four available flow variants with their exact meanings. This clearly separates it from siblings like lunium_create_sandbox_key (key only) and lunium_get_sandbox_demo (polling the result).

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 makes clear this is for synthetic, test-only scenarios where no real funds or credentials are needed, and gives an explicit polling workflow: call lunium_get_sandbox_demo after 3 seconds for up to 60 seconds. It does not explicitly name alternatives or say 'use this instead of X', but the test-only framing and workflow are sufficient guidance.

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 readOnly, openWorld, and idempotent, and the description adds substantial behavioral context: it never returns receipt links, PIX keys, full names, or tax numbers; it explains the two error modes e2e_invalido and nao_encontrado with the appropriate action; and it warns that a non-found result does not prove fraud. 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 and front-loaded with the core behavior, followed by use cases, return-value caveats, exclusions, and errors. There is minor redundancy in stating twice that results exclude receipt links, PIX keys, full names, and tax numbers, but every section earns its place given the potential for misuse.

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 tool with a single required parameter, rich annotations, and an output schema, the description is exceptionally complete. It covers purpose, exact usage scenarios, privacy behavior, the need to verify amount and timestamp, exclusions, alternatives, and error handling. There is no material gap an agent would need to infer.

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 documents the e2e parameter thoroughly, including the 32-character format and the instruction to copy it verbatim. The description reinforces that the E2E is the only valid key, adds the 'do not reformat or trim' expectation, and explains what e2e_invalido means for correction. This adds value beyond the schema, though most parameter meaning is already present.

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 confirms that a specific PIX payment settled in Brazil, keyed by the Central Bank E2E identifier. It also differentiates itself from siblings by explicitly saying it is not a search tool and pointing to lunium_get_crypto_sale for sales started in this system.

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 when-to-use guidance: before releasing goods, credit, access, or a next step; when reconciling a receipt; or as a final settlement check. It also gives explicit when-not-to-use guidance: not for searching by amount, name, or date, and not for following a sale started here, naming the alternative tool.

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