Toolsets e ferramentas

O servidor MCP do AmICited registra mais de 300 ferramentas, uma para tudo o que o dashboard pode fazer. Entregar todas essas definições a um modelo a cada requisição consumiria uma grande parte do contexto antes de ele fazer qualquer trabalho, e os modelos escolhem pior as ferramentas em uma lista muito longa. Por isso o servidor as revela progressivamente: seu cliente vê uma lista curta e o agente consulta o resto quando precisa.

Você não precisa gerenciar nada disso. Os agentes seguem o padrão sozinhos, guiados pelas instruções do servidor e pela skill using-amicited. Esta página explica o que eles estão fazendo, para você poder ler uma transcrição ou restringir a superfície de propósito.

O que seu cliente vê#

O tools/list anuncia um conjunto pequeno e fixo:

Como essa lista nunca muda durante uma conversa, o cache de prompt do cliente continua válido, o que mantém sessões longas rápidas e baratas.

Encontrar, inspecionar, executar#

Toda outra ferramenta é alcançada em três passos:

search_tools  {"query": "which prompts cite competitors but not us"}
describe_tool {"name": "seo_get_citation_gap_invisible_winners"}
read_tool     {"name": "seo_get_citation_gap_invisible_winners", "arguments": {...}}

• search_tools ordena as ferramentas por nome, descrição e toolset. Funciona melhor com a pergunta em palavras simples (“is the site down”, “customer lifetime value”) do que com um nome meio lembrado. Passe toolset com uma consulta vazia para navegar por uma área e aumente offset para paginar por uma grande.
• describe_tool retorna o esquema real de argumentos e o tipo da ferramenta. Os agentes devem sempre chamá-lo antes de executar uma ferramenta, porque algumas ferramentas recebem argumentos planos e outras um objeto query aninhado.
• read_tool executa ferramentas cujo tipo é read: leituras gratuitas e repetíveis dos seus próprios dados. Ele recusa qualquer outra coisa, e é por isso que é marcado como somente leitura e que clientes cautelosos (por exemplo, o Codex com aprovações desativadas) podem usá-lo sem parar para perguntar.
• run_tool executa tudo, incluindo os outros três tipos:

Uma ferramenta que não é anunciada não é menos protegida. Toda ferramenta verifica por conta própria as permissões, os limites do plano e os créditos, e o run_tool aplica a verificação de escrita da própria ferramenta de destino, então um token somente leitura não consegue chegar a uma escrita por ele.

Os doze toolsets#

Toda ferramenta pertence a exatamente um toolset. Os agentes os usam para decidir onde pesquisar, e você pode usá-los para fixar uma área (veja abaixo).

Os nomes das ferramentas têm prefixo por área (gsc_, bing_wmt_, google_ppc_, meta_, eshop_, uptime_, ads_), o que facilita percorrer as transcrições.

Fixando toolsets com ?toolsets=#

Alguns clientes lidam mal com uma chamada run_tool aninhada, e às vezes você quer um agente restrito que veja apenas uma área. Adicione um parâmetro de consulta à URL da conexão:

https://api.flowhunt.io/mcp/amicited?toolsets=eshop,uptime
https://api.flowhunt.io/mcp/amicited?toolsets=all

Os toolsets nomeados são então anunciados nativamente no tools/list, junto ao conjunto principal. all anuncia tudo, o que abre mão da economia de contexto, então use-o apenas com clientes que fazem sua própria busca de ferramentas. Nomes desconhecidos são ignorados em vez de rejeitados, então confira a grafia se uma área não aparecer. A seleção é fixa durante toda a vida da conexão; nenhuma ferramenta pode ampliá-la no meio da conversa.

Páginas, campos e limites#

• Páginas de 25 linhas. Toda ferramenta que retorna uma lista de linhas retorna 25 por padrão, até um máximo de 500 por chamada. Quando há mais linhas, a resposta inclui um bloco paging com has_more e o valor a passar na próxima chamada (um offset ou página nativo, ou um next_cursor).
• fields. As ferramentas que retornam uma lista de linhas aceitam um array fields para retornar apenas as colunas de que você precisa. Uma coluna que as linhas não têm é recusada, não ignorada.
• Sem argumento de workspace. O workspace é fixado pela sua credencial, então nenhuma ferramenta aceita um id de workspace. Quase toda ferramenta precisa de um domain_id obtido em list_domains.
• Limite horário. As chamadas de ferramentas são contadas por workspace por hora (veja conectar). Listar ferramentas e ler skills é gratuito; uma ferramenta oculta alcançada por read_tool ou run_tool conta uma vez.

Relacionados#