# Requisitos: Fix MCP v4 Bugs — Robustez para Deep Agents

## Descrição

Corrigir 8 bugs identificados na revisão do MCP v4 que afetam a robustez e usabilidade por deep agents. O foco principal é garantir que todas as tools retornem respostas estruturadas (nunca exceções brutas), que o paralelismo funcione de verdade, e que os singletons evitem criação excessiva de conexões.

### Por que é necessário

1. **`analisar` sem try/except** — tool mais importante do MCP retorna stack trace bruto se o LLM falhar; deep agents não conseguem se recuperar
2. **Duplicatas em `listar_processos`** — agente vê o mesmo processo listado múltiplas vezes, desperdica tool calls
3. **Paralelismo falso em `visao_geral_processo`** — 3 "queries paralelas" executam sequencialmente, dobrando latência
4. **Conexões criadas a cada call** — `SupabaseClient` e `LLMService` instanciados novos em cada tool call, sem singleton
5. **Paginação em memória** — `buscar_por_parte` carrega todos os resultados, depois faz slice
6. **Contexto cortado prematuramente** — `_montar_contexto_documentos` usa `break` em vez de `continue`, perde documentos menores
7. **Falso positivo em `stats_documentos`** — processo inexistente retorna zeros em vez de erro
8. **Movimentações sem ID** — `visao_geral_processo` não retorna `id` das movimentações

## Critérios de Aceitação

### Tratamento de erros
- [ ] `analisar` tem try/except global que retorna `erro_instrutivo()` em qualquer exceção
- [ ] Nenhuma tool retorna exceção bruta — sempre `{erro, dica}` estruturado

### Deduplicação
- [ ] `listar_processos()` sem busca retorna processos únicos (sem duplicatas de jobs)

### Performance
- [ ] `visao_geral_processo` executa 3 queries realmente em paralelo via `asyncio.to_thread`
- [ ] `SupabaseClient` usa singleton (mesmo client reutilizado entre calls)
- [ ] `LLMService` usa singleton (mesmo client reutilizado entre calls)

### Correções de dados
- [ ] `_montar_contexto_documentos` usa `continue` em vez de `break` para não perder docs menores
- [ ] `stats_documentos` retorna `erro_instrutivo` quando `total_documentos == 0`
- [ ] `visao_geral_processo` retorna `id` nas movimentações recentes

## Dependências

- Nenhuma dependência externa nova
- Todas as correções são em código Python existente

## Features Relacionadas

- `specs/mcp-v4-deep-agent-tools/` — implementação original das 12 tools
