# Requisitos: Consolidar Tools MCP v2 (Filosofia Deep Agents)

## Descricao

Consolidar as 27 tools do TecJustica MCP Server em 6 tools, inspirados na filosofia dos **Deep Agents** (LangChain) e do **Claude Agent SDK**. O agent que consome o MCP e um **investigador** que explora dados ativamente — precisa de tools para descobrir o que existe (explorar), navegar dados (consultar), e analisar com inteligencia (analisar com LLM).

**Motivacao:**
- 27 tools consomem ~4000+ tokens apenas em definicoes de schema no contexto do agent
- Agents inteligentes (Claude, Gemini) nao precisam de 8 tools especializadas de analise juridica — uma unica tool `analisar` com pergunta em linguagem natural e suficiente
- Falta uma tool de **exploracao** que permita ao agent entender o landscape dos dados antes de mergulhar na analise (padrao investigador dos Deep Agents)
- Respostas grandes sao truncadas brutalmente — precisam de **eviction inteligente** com LLM

**O MCP ja funciona muito bem.** A consolidacao preserva toda inteligencia interna (selecao de modelo, deteccao civel/criminal, selecao inteligente de documentos) e melhora a experiencia do agent consumidor.

## Criterios de Aceitacao

### Consolidacao de Tools
- [ ] Server tem exatamente 6 tools: `explorar_processo`, `consultar_documentos`, `consultar_movimentacoes`, `analisar`, `whoami` + 1 dispatch no explorar para listar/buscar processos
- [ ] Todas as 27 funcionalidades anteriores sao acessiveis via as 6 novas tools
- [ ] Nenhuma funcionalidade foi perdida na consolidacao
- [ ] Schema de tools no contexto do agent reduzido de ~4000 para ~1200 tokens

### Tool `explorar_processo` (NOVA)
- [ ] Retorna mapa completo do processo SEM conteudo pesado: dados basicos, partes, catalogo de documentos (id, nome, tipo, tamanho, data), tipos de documentos (contagem), tipos de movimentacoes (contagem), estatisticas, tipo_processo (civel/criminal)
- [ ] Suporta listar todos os processos (sem parametros) e buscar por parte (com `busca`)
- [ ] Nao faz chamada LLM — apenas queries leves ao banco
- [ ] Catalogo de documentos inclui IDs para uso em `consultar_documentos` e `analisar`

### Tool `consultar_documentos` (consolida 7 tools)
- [ ] Le documento por ID com eviction inteligente (docs > 10k chars resumidos com Gemini)
- [ ] Busca full-text em documentos com snippets de contexto
- [ ] Filtra documentos importantes por prioridade
- [ ] Lista documentos com metadados (sem conteudo)
- [ ] Paginacao com metadata: `total`, `has_more`, `offset`, `limite`

### Tool `consultar_movimentacoes` (consolida 3 tools)
- [ ] Lista movimentacoes de um processo com filtro por tipo
- [ ] Busca movimentacoes por termo na descricao
- [ ] Lista movimentacoes recentes cross-processo (sem numero_processo)
- [ ] Paginacao com metadata consistente

### Tool `analisar` (consolida 17 tools com LLM)
- [ ] Aceita qualquer pergunta em linguagem natural sobre o processo
- [ ] Aceita document_ids para analise de documentos especificos
- [ ] Aceita perspectiva para analise de risco orientada
- [ ] Detecta automaticamente civel/criminal e adapta contexto
- [ ] Seleciona modelo automaticamente (Gemini < 3M chars, Grok > 3M chars)
- [ ] Estrategia markdown-first com fallbacks para contexto grande
- [ ] Permite forcar modelo especifico

### Eviction Inteligente
- [ ] Helper `_smart_response()` resume com Gemini quando conteudo > 10k chars
- [ ] Retorna metadata: `foi_resumido`, `tamanho_original`, `tamanho_final`
- [ ] Instrucoes de resumo adaptadas por tipo (documento, analise, lista)
- [ ] Agent recebe sugestao de como obter dados completos

### Qualidade
- [ ] Todas as docstrings tem: QUANDO usar, formato dos args, formato do retorno, exemplo
- [ ] Todas as docstrings indicam dependencias de outras tools
- [ ] Erros instrutivos padronizados: `{sucesso, erro, sugestao}`
- [ ] Paginacao consistente em todas as tools que retornam listas
- [ ] `ruff check`, `ruff format` e `mypy` passam sem erros

### Prompts Atualizados
- [ ] Todos os `@mcp.prompt` em `server.py` referenciam os novos nomes de tools
- [ ] Prompt `guia_ferramentas` lista apenas as 6 tools com exemplos
- [ ] Prompts seguem padrao: FASE 0 (explorar) → FASE 1 (coletar) → FASE 2 (analisar)

## Dependencias

- `services/supabase_client.py` — todos os 30+ metodos de query permanecem intactos (SEM MUDANCA)
- `services/llm_service.py` — toda logica LLM permanece intacta (SEM MUDANCA)
- `tools/_helpers.py` — base existente com `analisar_com_selecao_modelo()` sera expandida
- FastMCP 2.14+ (framework atual)
- Supabase views: `vw_processo_completo`, `vw_stats_processo`, `vw_documentos_preview`, `vw_documentos_relevantes`, `vw_timeline_processo`, `vw_movimentacoes_recentes`

## Features Relacionadas

- `specs/consolidar-tools-mcp/` — versao anterior da consolidacao (superseded por esta)
- `specs/otimizar-mcp-contexto/` — otimizacao de contexto (parcialmente integrada aqui via eviction)
- `specs/filtros-inteligentes-documentos/` — filtros de documentos (integrado em `consultar_documentos`)
