---
title: Why meta-tools
description: CodeSpar provides 15 meta-tools that abstract every connected MCP server into a unified commerce interface, reducing context window cost and simplifying agent development.
---
import { Callout } from "fumadocs-ui/components/callout";
import { Cards, Card } from "fumadocs-ui/components/card";
# Tools & Meta-Tools
CodeSpar integrates MCP servers covering every major LatAm commerce API — payments, fiscal compliance, logistics, messaging, banking, ERP, and crypto. Instead of requiring your agent to understand each server's API individually, CodeSpar provides **15 meta-tools** that intelligently route calls to the right provider.
This design is intentional. A typical commerce workflow in Brazil might touch Stripe (cards), Mercado Pago (Pix), SEFAZ (NF-e), Melhor Envio (shipping), and Z-API (WhatsApp). That is 5 providers, each with 10-20 tools, totaling 50-100 tool definitions in the LLM's context window. Meta-tools compress this to 15 stable interfaces regardless of how many providers are connected.
## Why a few meta-tools, not 99 raw tools
### Context window economics
Every tool definition consumes tokens in the LLM's context window. A typical MCP server exposes 10-15 tools, each with a JSON Schema `input_schema` averaging 200-400 tokens. Connect 5 servers and you consume 5,000-15,000 tokens just on tool definitions -- before the conversation even starts.
Meta-tools solve this by providing 15 fixed interfaces that never change regardless of how many servers are connected:
| Approach | Tools in context | Tokens consumed | Agent complexity |
|----------|-----------------|-----------------|------------------|
| Raw server tools (5 servers) | 50-75 | 10,000-30,000 | Agent must know each provider |
| Meta-tools | 15 | ~3,000 | Agent uses unified interface |
### Routing abstraction
When your agent calls `codespar_pay`, CodeSpar inspects the arguments (payment method, currency, amount) and routes to the optimal provider:
1. **Inspects** the arguments to determine payment method and region
2. **Selects** the best available provider for that rail (e.g. Asaas for Pix in Brazil, Conekta for card in Mexico)
3. **Translates** the request to the provider's native API format
4. **Normalizes** the response into a consistent schema
5. **Returns** the result to your agent
Your agent never needs to know which provider handles Pix vs. boleto vs. SPEI. It calls `codespar_pay` with the intent, and CodeSpar handles the routing.
## The 15 meta-tools
| Meta-tool | Purpose | Typical latency |
|-----------|---------|-----------------|
| [`codespar_get_started`](/docs/concepts/meta-tools/get-started) | Read-only setup planner: the ordered happy path for this workspace. Moves no money | 50-150ms |
| `codespar_discover` | Semantic + lexical search across the catalog for tools and servers | 50-150ms |
| `codespar_manage_connections` | Inspect connected providers and start connection flows | 50-200ms |
| `codespar_pay` | Outbound transfers — payouts via Pix, card, wire, or bank transfer. `method: "boleto"` settles an existing boleto rather than issuing one | 400-1200ms |
| `codespar_charge` | Inbound charges — buyer pays merchant via Pix, boleto, card, PSE, or wallet across BR, MX, PE, CO, CL, AR, EC and USD | 400-1200ms |
| [`codespar_checkout`](/docs/concepts/meta-tools/checkout) | Sell-side merchant checkout — assemble a cart and dispatch it as an inbound charge. Pix x BRL x BR is the only rail with catalog lines; `boleto` and `card` refuse with `no_eligible_providers` | 600-2000ms |
| `codespar_shop` | Buy-side shopping — act as the shopper: search a store and buy, minting the store's real Pix (VTEX guest checkout, Mercado Livre) | 600-2000ms |
| `codespar_invoice` | Issue fiscal documents (NFS-e default, NF-e, CFDI, Factura AR) | 500-2000ms |
| `codespar_ship` | Domestic shipping via Melhor Envio (`domestic-quote`, `domestic-label`, `domestic-track`) | 200-600ms |
| `codespar_notify` | Send notifications via WhatsApp, SMS, or email | 100-300ms |
| `codespar_crypto_pay` | Crypto rails — Coinbase Commerce (hosted checkout), Bitso and Foxbit (BR), plus fiat on/offramp | 300-1000ms |
| `codespar_kyc` | KYC / identity verification via Persona, Sift, Konduto, or Truora | 300-1500ms |
| [`codespar_wallet`](/docs/concepts/meta-tools/wallet) | The agent's governed wallet: balance and Pix key, ledger statement, top-up via minted Pix copia-e-cola | 100-400ms |
| `codespar_ledger` | Double-entry ledger (Lerian Midaz) — entry, balance, account | 100-400ms |
| `codespar_issue` | Issue + control payment cards via our card-issuing partner — virtual/physical/freeze/cancel | 300-1000ms |
---
## As quinze, uma a uma
Cada meta-tool tem página própria, com o formato dos argumentos, o formato do resultado, o
roteamento entre trilhos e a configuração que o operador precisa fazer. Esta página não repete
isso: repetir uma referência é criar duas que divergem, e a que tem menos detalhe ganha por
estar mais perto.
| meta-tool | o que faz |
|---|---|
| [`codespar_charge`](/docs/concepts/meta-tools/charge) | Cobra, gerando o instrumento do trilho |
| [`codespar_checkout`](/docs/concepts/meta-tools/checkout) | Fecha um carrinho de e-commerce |
| [`codespar_crypto_pay`](/docs/concepts/meta-tools/crypto-pay) | Paga em stablecoin, com liquidação on-chain |
| [`codespar_discover`](/docs/concepts/meta-tools/discover) | Encontra o servidor e a ferramenta para uma intenção |
| [`codespar_get_started`](/docs/concepts/meta-tools/get-started) | O caminho de primeira integração |
| [`codespar_invoice`](/docs/concepts/meta-tools/invoice) | Emite documento fiscal |
| [`codespar_issue`](/docs/concepts/meta-tools/issue) | Emite cartão |
| [`codespar_kyc`](/docs/concepts/meta-tools/kyc) | Verifica identidade e onboarda |
| [`codespar_ledger`](/docs/concepts/meta-tools/ledger) | Lê e escreve o razão |
| [`codespar_manage_connections`](/docs/concepts/meta-tools/manage-connections) | Conecta e revoga credenciais de provedor |
| [`codespar_notify`](/docs/concepts/meta-tools/notify) | Envia mensagem por WhatsApp, SMS ou e-mail |
| [`codespar_pay`](/docs/concepts/meta-tools/pay) | Paga, roteando entre Pix, cartão e cripto |
| [`codespar_ship`](/docs/concepts/meta-tools/ship) | Contrata e rastreia entrega |
| [`codespar_shop`](/docs/concepts/meta-tools/shop) | Busca produto em lojas conectadas |
| [`codespar_wallet`](/docs/concepts/meta-tools/wallet) | Lê saldo e movimenta a carteira |
## Server-specific tools
In addition to the 15 meta-tools, each connected MCP server exposes its own native tools. These are useful when you need provider-specific features that meta-tools do not cover, such as Stripe subscription management or Mercado Pago installment configuration.
```typescript
const tools = await session.tools();
// Meta-tools are always available (15 tools)
// Server-specific tools depend on connected servers
// Examples:
// "stripe_create_subscription"
// "stripe_create_refund"
// "mercadopago_create_preference"
// "melhor_envio_calculate_deadline"
```
The tool schema field is `input_schema` (snake_case), following the MCP specification. Not `inputSchema` (camelCase).
## Next steps