{"generated_from":"tools/list","tools":[{"name":"codespar_discover","description":"Find the right tool for a free-form use case. Returns the recommended catalog tool (plus its connection status, known pitfalls, recommended plan, and related tools) AND, in `meta_tools`, any native CodeSpar high-level tools that cover the same job — e.g. 'buy a TV' surfaces codespar_shop, 'send a Pix' surfaces codespar_pay, 'save my address' surfaces codespar_manage_connections. Prefer a native meta-tool when one is returned. Use discover when you don't already know the canonical tool name to call.","inputSchema":{"type":"object","properties":{"use_case":{"type":"string","description":"Free-form description of what you want to accomplish (e.g. 'send an email', 'create a Pix payment')"},"category":{"type":"string","description":"Optional category filter"},"country":{"type":"string","description":"ISO-3166-1 alpha-2 country code or '*' for any"},"limit":{"type":"number","description":"Max related tools returned (1..20, default 5)"}},"required":["use_case"]},"annotations":{"title":"Discover tools","readOnlyHint":true,"openWorldHint":false}},{"name":"codespar_get_started","description":"Get the recommended happy path for this authenticated CodeSpar workspace. Read-only and informational — it returns a structured, ordered plan (it does NOT execute a charge or move money). In the test environment the sandbox rails (Pix in/out, wallet) ship PRE-CONNECTED, so you can run the full flow with no bank connection, CNPJ, or KYC: drive codespar_shop -> codespar_wallet -> codespar_pay under a signed mandate, or use codespar_charge for a Pix in-collection (the buyer pays you). Call this first when a user asks 'how do I start / what can you do' so you can act without a discovery detour. (Named to match the MCP server's no-key setup tool: exactly one codespar_get_started is ever visible — the no-key setup tool mints a key, this authenticated tool hands you the happy path.)","inputSchema":{"type":"object","properties":{}},"annotations":{"title":"Get started (happy path)","readOnlyHint":true,"openWorldHint":false}},{"name":"codespar_manage_connections","description":"List, inspect, or connect the accounts + identity the agent needs. For API-key/OAuth providers (server_id like asaas, nfe-io): action=list|status|initiate surfaces a dashboard connect deep-link — NEVER pass credentials here (they travel via the dashboard or OAuth callback). For login-walled STORES that have no buyer API (server_id=meli or ifood): action=connect_start returns a live-view URL the user opens to log into their OWN account once (their 2FA); then action=connect_finish (with the session_id + context_id from connect_start) persists that login. For meli, the connected login is what codespar_shop buys with on the buyer's own account. iFood checkout is not supported yet: connecting an iFood login only stores the session for a future capability — codespar_shop CANNOT buy on iFood today, so tell the user that BEFORE asking them to log in. For GUEST-checkout stores (VTEX: cobasi/animale/…) the buyer has no login but checkout still needs their data — action=save_profile vaults the buyer's checkout identity ONCE (name, email, CPF, full address; encrypted) so codespar_shop auto-fills it; action=get_profile returns it masked. ALWAYS ASK the buyer which email to use at checkout — do NOT infer it: it's where the order confirmation goes, and an email that already has an account at the store forces a VTEX ID login/identity wall the agent can't pass, so use a dedicated checkout email NOT registered at the store (keeps checkout as guest). save_profile merges field-by-field, so you can save the address first and add the email later; the response returns needs:'email' + profile_complete:false until an email is set. Saving the profile once means later purchases don't re-ask for CEP/email/CPF.","inputSchema":{"type":"object","properties":{"action":{"type":"string","description":"list | status | initiate (dashboard providers) · connect_start | connect_finish (login-walled stores: meli, ifood) · save_profile | get_profile (vaulted shopper identity for guest-checkout stores)"},"server_id":{"type":"string","description":"Provider/store id — required for status, initiate, connect_start, connect_finish (e.g. asaas, nfe-io, meli, ifood)"},"country":{"type":"string","description":"ISO-3166-1 alpha-2 filter (list only)"},"environment":{"type":"string","description":"live | test (default: live)"},"return_to":{"type":"string","description":"Path inside the dashboard to redirect to after the user finishes connecting (initiate only)"},"session_id":{"type":"string","description":"From connect_start — pass it back to connect_finish (login-walled stores)"},"context_id":{"type":"string","description":"From connect_start — pass it back to connect_finish to persist the buyer's login (login-walled stores)"},"consumer_id":{"type":"string","description":"Which buyer is connecting / whose profile to save. Defaults to the session's user id."},"profile":{"type":"object","description":"The buyer's vaulted checkout identity (action=save_profile). Shape: { buyer: { firstName, lastName, email, document (CPF), phone }, address: { postalCode, street, number, neighborhood, city, state, complement } }. Stored encrypted; codespar_shop checkout auto-fills it."}}},"annotations":{"title":"Manage connections","readOnlyHint":false,"openWorldHint":false}},{"name":"codespar_checkout","description":"SELL-side merchant checkout: as a MERCHANT, assemble a cart and create a payment for a shopper to pay YOU. Sums items into a total, dispatches it as an inbound charge on the tenant's connected payment rails, and returns the charge with a hosted payment page (charge_url) plus, on the Pix rail, the pix_copy_paste code. paymentMethod picks the rail: pix (live, BRL default), boleto/card (per catalog); for usdc use codespar_crypto_pay. Distinct from codespar_shop, the buy-side tool where the agent IS the shopper spending its own wallet.","inputSchema":{"type":"object","properties":{"items":{"type":"array","description":"Items to purchase. Each item: { title?, price (major units, e.g. 125.5), quantity? (default 1) }. The total is the sum of price x quantity unless a top-level amount is passed."},"amount":{"type":"number","description":"Optional explicit cart total in MAJOR currency units — wins over the items sum when provided."},"paymentMethod":{"type":"string","description":"Payment method (rail): pix (default) | boleto | card. For usdc, call codespar_crypto_pay."},"currency":{"type":"string","description":"Currency code (default BRL)"},"description":{"type":"string","description":"Optional charge description shown to the shopper; defaults to a summary of the items."},"buyer":{"type":"object","description":"Optional shopper details { name, email?, document?, phone? }; defaults to a guest checkout."},"metadata":{"type":"object","description":"Optional provider metadata (e.g. customer_id for PSPs that require a pre-created customer)."},"recipient":{"type":"string","description":"Recipient identifier"}},"required":["items"]},"annotations":{"title":"Checkout (sell-side)","readOnlyHint":false,"openWorldHint":true}},{"name":"codespar_pay","description":"Execute a direct payment or transfer, read a payment's status, quote a boleto, devolve a received Pix, manage the consumer's DDA registration, or manage the consumer's Pix keys (DICT). Pass action on every call. action=pay executes a payment/transfer with full governance (policy + mandate + routing) — Pix, card, boleto, wire (for USDC/crypto use codespar_crypto_pay). To PAY a store order's Pix copia-e-cola / QR (what codespar_shop checkout returns as pix_copia_e_cola), pass it as `copia_e_cola` — NOT as `recipient`. This routes to the BaaS Pix cash-out rail, which decodes the QR (static or dynamic) and debits the governed wallet. The same field pays a STATIC QR — the code taped to a small merchant's wall — which usually names no value, so `amount` is what gets sent; the result carries `initiation_type` so you can tell the two apart. A static QR carries no charge identifier, so its result says `charge_correlation: 'none'`: `settled` means the rail moved the money, NOT that the merchant marked an order paid — pass the `end_to_end_id` to the payee if they need to reconcile. A Pix cash-out is async: the result has `settled` + `status_message` — status=PROCESSING means ACCEPTED and settling (seconds), NOT failed, and the wallet is already debited. Relay `status_message` to the user, don't surface a bare PROCESSING. To pay an existing boleto, pass method=boleto with linha_digitavel (the boleto's 47/48-digit code or barcode); this settles an EXISTING boleto, it does not issue new boleto charges. action=boleto_quote reads a boleto's TRUE current amount (interest/discount applied) WITHOUT paying it — quote first, then settle with method=boleto passing expected_amount_minor so a stale quote fails cleanly instead of paying a different amount. action=status reads an existing payment/charge/boleto's current status by id (e.g. OVERDUE for an expired/unpaid boleto), so an agent can discover post-purchase state before deciding what to do next; it resolves WHICH provider holds that transaction (a BaaS Pix cash-out, TED or boleto settlement is read back from its own rail, a card/Pix charge from the PSP that minted it) — pass the id a previous codespar_pay / codespar_charge result returned, and pin `provider` when you already know it. method=ted sends a REAL outbound TED (bank wire) from the consumer's governed wallet to a bank account with no Pix key: pass the destination as an object `recipient` ({bank (ISPB), account, branch, tax_id, name, account_type?}) plus a stable `idempotency_key` (REQUIRED — a retry must be the SAME transfer, never a second wire). A TED is a cash-out, so it executes ONLY under a consumer mandate whose SIGNED withdrawal_allowlist names the destination string ted:<ispb>:<branch>:<account> (digits only, no punctuation); without one the call is refused with the consent next-step and nothing is sent — a merchant '*' wildcard never authorizes it. The dda_* actions manage DDA (Débito Direto Autorizado), Brazil's national boleto-visibility register: once a document is registered, every boleto issued against it nationwide is pushed to us and mirrored, so an agent can see and then pay what the consumer owes. No money moves on any of them — pay a discovered boleto with method=boleto passing its linha_digitavel. dda_subscribe REGISTERS the consumer's own CPF/CNPJ (pass document + a stable idempotency_key, REQUIRED — a retry must be the SAME registration, never a second one against a person's document); because registering exposes the titular's boletos, TWO conditions must both hold and neither substitutes for the other: the document must be the one VERIFIED for that consumer's own account at onboarding (a document that is not, including one for a consumer whose account has no verified document yet, is refused with dda_document_not_owned and nothing is sent — the refusal never says which document was expected, so it cannot be used to discover someone's CPF), AND that document must be named in the signed dda_allowlist of an active mandate of that consumer (otherwise refused with dda_document_unauthorized, also having sent nothing; the consumer names it at POST /v1/consents/init, field intent.dda_allowlist; there is no wildcard). Fixing the mandate does not clear dda_document_not_owned: that one is answered by onboarding the consumer whose document it is. Registration is asynchronous: it returns status='pending' and becomes 'active' when the provider's confirmation arrives, so poll dda_status rather than treating pending as failure. dda_status reads that registration and dda_list_due lists the mirrored boletos due in [from_date, to_date] — both are pure local reads that never call the provider, and both are answered for the caller's own organization only. dda_unsubscribe ends a registration the organization actually holds; it needs no mandate, because withdrawing a document from a national register must stay possible after the consumer revokes their consent. The dict_claim_* actions run the Pix DICT key claim lifecycle on the consumer's OWN account (no money moves): dict_claim_open opens an OWNERSHIP or PORTABILITY claim on a key; dict_claim_confirm / dict_claim_cancel act on a claim this consumer opened; dict_claim_status reads one claim; dict_claim_list lists the consumer's claims (either side); dict_claim_respond is the DONOR side — the account currently holding a contested key CONFIRMs (releases it) or REJECTs. The dict_key_* actions manage the keys on the consumer's own account: dict_key_register registers a new Pix key (key_type EMAIL | PHONE | CPF | CNPJ with the key value, or key_type EVP with NO value — Celcoin mints the random key; a CPF/CNPJ key must be the account holder's own document, and a CNPJ key follows the DICT rule of 14 ALPHANUMERIC characters, so the alphanumeric CNPJ is accepted); dict_key_list lists the keys currently registered on the account; dict_key_delete removes a registered Pix key. The account for every DICT action is always resolved server-side from consumer_id — it is never a caller-supplied value. action=pix_devolution RETURNS a Pix the consumer RECEIVED to its original payer (a refund on the Pix rail): pass end_to_end_id (the inbound payment's endToEndId) + idempotency_key (required — reuse the SAME key verbatim on every retry; a devolution moves real money); amount defaults to the full remaining credit when the payment funded the governed wallet, and the destination is always the original payer — it cannot be redirected. The SAME action with payment_direction='outbound' asks the rail to devolve a Pix the consumer SENT (e.g. a payment the agent itself dispatched), returning the money TO the consumer's account: there amount (centavos) is REQUIRED (the sent amount is not on our books), each sent payment gets exactly ONE devolution, and the rail may refuse when the receiver is out of its reach — that refusal comes back as-is, it is not a retry case. Either way, only a payment found on the consumer's OWN account statement (last 7 days) can be devolved. action=pix_devolution_status reads a devolution's state by devolution_id; a devolution settles in seconds but its settlement truth comes from the account statement, so poll this (not action=status) until status='settled'.","inputSchema":{"type":"object","properties":{"action":{"type":"string","description":"pay (execute a payment/transfer) | status (read an existing payment/charge/boleto's status by id) | boleto_quote (read a boleto's true current amount without paying — pure read) dda_subscribe | dda_status | dda_list_due | dda_unsubscribe (DDA — register a consumer's own CPF/CNPJ for national boleto visibility, read that registration, list the boletos it has surfaced, or end it; no money moves) | dict_claim_open | dict_claim_confirm | dict_claim_cancel | dict_claim_status | dict_claim_list | dict_claim_respond (Pix DICT key claim lifecycle — portability/ownership of a Pix key; no money moves) | dict_key_register (register a Pix key on the consumer's own account — key_type EMAIL/PHONE/CPF/CNPJ with the key value, or EVP with no value) | dict_key_list (list the Pix keys registered on the consumer's own account) | dict_key_delete (remove a Pix key from the consumer's own account) | pix_devolution (return a RECEIVED Pix to its original payer — pass end_to_end_id + idempotency_key) | pix_devolution_status (read a devolution's state by devolution_id; settlement truth comes from the account statement, not a provider status-poll). Required — pass it explicitly on every call."},"amount":{"type":"number","description":"Amount to pay, in minor units (centavos for BRL). Must match the copia-e-cola's amount when paying a QR. Required for action=pay. For action=pix_devolution: optional on the default (inbound) direction — the partial amount (centavos) to return; defaults to the full remaining amount of the original credit when the payment funded the governed wallet. REQUIRED when payment_direction='outbound' (the sent amount is not on our books)."},"currency":{"type":"string","description":"Currency code (BRL, USD, EUR). Required for action=pay."},"country":{"type":"string","description":"ISO-3166-1 alpha-2 country code for the eligibility rail (BR, US, MX, AR, CL, CO, INTL). Defaults to BR. Set to US for cross-border USD card via Stripe ACP, INTL for hosted-checkout flows."},"method":{"type":"string","description":"Payment method: pix, card, boleto, ted, wire. method=boleto pays/settles an EXISTING boleto (provide linha_digitavel); it does not issue new boleto charges. method=ted sends a real outbound bank wire under mandate governance — object recipient + idempotency_key required, destination pinned by the mandate's signed withdrawal_allowlist. For USDC or any on-chain settlement use codespar_crypto_pay. With action=status, method (pix | ted | boleto) narrows which rail the status is read from."},"recipient":{"type":"string","description":"EITHER a Pix KEY string (email, phone, CPF/CNPJ, EVP) — the common case — OR an object with bank-account details ({bank, account, branch, tax_id, name, account_type?}) to pay a destination that has no registered Pix key (Pix cash-out via initiationType MANUAL, or the destination of method=ted). Pass the object literally (do not JSON-stringify it) — the tool-call argument type, not this schema's declared string type, is what determines routing. For a copia-e-cola/QR use `copia_e_cola` instead."},"copia_e_cola":{"type":"string","description":"A Pix copia-e-cola / BR Code to PAY (a store order's QR, '0002...'). Use this to pay a checkout's pix_copia_e_cola; the rail resolves the payee. Either recipient OR copia_e_cola is required."},"consumer_id":{"type":"string","description":"Whose governed wallet pays (the payment account to debit). Defaults to the session user — but for a checkout-originated Pix you MUST pass the consumer used in the checkout, otherwise the cash-out resolves no account. Same id as codespar_shop/codespar_wallet."},"checkout_session_id":{"type":"string","description":"To pay a codespar_shop checkout: pass its checkout_session_id and the backend resolves the EXACT Pix copia-e-cola server-side. PREFER THIS over copia_e_cola for a store order — never re-type the long Pix code yourself (re-typing corrupts the CRC). Pass with consumer_id."},"description":{"type":"string","description":"Payment description. Required for action=pay."},"mandateId":{"type":"string","description":"Pre-authorized mandate ID"},"payment_id":{"type":"string","description":"The payment/charge/boleto id to read (action=status) — the id a previous codespar_pay / codespar_charge result returned (an Asaas pay_* id, a BaaS transaction id, or a Pix endToEndId). status returns that provider's status verbatim, e.g. OVERDUE for an expired/unpaid boleto, CONFIRMED for a settled Pix."},"provider":{"type":"string","description":"action=status only: pin WHICH provider holds the transaction — asaas | celcoin — instead of letting the read resolve it from the id. Any other value is refused rather than defaulted. Omit it and the read probes the rails that can answer, in order, and reports the one that holds the id."},"linha_digitavel":{"type":"string","description":"The 47/48-digit linha digitavel (or barcode) of an existing boleto to pay (action=pay, method=boleto) or to quote (action=boleto_quote)"},"expected_amount_minor":{"type":"number","description":"action=pay, method=boleto only: the EXACT amount (minor units) a prior action=boleto_quote returned as true_amount. The settle re-consults the boleto and refuses with amount_mismatch when the fresh true amount differs — no money moves on a stale or wrong quote. Pass it whenever an amount was signed/held from a quote."},"idempotency_key":{"type":"string","description":"Stable per-operation key, reused verbatim on every retry of the SAME operation so a retry never dispatches a second payment (forwarded as the provider's dedupe anchor — e.g. the Celcoin clientRequestId/clientCode). REQUIRED for method=ted, action=pix_devolution and action=dda_subscribe; strongly recommended for method=boleto (ent#783: without it every retry mints a fresh key and Celcoin cannot dedupe). On action=pix_devolution a NEW key for the same payment opens a NEW devolution of the remainder, so reuse the original key to retry rather than to top up."},"client_finality":{"type":"string","description":"method=ted only: Celcoin clientFinality code (documented values 1|3|4|5|7|9|10|100|110|99999; defaults to 1 = generic transfer). 99999 requires a description."},"document":{"type":"string","description":"action=dda_* : the consumer's own CPF or CNPJ (punctuation optional). For dda_subscribe this document is REGISTERED in the national DDA register, so it must be named in the signed dda_allowlist of an active mandate of this consumer — a document nobody consented to is refused and nothing is sent. For dda_status / dda_unsubscribe it identifies which registration to read or end."},"client_name":{"type":"string","description":"action=dda_subscribe only: the document holder's name as it should reach the provider. Defaults to consumer_id when omitted."},"from_date":{"type":"string","description":"action=dda_list_due only (required): list boletos due on or after this date (YYYY-MM-DD)."},"to_date":{"type":"string","description":"action=dda_list_due only (required): list boletos due on or before this date (YYYY-MM-DD)."},"key":{"type":"string","description":"The Pix key: the key being claimed (action=dict_claim_open), the key VALUE to register (action=dict_key_register with key_type EMAIL/PHONE/CPF/CNPJ — omit for EVP), or the key to remove from the consumer's own account (action=dict_key_delete)."},"key_type":{"type":"string","description":"Pix key type. REQUIRED for action=dict_key_register: EMAIL | PHONE (E.164, e.g. +5531999123456) | CPF | CNPJ (must be the account holder's own document) | EVP (Celcoin mints a random key — pass no key value). Optional forwarded hint for action=dict_claim_open."},"claim_type":{"type":"string","description":"action=dict_claim_open (required): OWNERSHIP (contest a key currently resolving to another account) or PORTABILITY (re-point a key the consumer owns at another institution). Also an optional filter on action=dict_claim_list."},"claim_id":{"type":"string","description":"The DICT claim id — required for dict_claim_confirm, dict_claim_cancel, dict_claim_status and dict_claim_respond. Must be a claim this consumer opened (confirm/cancel/status) or is the donor of (respond); any other id is refused."},"reason":{"type":"string","description":"Optional reason for dict_claim_confirm / dict_claim_cancel / dict_claim_respond: USER_REQUESTED (the default on cancel/reject) | ACCOUNT_CLOSURE | FRAUD | DEFAULT_OPERATION. For action=pix_devolution: the Pix return code, default MD06 (user-requested return — the homologated value)."},"end_to_end_id":{"type":"string","description":"action=pix_devolution (required): the ORIGINAL payment's endToEndId — the only reference the rail accepts (an inbound payment's by default; the SENT payment's when payment_direction='outbound'). Only a payment on the consumer's own account statement (last 7 days) can be devolved."},"devolution_id":{"type":"string","description":"action=pix_devolution_status (required): the devolution to read, as returned by action=pix_devolution."},"payment_direction":{"type":"string","description":"action=pix_devolution (optional): the ORIGINAL payment's direction from the consumer's perspective. 'inbound' (default) devolves a payment the consumer RECEIVED, sending the money back to its payer; 'outbound' devolves a payment the consumer SENT, returning the money to the consumer's own account (amount is then required)."},"response":{"type":"string","description":"action=dict_claim_respond (required): CONFIRM (the donor releases the key and the claim completes) or REJECT (the donor keeps the key and the claim is cancelled)."},"status":{"type":"string","description":"action=dict_claim_list only: filter by claim status — OPEN | WAITING_RESOLUTION | CONFIRMED | CANCELLED | COMPLETED."},"date_from":{"type":"string","description":"action=dict_claim_list only: list claims from this date (YYYY-MM-DD)."},"date_to":{"type":"string","description":"action=dict_claim_list only: list claims up to this date (YYYY-MM-DD)."},"limit_per_page":{"type":"number","description":"action=dict_claim_list only: page size."},"page":{"type":"number","description":"action=dict_claim_list only: page number."}},"required":["action"]},"annotations":{"title":"Pay (outbound) / read payment status","readOnlyHint":false,"openWorldHint":true,"destructiveHint":false}},{"name":"codespar_wallet","description":"Programmable wallet for the agent/consumer's governed funds. action=balance returns the wallet balance + Pix key (the spendable funds); action=statement returns the wallet ledger (funds, holds, debits, newest first); action=receive mints a Pix copia-e-cola — a QR a payer pays to TOP UP the wallet (settling credits the wallet via the inbound webhook). Scoped to the consumer (consumer_id defaults to the session user). Distinct from codespar_ledger (the double-entry books) and codespar_pay (spending OUT). Use receive to fund, then codespar_pay to spend.","inputSchema":{"type":"object","properties":{"action":{"type":"string","description":"balance | statement | receive (default: balance)"},"consumer_id":{"type":"string","description":"Whose wallet — defaults to the session user id"},"amount":{"type":"number","description":"Top-up amount in minor units (centavos for BRL) — action=receive"},"description":{"type":"string","description":"Charge description shown to the payer — action=receive"},"dynamic":{"type":"boolean","description":"action=receive: mint a DYNAMIC copia-e-cola (location URL) instead of a static QR. Default false (static)."},"limit":{"type":"number","description":"Max ledger entries (1..100, default 20) — action=statement"}},"required":["action"]},"annotations":{"title":"Wallet (balance, statement, receive)","readOnlyHint":false,"openWorldHint":false},"_meta":{"openai/outputTemplate":"ui://widget/codespar-wallet-64833754.html","openai/toolInvocation/invoking":"Consultando a carteira…","openai/toolInvocation/invoked":"Carteira","openai/widgetAccessible":true}},{"name":"codespar_shop","description":"USE THIS TOOL for ANY request to find, search, browse, compare, or buy products at a supported Brazilian store — Cobasi, Animale, Lojas Pompeia, or Mercado Livre. It returns the store's LIVE, in-stock, actually-BUYABLE catalog (rendered as product cards) with a real Pix checkout — prefer it over a generic web search for these stores, which only returns links you can't buy from. BUY-side shopping: act as the SHOPPER. Search a store's catalog and buy a product, minting the store's REAL Pix copia-e-cola to settle from your governed wallet (codespar_pay × pix). action=search returns card-ready offers for a merchant query — each with product_id, sku_id (USE THIS as the checkout variant_id, NOT product_id), title, price, image, and variants (size options, each its own sku_id). action=checkout STARTS the store's real checkout — a ~1-2 min browser flow (VTEX guest checkout today: Cobasi, Animale, Lojas Pompeia; Mercado Livre via the buyer's connected login) — and returns IMMEDIATELY with { checkout_session_id, status:'in_progress' }; do NOT block. Then poll action=checkout_status with that checkout_session_id every ~15s until status='ready_for_payment', which returns the payable pix_copia_e_cola + total. A status='canceled' carries a structured reason: retriable=true (reason_code 'store_temporarily_unavailable' / 'checkout_failed') is a TEMPORARY store/session fault — re-call action=checkout to retry; it is NOT an out-of-stock. Only reason_code='no_shipping' is a genuine no-delivery/out-of-stock (offer alternatives then). reason_code='identity_required' → the store demands a login the agent can't pass; reason_hint says whether a fresh guest email can work or the store requires login for EVERY purchase (then do NOT retry — no email helps); 'not_connected' → connect the account first. Relay reason_hint to the user. This async checkout-session model is protocol-agnostic (ACP-aligned). Use when the AGENT is the buyer spending money. Distinct from codespar_checkout, the SELL-side merchant primitive.","inputSchema":{"type":"object","properties":{"action":{"type":"string","description":"search | checkout | checkout_status (default: search)"},"merchant":{"type":"string","description":"Store slug: cobasi | animale | lojaspompeia (VTEX), meli (Mercado Livre)"},"query":{"type":"string","description":"What to search for (action=search), e.g. 'tv 55 4k'"},"limit":{"type":"number","description":"Max results returned, 1..20 (action=search)"},"items":{"type":"array","description":"Items to buy: [{ variant_id, quantity, seller? }] (action=checkout, VTEX stores)"},"url":{"type":"string","description":"Listing URL to buy (action=checkout, Mercado Livre — it has no buyer API)"},"paymentMethod":{"type":"string","description":"Settlement rail the store mints — pix (default)"},"consumer_id":{"type":"string","description":"Which buyer is shopping — resolves their connected Mercado Livre login (action=checkout, meli)"},"checkout_session_id":{"type":"string","description":"From action=checkout — pass it to action=checkout_status to poll for the Pix"},"auto_pay":{"type":"boolean","description":"action=checkout_status ONLY: when the order is ready_for_payment, pay it AUTOMATICALLY server-side from the consumer's governed wallet (pass consumer_id) and return status='paid' + a payment receipt. The agent never handles the Pix code or calls codespar_pay — the backend does the payment within the consumer's mandate. Use this to complete a purchase in one shopping flow."},"buyer":{"type":"object","description":"Vaulted shopper profile (email, firstName, lastName, document, phone) — optional"},"address":{"type":"object","description":"Shipping address (postalCode, street, number, neighborhood, city, state, complement) — optional"}},"required":["action"]},"annotations":{"title":"Shop (search & buy)","readOnlyHint":false,"openWorldHint":true},"_meta":{"openai/outputTemplate":"ui://widget/codespar-shop-e8a32efe.html","openai/toolInvocation/invoking":"Buscando produtos…","openai/toolInvocation/invoked":"Produtos encontrados","openai/widgetAccessible":true}},{"name":"codespar_charge","description":"Create an INBOUND charge — the buyer pays the merchant — then read it or cancel it. Pix charge / boleto / cobrança com vencimento / hosted card checkout / digital wallet redirect (PicPay). Distinct from codespar_pay (outbound transfer/payout). action=create (the default; omit action and you get it) issues the charge. In Brazil the instrument follows `method` + `due_date`: method=pix issues an IMMEDIATE Pix charge (a copia-e-cola that expires in the next hour or so, returned right away); method=boleto WITH due_date issues a cobrança com vencimento — ONE receivable the payer settles either as a boleto (barcode + linha digitável) or by Pix, which is what an instalment, an agreement or any invoice with a due date needs. That instrument is registered with the banking clearing house before it becomes payable, so create answers status PROCESSING with no document yet and `payable: false`; the document arrives ~30s later (occasionally up to an hour). Wait for the commerce.charge.created event — subscribe a trigger to it — or poll action=status. Do not treat the empty barcode on create as a failure. action=status and action=cancel serve the cobrança com vencimento only (an immediate Pix charge returns its copia-e-cola at create time and expires on its own — it is not readable or cancellable here). action=status reads a cobrança you issued back, by charge_id (the id create returned) or by the idempotency_key you created it with, and returns the barcode / linha digitável / Pix copia-e-cola once they exist. action=cancel withdraws an unpaid cobrança; the clearing house accepts a cancellation only while the charge is PENDING (a still-registering PROCESSING charge is refused — retry once it registers) and a paid charge cannot be withdrawn. commerce.charge.paid fires when the payer settles it, by either leg. idempotency_key is REQUIRED on create of a cobrança com vencimento: a retry with the same key returns the SAME charge instead of issuing a second receivable the same payer could pay twice, and a call without one is refused before anything is sent. The instrument is issued by Celcoin only and never falls over to another issuer — a refusal is reported, not routed around. That holds for two calls that race under one key as well: the key is reserved before the issuer is called, so exactly one call issues and the other is handed the same charge. When the issuer's answer is lost (timeout, connection reset) the key is kept, not freed: the result names it, a retry under the same key answers issuance_unconfirmed:true and issues nothing, and the charge-create event (or action=status by idempotency_key) resolves it once the clearing house registers the charge — to issue a second receivable on purpose, use a new key. No other create is replayed — retrying an immediate Pix, card or wallet create issues a new charge.","inputSchema":{"type":"object","properties":{"action":{"type":"string","description":"create (issue the charge — the default when omitted) | status (read a charge you issued) | cancel (withdraw an unpaid charge)"},"amount":{"type":"number","description":"Charge amount in major currency unit (R$ 125.00 → 125). Required for action=create."},"currency":{"type":"string","description":"Currency code (BRL, USD, EUR). Required for action=create."},"country":{"type":"string","description":"ISO-3166-1 alpha-2 country code for the eligibility rail (BR, US, MX, AR, CL, CO, INTL). Defaults to BR. Set to US for cross-border USD card via Stripe ACP, INTL for hosted-checkout flows."},"method":{"type":"string","description":"Payment method: pix, boleto, card, wallet. Required for action=create. In BR, boleto + due_date issues the due-dated boleto-and-Pix instrument; pix issues the immediate Pix charge."},"description":{"type":"string","description":"Charge description shown to buyer. Required for action=create."},"buyer":{"type":"object","description":"Buyer details (name, email, document, phone). Required for action=create. For a BR due-dated charge the document is REQUIRED and must be a real CPF/CNPJ — the clearing house validates its check digit, and the charge names who owes it."},"due_date":{"type":"string","description":"Due date, YYYY-MM-DD (a full ISO-8601 instant is accepted and narrowed to the date). Present it with method=boleto to issue a cobrança com vencimento; the immediate Pix charge has no due date and refuses one."},"charge_id":{"type":"string","description":"The cobrança com vencimento to read or withdraw (action=status, action=cancel) — the id its create returned. Resolved against the charges this project issued, so an id from elsewhere is simply not found."},"idempotency_key":{"type":"string","description":"Stable caller key. REQUIRED on action=create of a cobrança com vencimento: a repeat with the same key returns the charge already issued (or its unconfirmed reservation) instead of issuing a second one; on action=status / action=cancel it can stand in for charge_id."},"metadata":{"type":"object","description":"Provider-specific overrides"}}},"annotations":{"title":"Charge a customer","readOnlyHint":false,"openWorldHint":true}},{"name":"codespar_invoice","description":"Issue, read, or amend invoices, NF-e (Nota Fiscal Eletrônica), or NFS-e. action=issue emits a new document (default); action=status reads an existing document's fiscal state (autorizada / cancelada / ...); action=amend corrects an existing document — a correction letter (CC-e) in place while the SEFAZ amendment window is open, or a cancel and reissue as a substitute (tipo 3) once it is not, with the result indicating which mechanism applied. Routes to the Brazilian fiscal rail for NF-e/NFS-e or Stripe Invoicing internationally.","inputSchema":{"type":"object","properties":{"action":{"type":"string","description":"issue (emit, default) | status (read fiscal state) | amend (correct in place via CC-e, or cancel + reissue as a substitute)"},"type":{"type":"string","description":"Invoice type: nfe, nfse, invoice"},"recipient":{"type":"object","description":"Recipient details (name, document, email). Required for action=issue."},"items":{"type":"array","description":"Line items. Required for action=issue."},"dueDate":{"type":"string","description":"Due date (ISO 8601)"},"invoice_id":{"type":"string","description":"The existing document's id to read or amend (action=status, action=amend)"},"correction":{"type":"string","description":"Correction text for an in-window correction letter (CC-e) amendment (action=amend)"},"reason":{"type":"string","description":"Why the document is being amended — drives correction-letter vs cancel-and-reissue (action=amend)"}},"required":["type"]},"annotations":{"title":"Issue invoice (NF-e)","readOnlyHint":false,"openWorldHint":true}},{"name":"codespar_ship","description":"Generate a shipping label OR fetch tracking status. Routes to Melhor Envio (BR domestic — Correios + private carriers), or international carriers via a unified shape. Distinct from canonical melhor-envio/generate_label calls in that the agent passes a neutral {origin, destination, items} shape and the router picks the cheapest carrier per request.","inputSchema":{"type":"object","properties":{"action":{"type":"string","description":"label | track | quote"},"origin":{"type":"object","description":"Sender address (postal_code + city + state)"},"destination":{"type":"object","description":"Recipient address"},"items":{"type":"array","description":"Items to ship — each with weight_g + dimensions"},"service_level":{"type":"string","description":"fastest | cheapest | standard"},"tracking_code":{"type":"string","description":"For action=track only"},"metadata":{"type":"object","description":"Provider-specific overrides"}},"required":["action"]},"annotations":{"title":"Shipping","readOnlyHint":false,"openWorldHint":true}},{"name":"codespar_notify","description":"Send notifications via WhatsApp, email, or SMS. Routes to Z-API for WhatsApp messaging or other channels.","inputSchema":{"type":"object","properties":{"channel":{"type":"string","description":"Notification channel: whatsapp, email, sms"},"to":{"type":"string","description":"Recipient phone number or email"},"template":{"type":"string","description":"Message template name"},"message":{"type":"string","description":"Custom message text"},"variables":{"type":"object","description":"Template variables"}},"required":["channel","to"]},"annotations":{"title":"Notify (WhatsApp)","readOnlyHint":false,"openWorldHint":true}},{"name":"codespar_crypto_pay","description":"Send or receive a crypto payment. USDC/USDT/BTC across mainnet + L2s. Routes to Coinbase Commerce (hosted checkout), Bitso (BR/MX), Foxbit (BR), a BRL-USDC on/offramp partner (cross-border payout), or x402 micropayment protocols. Distinct from codespar_pay (fiat rails).","inputSchema":{"type":"object","properties":{"amount":{"type":"number","description":"Amount in target currency major unit"},"currency":{"type":"string","description":"Crypto currency code: USDC, USDT, BTC, ETH, MATIC"},"network":{"type":"string","description":"Blockchain network: ethereum, polygon, base, solana, bitcoin"},"direction":{"type":"string","description":"send | receive"},"counterparty":{"type":"object","description":"Recipient (send) or buyer (receive). For `direction: send` counterparty is required and must include `country` (ISO 3166-1 alpha-2) so the router + audit log can track the destination of cross-border flows. For `direction: receive` counterparty is optional — the buyer is anonymous until they hit the hosted URL.","properties":{"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code of the recipient (e.g. 'US', 'BR', 'MX'). Required when direction='send'."}}},"metadata":{"type":"object","description":"Provider-specific overrides"}},"required":["amount","currency","direction"]},"annotations":{"title":"Crypto payout","readOnlyHint":false,"openWorldHint":true,"destructiveHint":true}},{"name":"codespar_kyc","description":"Run a KYC / identity verification, OR open a payments account. check_type=identity|document → Persona; risk-score → Sift/Konduto; sanctions → Sift/Truora. check_type=onboarding (BR, natural person / CPF) and check_type=onboarding-business (BR, legal person / CNPJ — PJ/MEI) route to our licensed BaaS partner and are special: they VERIFY (background check + documentoscopia) AND PROVISION a real payment account for the consumer — that account becomes the codespar_wallet funding source (so after onboarding, codespar_wallet balance/receive and codespar_pay work for the same consumer_id). For onboarding-business the documentoscopia target is the responsible partner (buyer.owner[0]), not the company itself. Every check_type returns a verification_id; poll completion with check_type=status (pass verification_id + document_number — the verification_id is required, a status poll with only a document number provisions nothing and refuses with document_ownership_unproven). For onboarding, status returns 'pending' | 'documentscopy_pending' (with a hosted_url to finish doc capture) | 'approved' (with the funding source) | 'rejected'. Sandbox: a phoneNumber ending in 1 auto-approves both gates.","inputSchema":{"type":"object","properties":{"buyer":{"type":"object","description":"Subject. For onboarding (PF): { fullName, document (CPF), email, phoneNumber (+55…; sandbox last digit 1 = auto-approve), birthDate (DD-MM-YYYY), motherName, address, country }. For onboarding-business (PJ/MEI): { document (CNPJ — 14 characters, digits OR letters: Receita's alphanumeric CNPJ is accepted), businessName (razão social), tradingName?, businessEmail, contactNumber, businessAddress (or address), owner: [...] } — owner[] is required and its FIRST entry must be the sócio responsible for documentation (ownerType REPRESENTANTE, full PF data; their CPF is the documentoscopia target). For verification: { name, document, country, email }."},"check_type":{"type":"string","description":"identity | document | risk-score | sanctions | onboarding (open a BR payment account — natural person, CPF) | onboarding-business (open a BR payment account — legal person, CNPJ / PJ / MEI) | status (poll a verification_id)"},"verification_id":{"type":"string","description":"From a prior call — REQUIRED with check_type=status to poll completion. It names the proposal that verified the document, and it is the only thing that provisions a payment account: a status poll without it never binds an account, because a document number an agent typed is not proof the document is the consumer's"},"document_number":{"type":"string","description":"CPF (or CNPJ when polling an onboarding-business proposal) — required with check_type=status (identifies the subject; NOT on its own a licence to bind that person's account). It must be the SAME document the verification_id's proposal verified — never used to look an account up: a mismatch refuses with onboarding_document_mismatch"},"consumer_id":{"type":"string","description":"Whose account/verification — defaults to the session user id (onboarding + status)"},"metadata":{"type":"object","description":"Provider-specific overrides"}},"required":["buyer","check_type"]},"annotations":{"title":"KYC verification","readOnlyHint":false,"openWorldHint":true}},{"name":"codespar_ledger","description":"Record money movement in a double-entry ledger, read account balances, create accounts, or read the agentic receipt of a spend. Routes to the tenant's self-hosted Lerian Midaz instance (multi-currency, multi-asset, immutable + auditable). action=entry posts an n:n journal entry (source debits must equal destination credits); action=balance reads an account's balances; action=account creates an account. action=receipt returns the canonical agentic receipt (the Control Record: mandate -> quote -> payment -> delivery, with a tamper-evident chain hash + any settle-time exceptions) by receipt_id; action=receipts lists a consumer's receipts (newest first). Amounts are in minor units. The ledger is asset-agnostic — no currency/country needed. Distinct from codespar_pay/charge (those move real money via PSPs); this is the system of record / books.","inputSchema":{"type":"object","properties":{"action":{"type":"string","description":"entry | balance | account | receipt | receipts (default: entry)"},"receipt_id":{"type":"string","description":"The agentic receipt id (rcpt_...) to read (action=receipt)."},"consumer_id":{"type":"string","description":"Whose receipts to list (action=receipts). Defaults to the session user."},"limit":{"type":"number","description":"Max receipts to list (action=receipts, default 50)."},"asset":{"type":"string","description":"Asset / currency code for entry + account (BRL, USD, USDC, ...)"},"scale":{"type":"number","description":"Decimal places for the asset (default 2; JPY=0, most crypto=6/8)"},"source":{"type":"array","description":"Debit side(s) of an entry: [{ account (alias), amount (minor units) }]"},"destination":{"type":"array","description":"Credit side(s) of an entry: [{ account (alias), amount (minor units) }]"},"description":{"type":"string","description":"Transaction description (entry only)"},"account":{"type":"string","description":"Account UUID to read balances for (action=balance)"},"alias":{"type":"string","description":"Account alias, e.g. @wallet/user_123 (action=account)"},"name":{"type":"string","description":"Account display name (action=account)"},"type":{"type":"string","description":"Midaz account type: deposit, savings, external (action=account, default deposit)"},"metadata":{"type":"object","description":"Free-form metadata stored on the entry / account"}},"required":["action"]},"annotations":{"title":"Ledger","readOnlyHint":true,"openWorldHint":false}},{"name":"codespar_issue","description":"Issue and control payment cards for AI agents or end-users. Routes to our card-issuing partner (pan-LATAM issuing-as-a-service). action=card-virtual issues a virtual card (active immediately); card-physical issues a physical card (needs shipping_address); card-control freezes/unfreezes/cancels an existing card; card-get reads a card's status. This is the agent-spend-card primitive (the Mesada use case) — it creates SPEND INSTRUMENTS, distinct from codespar_pay/charge which move money.","inputSchema":{"type":"object","properties":{"action":{"type":"string","description":"card-virtual | card-physical | card-control | card-get (default: card-virtual)"},"cardholder_id":{"type":"string","description":"Cardholder id at the issuer. Required to issue a card."},"program_id":{"type":"string","description":"Card program / BIN (issuer affinity group). Required to issue a card."},"card_id":{"type":"string","description":"Card id — required for card-control and card-get."},"control":{"type":"string","description":"freeze | unfreeze | cancel (card-control only)"},"reason":{"type":"string","description":"Reason stamped on a control action"},"shipping_address":{"type":"object","description":"Shipping address (card-physical only)"},"metadata":{"type":"object","description":"Provider-specific overrides"}},"required":["action"]},"annotations":{"title":"Issue card","readOnlyHint":false,"openWorldHint":true}}]}