# Investigando execuções

O melhor uso do MCP do TunnelHub hoje é investigação operacional.

Em vez de navegar manualmente pelo portal, você pode combinar ferramentas para localizar uma execução, abrir o resumo e seguir para logs ou traces.

## Fluxo recomendado

O fluxo mais seguro costuma ser:

1. localizar a execução por janela de tempo;
2. capturar `automationId`, `executionId` e `executionPeriod`;
3. abrir o resumo da execução;
4. aprofundar em logs ou traces.

## Passo 1: encontrar a execução

Use `find_execution_tunnelhub` quando você já tem uma janela de tempo e quer localizar uma execução específica.

Exemplo de parâmetros:

```json
{
  "startDate": "2026-03-17 00:00:00",
  "endDate": "2026-03-17 23:59:59",
  "automationId": "<automation-id>",
  "status": "ERROR"
}
```

Essa etapa é importante porque as ferramentas de detalhe exigem `executionPeriod` no formato `YYYY-MM`.

## Passo 2: abrir o resumo

Depois de encontrar a execução, use `summarize_execution_tunnelhub` ou `get_execution_tunnelhub`.

Exemplo conceitual:

```json
{
  "automationId": "<automation-id>",
  "executionId": "<execution-id>",
  "executionPeriod": "2026-03"
}
```

O resumo é o melhor ponto de entrada para entender:

* status consolidado;
* mensagens principais;
* volume processado;
* indícios iniciais de falha.

## Passo 3: abrir traces

Quando o problema parece técnico, siga para `get_execution_traces_tunnelhub`.

Use filtros quando quiser reduzir ruído, por exemplo:

* `level`;
* `status`;
* `message`;
* `timestampStart` e `timestampEnd`.

Os traces ajudam mais quando você quer reconstruir a sequência de eventos internos da execução.

## Passo 4: abrir logs de processamento

Quando o problema parece ligado a registros de negócio, use `get_execution_logs_tunnelhub`.

Esse caminho é ideal para responder perguntas como:

* quais itens falharam;
* qual ação foi tentada;
* quais mensagens apareceram por item;
* como os metadados definidos no SDK explicam o erro.

## Quando usar cada ferramenta

* `find_execution_tunnelhub`: localizar a execução certa.
* `summarize_execution_tunnelhub`: obter contexto rápido.
* `get_execution_tunnelhub`: abrir o detalhe estruturado.
* `get_execution_traces_tunnelhub`: investigar comportamento técnico.
* `get_execution_logs_tunnelhub`: investigar itens de negócio.

## Exemplo de pergunta em linguagem natural

Você pode pedir algo como:

"Encontre execuções com erro da automação X hoje, resuma a mais recente e destaque os traces com falha."

O bom resultado depende de informar:

* período;
* automação, quando conhecida;
* status desejado;
* profundidade esperada da análise.

## Cuidados práticos

* sempre informe janela de tempo explícita nas buscas;
* guarde `executionPeriod`, porque ele é obrigatório nas ferramentas de detalhe;
* lembre que logs e traces podem conter dados sensíveis dependendo da automação;
* sanitize qualquer saída antes de reutilizar o conteúdo em documentação pública ou tickets externos.