--- title: Why meta-tools description: CodeSpar provides 14 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"; 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 **14 meta-tools** that intelligently route calls to the right provider, plus `codespar_get_started`, the onboarding planner: it moves no money and is counted apart. 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 14 meta-tools, plus `codespar_get_started` | 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 | --- ## Each one, on its own page Each meta-tool has its own page with the argument shape, the result shape, how it routes between rails, and what the operator has to configure. This page does not repeat that: two copies of one reference diverge, and the one with less detail wins by being closer. | Meta-tool | What it does | |---|---| | [`codespar_charge`](/docs/concepts/meta-tools/charge) | Charges, producing the rail's instrument | | [`codespar_checkout`](/docs/concepts/meta-tools/checkout) | Closes an e-commerce cart | | [`codespar_crypto_pay`](/docs/concepts/meta-tools/crypto-pay) | Pays in stablecoin, settling on-chain | | [`codespar_discover`](/docs/concepts/meta-tools/discover) | Finds the server and the tool for an intent | | [`codespar_get_started`](/docs/concepts/meta-tools/get-started) | The first-integration path | | [`codespar_invoice`](/docs/concepts/meta-tools/invoice) | Issues a fiscal document | | [`codespar_issue`](/docs/concepts/meta-tools/issue) | Issues a card | | [`codespar_kyc`](/docs/concepts/meta-tools/kyc) | Verifies identity and onboards | | [`codespar_ledger`](/docs/concepts/meta-tools/ledger) | Reads and writes the ledger | | [`codespar_manage_connections`](/docs/concepts/meta-tools/manage-connections) | Connects and revokes provider credentials | | [`codespar_notify`](/docs/concepts/meta-tools/notify) | Sends a message over WhatsApp, SMS or email | | [`codespar_pay`](/docs/concepts/meta-tools/pay) | Pays, routing between Pix, card and crypto | | [`codespar_ship`](/docs/concepts/meta-tools/ship) | Books and tracks a delivery | | [`codespar_shop`](/docs/concepts/meta-tools/shop) | Searches for a product in connected stores | | [`codespar_wallet`](/docs/concepts/meta-tools/wallet) | Reads the balance and moves the wallet | ## Server-specific tools In addition to the 14 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 import { CodeSpar } from "@codespar/sdk"; const cs = new CodeSpar({ apiKey: process.env.CODESPAR_API_KEY }); const session = await cs.create("user_123", { servers: ["asaas"] }); // ---cut--- import { tools } from "@codespar/sdk"; const available = await tools(session); // The 14 meta-tools plus codespar_get_started, on every session, whatever `servers` holds. // A provider's own tools are not in this list: call them by name, // `/`, and the catalog resolves them. // "stripe/create_subscription" // "asaas/get_balance" // "mercado-pago/create_preference" // "melhor-envio/calculate_deadline" ``` The tool schema field is `input_schema` (snake_case), following the MCP specification. Not `inputSchema` (camelCase). ## Next steps