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

# Ferramentas Disponíveis

> Catálogo completo de tools expostas pelo MCP Server da GYRA+, agrupadas por domínio.

<Info>
  **Resumo:** esta página lista todas as tools do MCP Server da GYRA+, agrupadas por domínio (autenticação, relatórios, políticas, webhooks). Cada entrada descreve o que a tool faz, os parâmetros principais e um exemplo de prompt natural que costuma invocá-la.
</Info>

## Autenticação

### `authenticate`

Troca `clientId` + `clientSecret` por um token de sessão (JWT). Geralmente **não precisa ser chamada manualmente**: o MCP autentica e renova o token automaticamente quando `GYRA_CLIENT_ID` e `GYRA_CLIENT_SECRET` estão configurados (ou via custom connector OAuth).

* **Quando usa**: agente que gerencia múltiplas organizações e precisa trocar de contexto on demand.
* **Parâmetros**: `clientId`, `clientSecret`.
* **Retorno**: `{ accessToken, expiresIn }`.

## Relatórios

### `create_report`

Cria uma nova análise para um CPF ou CNPJ.

* **Parâmetros**: `document`, `policyId`, opcional `amount`.
* **Retorno**: objeto `Report` com `id` e status inicial (`PROCESSING`).
* **Prompt típico**: *"roda uma análise no CNPJ 43.591.367/0001-30 com a política Capital de Giro"*.

### `get_report`

Consulta o detalhe de um relatório existente pelo id.

* **Parâmetros**: `reportId`.
* **Retorno**: objeto `Report` completo.
* **Prompt típico**: *"mostra o resultado da análise 6612a7f3..."*.

### `list_reports`

Lista relatórios da organização com filtros.

* **Parâmetros**: opcionais `status`, `document`, `policyId`, `from`, `to`, `limit`, `offset`.
* **Prompt típico**: *"quais foram as 10 últimas análises?"*.

### `count_reports`

Conta quantos relatórios existem que atendem filtros específicos.

* **Parâmetros**: mesmos filtros de `list_reports`.
* **Prompt típico**: *"quantas análises foram negadas este mês?"*.

### `get_section`

Retorna uma seção específica de um relatório.

* **Parâmetros**: `reportId`, `sectionId`.
* **Prompt típico**: *"me traz a seção de processos judiciais desse relatório"*.

### `get_report_section_by_type`

Atalho para pegar seção por tipo, sem precisar saber o `sectionId`.

* **Parâmetros**: `reportId`, `sectionType` (ex: `"LAWSUITS"`, `"BUREAU"`, `"SCR"`).
* **Prompt típico**: *"qual o score do bureau nesse relatório?"*.

### `analyze_report`

Registra uma **análise manual** de um relatório: o usuário submete uma decisão (aprovado/negado) com justificativa, sobrescrevendo ou complementando o resultado automático da política.

* **Parâmetros**: `reportId`, `approved` (boolean), `commentary` (motivo da decisão).
* **Quando usa**: analista de crédito precisa registrar decisão manual (ex.: "aprovado por relacionamento comercial", "negado por política interna").
* **Prompt típico**: *"marca o relatório X como aprovado, justificativa: cliente histórico com bom relacionamento"*.

### `re_analyze_report`

Refaz uma análise manual já registrada em um relatório. Só pode ser usada quando já existe uma análise manual prévia e o usuário tem permissão para revisar.

* **Parâmetros**: `reportId`, `approved`, `commentary`.
* **Quando usa**: revisão de decisão manual anterior (ex.: nova informação chegou e o analista quer alterar o parecer já dado).
* **Prompt típico**: *"reanalisa manualmente esse relatório, mudei minha decisão para negado"*.

### `export_report_sync`

Exporta o relatório em PDF, XLS ou ambos e retorna um link com validade de 7 dias.

* **Parâmetros**: `reportId`, `exportFormat` (`"pdf"`, `"excel"` ou `"both"`).
* **Prompt típico**: *"gera um PDF desse relatório"* ou *"me manda a planilha do relatório"*.

## Políticas

