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