Description and Allowed Tools

Two optional levers, two very different effects

The URL and label are enough to establish the connection, but they don’t tell Grok how to use the server. Two optional parameters fill this gap and complement each other: server_description explains what the server is for, while allowed_tools—or allowed_tool_names depending on the SDK—decides what it is allowed to touch. The first guides, the second constrains.

server_description: give context to the model

This parameter provides Grok with a natural language description of the server’s capabilities. The model uses it to arbitrate: should it query this server, another one, or none at all?

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."
)

Without this description, Grok only has the individual names and descriptions of the exposed tools. It works, but the model reasons without a big picture: it sees a collection of tools without knowing what they form collectively. A good description gives it three things no tool name can convey: when this server is relevant rather than another, the type of requests to route there, and—often overlooked, often decisive—what the server does not do, which avoids calls doomed to fail.

Write this description as if you were explaining the service to a colleague joining the project. Be specific: “Product technical documentation database” is useful where “Documentation” is not. Name the actions actually possible, like “lets you search, read, and update tickets.” And if the scope is restricted, state it clearly: “read-only access, no modifications” will save the model from a failed attempt.

allowed_tools: narrow the scope

By default, connecting Grok to an MCP server injects all tools that server exposes into the model’s context, without exception. On a CRM, this means creating, modifying, and deleting contacts are accessible just like searching.

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.

The allowed_tool_names parameter reverses this behavior by establishing an explicit whitelist. Anything not on it becomes invisible to the model.

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

Why restrict, even when everything is working

The first reason is security, and it follows the principle of least privilege. If your application only needs to read, do not leave modification or deletion tools within the model’s reach. A successful prompt injection—a malicious instruction slipped into a document Grok analyzes—cannot trigger a delete_contact that was never exposed. The whitelist turns a potential incident into a non-event.

# Read-only for a public chatbot
allowed_tool_names=["search_database", "get_record", "format_data"]

The second reason is performance. Every exposed tool takes up space in the context window, since its name, description, and parameter schema must fit there. An MCP server publishing fifty tools consumes a considerable volume before the user has even asked their question. By dropping down to five truly useful tools, you reclaim that space for what matters: the conversation itself.

The third reason is precision. The more extensive the catalog, the more the model hesitates between similar tools—and two tools with similar descriptions produce unstable choices from one execution to the next. A catalog tightened around your use case makes selection significantly more reliable.

Make the two work together

The result becomes truly clean when you combine both parameters, provided they tell the same story.

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"]
)

Here, the description announces read-only access and the whitelist guarantees it technically. Beware the opposite situation, which happens more often than you think: a description inherited from a previous version that promises write capabilities now removed from the whitelist. The model will attempt the call, fail, and you will spend time hunting for a bug that doesn’t exist. Always review these two parameters together, never separately.

Key takeaways

• server_description helps Grok understand when to use this MCP server
• Without allowed_tools, all server tools are injected into the context
• Restricting tools strengthens security, performance, and precision
• Combine description and restriction for optimal control
• Write the description as a natural language explanation of the server’s capabilities