### `list_policies`

Lista as políticas de crédito da organização.

* **Parâmetros**: opcionais `documentType` (`"PF"` / `"PJ"`), `enabled`.
* **Prompt típico**: *"quais políticas PJ estão ativas?"*.

## Webhooks

### `create_webhook`

Cria um webhook para receber notificações de eventos. Um webhook por tipo — registre vários se precisa escutar mais de um.

* **Parâmetros**: `type` (`REPORT`, `REPORT_FINISHED`, `REPORT_STATUS`, `REPORT_EXPORTED`, `CREDIT_POLICY`, `OPERATION`), `url`, `apiKey` (opcional, enviado como header `api-key` nas chamadas).
* **Prompt típico**: *"configura webhook REPORT\_FINISHED apontando para [https://meu-backend/gyra](https://meu-backend/gyra)"*.

### `find_webhooks`

Lista webhooks configurados.

* **Parâmetros**: opcionais `webhookId`, `type`.
* **Prompt típico**: *"quais webhooks eu tenho configurados?"*.

### `delete_webhook`

Remove um webhook.

* **Parâmetros**: `webhookId`.
* **Prompt típico**: *"remove o webhook antigo que não está sendo usado"*.

## Exemplos encadeados

O poder do MCP aparece quando o agente **encadeia** tools sem você precisar dizer qual chamar:

### Exemplo 1, análise completa por conversa

> Você: *"roda uma análise no 43591367000130 com a política padrão PJ e me diz por que foi aprovada ou negada."*

1. Agente chama `list_policies` filtrando por `PJ` para achar a política padrão.
2. Agente chama `create_report` com `document` e `policyId`.
3. Agente faz polling em `get_report` até status `COMPLETED`.
4. Agente chama `get_report_section_by_type` para pegar o breakdown.
5. Agente responde em linguagem natural com a conclusão.

### Exemplo 2, auditoria semanal

> Você: *"quantas análises negadas tivemos esta semana e qual a regra mais frequente de bloqueio?"*

1. Agente chama `count_reports` com `status: "DENIED"` e intervalo de datas.
2. Agente chama `list_reports` com o mesmo filtro.
3. Agente consulta breakdown de cada relatório via `get_report_section_by_type`.
4. Agente agrega e responde.

## Limitações

* **Tools disponíveis refletem o escopo contratado pela organização.** Features não contratadas retornam erro claro.
* **Rate limit aplicável**: mesmas regras da API REST (100 req/min padrão). O cliente MCP retransmite 429 e o modelo espera.
* **Payloads grandes**: relatórios COMPLETO+ podem exceder o limite de contexto do modelo. Use `get_report_section_by_type` em vez de `get_report` para buscar só o que precisa.

## Perguntas frequentes

<AccordionGroup>
  <Accordion title="Posso criar tools customizadas?">
    Por enquanto o catálogo é fechado. Se você precisa de tool específica, fale com o suporte. Se precisa de tool composta, deixe o modelo encadear as existentes (costuma ser suficiente).
  </Accordion>

  <Accordion title="As tools têm descrição em português ou inglês?">
    Os schemas (nomes, parâmetros) estão em inglês para alinhar ao padrão MCP. As descrições funcionais estão em português para que modelos em PT-BR escolham corretamente.
  </Accordion>

  <Accordion title="Como vejo o que o modelo chamou em background?">
    Todo cliente MCP sério (Claude Desktop, Cursor) mostra as tool calls na UI. Além disso, toda chamada fica no log de auditoria do toolbox.
  </Accordion>
</AccordionGroup>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Casos de uso" icon="lightbulb" href="/mcp/casos-de-uso">
    Conversas práticas com exemplos reais.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/mcp/troubleshooting">
    Quando uma tool não é chamada.
  </Card>

  <Card title="Instalação" icon="download" href="/mcp/instalacao">
    Voltar e configurar o cliente.
  </Card>

  <Card title="API REST" icon="code" href="/api-reference/como-funciona">
    Acesso direto sem MCP.
  </Card>
</CardGroup>