Ajustar o contexto de ferramentas de um agente

Este guia aborda o trabalho prático em torno da superfície de ferramentas de dois níveis: ver o que uma execução envia, alterar isso e diagnosticar um agente que recorreu à ferramenta errada. Para entender por que funciona assim, leia Contexto de ferramentas e cache de prompts.

Veja o que uma execução realmente envia

Abra uma conversa e toque no indicador de utilização do contexto no cabeçalho da conversa. Ele reconstrói exatamente a superfície que o próximo despacho enviaria, sem executar nada. Ver mais (ou o comando /context) abre o explorador de contexto completo, onde você pode inspecionar cada ferramenta.

Dois segmentos importam aqui:

• Definições de ferramentas e MCP e ferramentas dinâmicas — o conjunto residente, com o custo real em tokens de cada ferramenta.
• Ferramentas carregadas sob demanda — o índice diferido. Cada entrada é cobrada apenas pelo seu nome, porque um nome é tudo o que a requisição carrega; abrir uma delas ainda mostra a descrição e o esquema completos, para você ver quanto ela custaria se a execução a carregasse.

Se o segmento diferido estiver vazio, o diferimento está desativado para este servidor. Verifique --tool-deferral na CLI do cc_server.

Altere quais ferramentas são carregadas de antemão

O conjunto residente é política, não configuração — ele vive em ModeToolPolicy (packages/cc_domain/lib/features/mcp/domain/value_objects/mode_tool_policy.dart) e se aplica a todas as execuções:

• residentBuiltins — o vocabulário de arquivos e shell.
• residentDiscovery — search_tools e list_my_tools. Não remova estas; é por meio delas que um agente alcança todo o resto.
• residentMcpTools — o punhado de ferramentas do Control Center que valem o próprio esquema a cada requisição.
• Um bloco por modo, para as ferramentas que um determinado modo usa quase a cada turno.

Duas regras ao editá-lo:

Adicione uma ferramenta apenas se a maioria das execuções a usar. Todo nome custa o próprio esquema em cada requisição de cada execução, para sempre. Uma ferramenta importante quando usada, mas rara no geral, pertence à metade diferida — o agente ainda vai encontrá-la.

Use o nome real da ferramenta. Um nome residente que não corresponde a nenhuma ferramenta é inerte: nenhum erro, nenhum aviso, a ferramenta simplesmente fica diferida. test/tooling/resident_tool_names_test.dart detecta isso e também mantém cada modo com menos de 40 ferramentas residentes, que é o objetivo do exercício — além dessa faixa, a seleção de ferramentas se degrada de forma mensurável.

Os verbos obrigatórios e fixados de um modo são adicionados automaticamente, então você nunca precisa listar o próprio verbo de saída de um modo.

Diagnostique uma escolha ruim de ferramenta

Quando um agente usou a ferramenta errada ou afirmou que não conseguia fazer algo, descubra qual destas três coisas aconteceu.

1. Ele procurou?

Cada execução registra as ferramentas diferidas que carregou e o que disparou isso — uma chamada direta pelo nome ou uma consulta a search_tools. Abra o fluxo de eventos da execução (Configurações → Espaço de trabalho → Agentes → o agente → Registros → Visualizar) e procure por [harness] loaded N deferred tool(s).

• Nada registrado, e o agente afirmou que a capacidade não existia — ele nunca procurou. Isso é um problema de prompt, não de recuperação: o índice diferido está no prompt de sistema dele, com a instrução de não declarar uma capacidade ausente antes de uma busca voltar vazia.
• Uma busca registrada, mas nada carregado — uma falha de recuperação genuína. Vá para o passo 2.
• Ferramentas carregadas, mas a errada foi usada — as ferramentas que ele encontrou são parecidas demais. Vá para o passo 3.

2. Corrija uma falha de recuperação

search_tools faz correspondência por nomes, descrições e nomes de argumentos. Uma falha quase sempre significa que a descrição não contém as palavras que o agente usou.

Adicione-as. As descrições são o índice de recuperação, então aumente-as em vez de encurtá-las — escreva o vocabulário que um operador realmente digitaria (“atribuir”, “repassar”, “entregar para”), não apenas o substantivo interno. Encurtar uma descrição para economizar tokens custa tanto o acerto de busca quanto a precisão da seleção, e economiza quase nada perto do esquema.

Se a ferramenta certa existe mas tem classificação baixa, é para isso que serve o argumento limit; a própria descrição da ferramenta orienta o agente a ampliar uma busca que parece próxima, mas não encontra.

3. Corrija ferramentas parecidas

Se duas ferramentas têm descrições que soariam iguais para quem já não sabe a diferença, o modelo está adivinhando. Una as duas em uma só ferramenta com um argumento discriminante.

ticket_relation e ticket_pr_link seguem esse padrão: cada um cuida de vincular e desvincular por meio de um argumento discriminante. Uma escolha feita dentro de uma chamada, com o contexto completo da requisição, é mais confiável do que uma escolha feita entre duas descrições parecidas.

Mantenha as ferramentas separadas quando elas precisarem de requisitos de aprovação, auditoria ou renderização diferentes — esses são motivos pelos quais uma fusão custaria algo real.

Verifique se o cache de prompts está funcionando

A taxa de acertos de cache aparece em Observabilidade → Resumo como Taxa de cache. Uma conversa longa e saudável fica alta; se estiver persistentemente baixa, algo está reescrevendo o prefixo a cada turno.

Causas comuns, em ordem de probabilidade:

• Qualquer coisa não determinística no início do prompt. Um carimbo de data e hora, um id de requisição ou um conjunto iterado em ordem variável já bastam.
• Uma mudança de modelo ou de esforço no meio da conversa. Ambas alteram o prefixo. Subagentes são especialmente fáceis de errar aqui: executar os filhos com um esforço menor para economizar dinheiro pode custar mais em compartilhamento de cache perdido do que economiza.
• Compactação frequente. A compactação reescreve o histórico por projeto, então seu custo é real; a solução é compactar raramente e em profundidade, em vez de com frequência e superficialmente.

Desativar o diferimento com --tool-deferral=off é um A/B válido para isolar se uma mudança de comportamento veio da superfície de dois níveis. Ele reproduz exatamente a requisição anterior ao diferimento, então, se o comportamento persistir com ele desativado, a superfície não é a causa.