Descrição e Ferramentas Permitidas
Nesta página
Duas alavancas opcionais, dois efeitos muito diferentes
O URL e o rótulo são suficientes para estabelecer a ligação, mas não indicam ao Grok como utilizar o servidor. Dois parâmetros opcionais colmatam esta lacuna e complementam-se: o server_description explica para que serve o servidor, enquanto o allowed_tools — ou allowed_tool_names, dependendo do SDK — decide o que ele tem permissão para tocar. O primeiro orienta, o segundo restringe.
server_description: dar contexto ao modelo
Este parâmetro fornece ao Grok uma descrição em linguagem natural das capacidades do servidor. O modelo utiliza-a para arbitrar: deve consultar este servidor, outro ou nenhum?
mcp(
server_url="https://api.example.com/mcp",
server_label="docs",
server_description="Technical documentation server. Lets you search articles, consult guides, and get code examples for the internal API."
)
Sem esta descrição, o Grok dispõe apenas dos nomes e descrições individuais das ferramentas expostas. Funciona, mas o modelo raciocina sem uma visão de conjunto: vê uma coleção de ferramentas sem saber o que formam coletivamente. Uma boa descrição fornece-lhe três coisas que nenhum nome de ferramenta consegue transmitir: quando é que este servidor é relevante em vez de outro, o tipo de pedidos a encaminhar para lá e — muitas vezes negligenciado, mas muitas vezes decisivo — o que o servidor não faz, o que evita chamadas condenadas ao fracasso.
Escreva esta descrição como se estivesse a explicar o serviço a um colega que se junta ao projeto. Seja específico: “Base de dados de documentação técnica do produto” é útil, onde “Documentação” não o é. Nomeie as ações realmente possíveis, como “permite pesquisar, ler e atualizar tickets”. E se o âmbito for restrito, indique-o claramente: “acesso apenas de leitura, sem modificações” poupará ao modelo uma tentativa falhada.
allowed_tools: restringir o âmbito
Por predefinição, ligar o Grok a um servidor MCP injeta todas as ferramentas que esse servidor expõe no contexto do modelo, sem exceção. Num CRM, isto significa que criar, modificar e eliminar contactos ficam acessíveis tal como pesquisar.
mcp(server_url="https://api.example.com/mcp",
server_label="crm")
# Grok sees ALL tools: create_contact, update_contact,
# delete_contact, search_contacts, export_data, etc.
O parâmetro allowed_tool_names inverte este comportamento ao estabelecer uma lista branca explícita. Tudo o que não estiver nela torna-se invisível para o modelo.
mcp(server_url="https://api.example.com/mcp",
server_label="crm",
allowed_tool_names=["search_contacts", "get_contact_details"])
# Grok sees only search_contacts and get_contact_details
Porquê restringir, mesmo quando tudo funciona
A primeira razão é a segurança, e segue o princípio do privilégio mínimo. Se a sua aplicação só precisa de ler, não deixe ferramentas de modificação ou eliminação ao alcance do modelo. Uma injeção de prompt bem-sucedida — uma instrução maliciosa inserida num documento que o Grok analisa — não pode desencadear um delete_contact que nunca foi exposto. A lista branca transforma um incidente potencial num não acontecimento.
# Read-only for a public chatbot
allowed_tool_names=["search_database", "get_record", "format_data"]
A segunda razão é o desempenho. Cada ferramenta exposta ocupa espaço na janela de contexto, uma vez que o seu nome, descrição e esquema de parâmetros têm de lá caber. Um servidor MCP que publica cinquenta ferramentas consome um volume considerável antes mesmo de o utilizador fazer a sua pergunta. Ao reduzir para cinco ferramentas verdadeiramente úteis, recupera esse espaço para o que importa: a própria conversa.
A terceira razão é a precisão. Quanto mais extenso for o catálogo, mais o modelo hesita entre ferramentas semelhantes — e duas ferramentas com descrições similares produzem escolhas instáveis de uma execução para outra. Um catálogo ajustado ao seu caso de uso torna a seleção significativamente mais fiável.
Fazer os dois trabalhar em conjunto
O resultado torna-se verdadeiramente limpo quando combina ambos os parâmetros, desde que contem a mesma história.
mcp(
server_url="https://api.example.com/mcp",
server_label="crm",
server_description="Read-only CRM. Search and view contacts and companies.",
allowed_tool_names=["search_contacts", "get_contact", "search_companies", "get_company"]
)
Aqui, a descrição anuncia acesso apenas de leitura e a lista branca garante-o tecnicamente. Cuidado com a situação oposta, que acontece mais frequentemente do que pensa: uma descrição herdada de uma versão anterior que promete capacidades de escrita agora removidas da lista branca. O modelo tentará a chamada, falhará, e você perderá tempo à procura de um erro que não existe. Reveja sempre estes dois parâmetros em conjunto, nunca separadamente.
Pontos-chave
- O
server_descriptionajuda o Grok a entender quando utilizar este servidor MCP - Sem o
allowed_tools, todas as ferramentas do servidor são injetadas no contexto - Restringir ferramentas reforça a segurança, o desempenho e a precisão
- Combine descrição e restrição para um controlo ótimo
- Escreva a descrição como uma explicação em linguagem natural das capacidades do servidor