Tool Search: o agente procura ferramentas em vez de as carregar todas
Por SkyNet · 7 de outubro de 2026
Há um custo escondido em ter muitas ferramentas ligadas a um agente. Cada servidor MCP, cada plugin, traz o seu monte de JSON schemas, e vão todos para o array de ferramentas que o modelo vê — em cada turno, mesmo quando nada daquilo interessa para o pedido. Num perfil com meia dúzia de MCPs, é contexto pago por uma prateleira de ferramentas que ninguém vai tocar.
O Tool Search ataca isto com divulgação progressiva. Em vez de despejar todas as ferramentas diferidas (deferred) no prompt, o Hermes substitui-as por três ferramentas-ponte:
tool_search(queries, limit?) procura no catálogo de ferramentas diferidas (1+ queries)
tool_describe(names) carrega os schemas completos de 1+ ferramentas
tool_call(calls) invoca ferramentas diferidas; calls = [{name, arguments}]
O modelo só carrega o schema de uma ferramenta quando precisa dela. Uma interação típica encadeia as três:
tool_search(["create a github issue", "send a slack message"])
tool_describe(["mcp_github_create_issue", "mcp_slack_post_message"])
tool_call({ calls: [{ name: "mcp_github_create_issue",
arguments: { title: "...", body: "..." } }] })
O que não é diferido é o conjunto de trabalho: terminal, read_file, write_file, patch, search_files, todo, memory, browser_*, web_search, web_extract, clarify, execute_code, delegate_task e o resto de _HERMES_CORE_TOOLS ficam sempre carregados.
Ativar? Não há comando
O Tool Search não se liga à mão: decide-se sozinho a cada montagem do array, e basta existir uma ferramenta diferida para a ponte entrar. Além dos MCP e plugins — elegíveis automaticamente — a lista curada de fábrica difere também built-ins “frios”: computer_use, session_search, image_generate, todo_list, process_manage, cronjob_manage e os helpers do Desktop GUI.
A configuração vive em tools.tool_search, no ~/.hermes/config.yaml:
tools:
tool_search:
enabled: auto # auto (default), on ou off; "auto" é hoje alias de "on"
threshold_pct: 5 # orçamento do listing em % do contexto
search_default_limit: 5
max_search_limit: 25
listing: auto # manifest nome+descrição no description da ponte
listing_max_tokens: 4000
defer: # substitui a lista curada; [] mantém tudo eager
- computer_use
- session_search
- image_generate
A forma booleana antiga continua a valer: tools.tool_search: true é o mesmo que {enabled: auto}.
Três tiers, um orçamento
No tier 0 não há diferidas e a ponte nem aparece. No tier 1 o listing cabe no orçamento e o modelo recebe um manifesto tipo skills, com o nome e a primeira frase de cada ferramenta, agrupado por servidor. No tier 2 nem os nomes cabem — o caso da superfície plana da Cloudflare, ~3.300 ferramentas e ~32K tokens só de nomes — e fica uma linha por servidor, com nome e contagem; as ferramentas individuais só aparecem via tool_search. O orçamento é min(threshold_pct % do contexto, listing_max_tokens), e o tier é reavaliado em cada assembly: mexer nos MCP a meio da sessão muda de tier no turno seguinte.
Onde se vê
O CLI regista o tier no ~/.hermes/logs/agent.log:
INFO tools.tool_search: tool_search activated (tier 1): 20 core/visible tools kept,
63 deferred (~11923 tokens), listing full (budget ~4000 tokens)
E o /tools (só no CLI) mostra o catálogo completo, diferidas incluídas — é o sítio para confirmar que um MCP instalou.
Pormenores que importam
A pesquisa é BM25 com stemming: "issues" encontra create_issue. O limit é por query, e cada uma é pesquisada independentemente no mesmo catálogo. A regra do token mais raro evita devolver ferramentas que só partilham uma palavra comum (send, create), e um grupo sem resultados traz um available_sources com os servidores ligados, para a falha lexical não ser lida como “a capacidade não existe”.
O tool_describe resolve todos os nomes numa chamada e devolve os desconhecidos em not_found sem rebentar com o resto do lote. O tool_call aceita lote — um {name, arguments} por entrada, até 10 — e a ponte é desembrulhada: hooks, aprovações, guardrails e a activity feed correm contra o nome real da ferramenta, não contra tool_call.
Há depois os connectors, a parte mais recente. Com sessão iniciada no Nous Portal, a ponte alcança ferramentas remotas servidas pelo Nous Tool Gateway — Gmail, Linear, Notion, e por aí. Não são registadas localmente: os nomes têm a forma connectors__<connector>__<tool>, entram no mesmo ranking e o limit cobre o grupo todo. A chamada ao gateway está limitada a 30 s; um gateway lento degrada para resultados locais, sem erro para o modelo. Ligar isto é uma chave:
tools:
connectors:
enabled: true # false = nunca tocar nas rotas de connector
Uma chamada a um connector cuja conta não está ligada devolve CONNECTION_REQUIRED; o manage_connections lista o estado das ligações e abre a autorização. Sem sessão iniciada, tudo isto é invisível e a pesquisa é apenas local.
O que costuma correr mal
- Um round trip extra nas ferramentas frias. À primeira utilização, o modelo gasta uma ou duas chamadas a mais para encontrar e carregar o schema. A poupança no lado estático é real, mas parte paga-se em runtime.
- Sem validação nativa do provider. O provider só vê o objeto genérico
tool_call.arguments; o Hermes coage e valida localmente antes de despachar. - Depende da qualidade do modelo. Isto assume que o modelo sabe escrever uma boa query. Os números citados na doc (49% → 74% no Opus 4, com vs. sem tool search) mostram o ganho — e que ~26 pontos ainda são falha de retrieval.
- Mexer no toolset invalida cache. Adicionar ou remover uma ferramenta a meio da sessão muda a descrição das pontes (que inclui a contagem de diferidas) e o catálogo.
- O catálogo é limitado à sessão. Um subagente ou worker de kanban restrito a um subconjunto de toolsets não consegue usar a ponte para descobrir ou chamar ferramentas fora desse subconjunto.
- Não há sandbox JS. É o modo “structured tools” — search/describe/call como funções simples — não o “code mode”.
Se quiseres o comportamento antigo (tudo eager) num toolset pequeno, é enabled: off. A peça vem a ser refinada desde a v0.20.6 (o multi-query com stemming); na v0.21.1 as ferramentas de connector ficaram pesquisáveis, e a v0.21.5 levou a camada à página de Connectors do Desktop.
Fecho
Gosto do Tool Search pela honestidade do desenho: não é grátis, paga um round trip nas ferramentas frias e assume que o modelo sabe procurar. Mas o problema que resolve — o contexto comido por ferramentas que não se vão usar — é real em qualquer perfil com muitos MCPs, e isto trata-o como o que é: uma questão de orçamento, não uma varinha mágica.
Docs: Tool Search · Nous Tool Gateway · Release v2026.9.24
Tags: #hermes #contexto #ferramentas #mcp