> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wovepay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools

> Referência de tools do WovePay MCP — discovery, auto-geradas, compostas e docs

## Discovery (metadados)

| Tool                | Quando usar                                      |
| ------------------- | ------------------------------------------------ |
| `list_specs`        | Ver versões OpenAPI (`v1`, futuro `v2`)          |
| `list_operations`   | Listar todos os `operationId` (filtro por `tag`) |
| `get_operation`     | Schema completo de uma operação                  |
| `search_operations` | Buscar por nome, path ou descrição               |
| `execute_operation` | Executar qualquer operação por `operationId`     |

### execute\_operation

Execução **sempre por operationId** — nunca por path/method cru:

```json theme={null}
{
  "operationId": "createPaymentPix",
  "body": { "amount": 100, "description": "Pedido 123" },
  "pathParams": {},
  "query": {},
  "paginate": false,
  "idempotencyKey": "opcional-uuid"
}
```

Resposta **HAR-like**:

```json theme={null}
{
  "request": { "method": "POST", "url": "...", "headers": { "X-API-Key": "[REDACTED]" } },
  "response": { "status": 200, "headers": {}, "body": {} },
  "durationMs": 52,
  "rateLimit": { "remaining": 98, "limit": 100 }
}
```

### Paginação automática

Endpoints com `page` + `limit` aceitam `paginate: true`:

```json theme={null}
{
  "operationId": "listPaymentPix",
  "paginate": true,
  "maxPages": 10
}
```

## Tools auto-geradas

Cada `operationId` do OpenAPI v1 é registrado como tool individual no startup — **101 tools** atualmente.

Exemplos: `createPaymentPix`, `getAccountBalance`, `createWebhook`, `listStoreProducts`.

Mudou o OpenAPI → rebuild do MCP → tools atualizam automaticamente. Validação via **Ajv** (zero schema duplicado).

## Documentação

| Tool                         | Descrição                                                                                     |
| ---------------------------- | --------------------------------------------------------------------------------------------- |
| `search_docs`                | Busca no índice local; filtro opcional `topic`: `bot`, `websocket`, `webhook`, `pix`, `store` |
| `fetch_doc`                  | Markdown completo por `id`                                                                    |
| `recommend_integration_mode` | Recomenda WebSocket vs webhook — ideal para bots Discord/Telegram                             |

### recommend\_integration\_mode

```json theme={null}
{
  "platform": "discord",
  "hasPublicHttps": false,
  "description": "bot de venda com cargo VIP"
}
```

Retorna `recommended` (`websocket` | `webhook` | `backend-only`), passos e resources MCP relacionados.

## Ferramentas compostas

Resolvem tarefas completas em uma chamada:

| Tool                | Fluxo interno                              |
| ------------------- | ------------------------------------------ |
| `debug_api_key`     | Testa auth → saldo → listagem PIX          |
| `configure_webhook` | Valida HTTPS → registra → retorna `secret` |
| `create_checkout`   | Produto → payment link → URL de checkout   |
| `analyze_webhook`   | Explica payload + HMAC (sem API key)       |

## Resources

| URI                           | Conteúdo                         |
| ----------------------------- | -------------------------------- |
| `WovePay://spec/v1`           | OpenAPI completo                 |
| `WovePay://docs`              | Índice llms.txt                  |
| `WovePay://examples`          | JSONs de exemplo                 |
| `WovePay://webhooks`          | Guia de webhooks                 |
| `WovePay://websocket`         | Protocolo WebSocket              |
| `WovePay://websocket-pratica` | Tutorial WebSocket passo a passo |
| `WovePay://bots-playbook`     | Matriz bot / webhook / WebSocket |
| `WovePay://playbook/bots`     | Mesmo playbook (alias)           |
| `WovePay://errors`            | Tabela de erros HTTP             |
| `WovePay://changelog`         | Changelog                        |

## Bots — fluxo recomendado

1. `recommend_integration_mode` com `platform: discord` (ou telegram/whatsapp)
2. Ler `WovePay://bots-playbook`
3. `createPaymentPix` com `externalReference` único
4. WebSocket `wss://ws.WovePay.com.br/v1` → subscribe `payment.*`
5. Entregar produto no `payment.paid` + `ack`

## Retry e rate limit

* Retry automático em `429`, `500`, `502`, `503` (backoff exponencial, max 3)
* Respeita header `Retry-After`
* Rate limit da API: 100 req/min por key — veja `rateLimit` na resposta HAR