MCP tools, descriptions and resources in agent workflows

1.Every connected server, one tool pool

In MCP, Claude Code is the host. It creates one client per configured server, and each client holds one stateful session with its server. On connection, the two sides exchange capabilities, and a server that offers tools must declare that it does. The client then asks for the server's tools with a tools/list request.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {
    "cursor": "optional-cursor-value"
  }
}

Discovery runs for every configured server, so when you configure GitHub, Sentry and a database server together, all three sets of tools are available to Claude in the same session. You don't switch between servers. Claude Code labels each tool with the server name you chose, so tools from different servers stay distinguishable. If a server connects but can't list its tools, claude mcp list shows ! Connected · tools fetch failed.

Available doesn't necessarily mean in context. With tool search, which is on by default for current models, MCP tool definitions are deferred and loaded on demand, so a large set of servers doesn't fill the context window before work begins. If a server finishes connecting late, its tools become available on Claude's next request.

Sources123

2.Descriptions that win against built-in tools

Having every tool available creates competition between them. An MCP tool sits next to Claude Code's built-in tools, and Claude chooses largely from names and descriptions. If an MCP code-search tool is described as "Searches code", Claude has no reason to prefer it over a built-in search tool it already knows, even if the MCP tool understands your repository's structure much better. The sources don't discuss Grep specifically, but they are clear about the fix: the description is the lever.

Anthropic's guidance says a good description covers what the tool does, when to use it and when not to, what each parameter means, and its caveats, including what the tool does *not* return. It recommends at least 3–4 sentences, and more for complex tools. For an MCP tool that competes with a built-in, the "when to use it" part should say plainly what it gives you that a plain text search doesn't, and what its output contains. Use namespaced names such as github_list_prs so tools from different services don't blur together.

{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",

The MCP specification gives tools the same fields: a name, a description of what the tool does, and an inputSchema for its parameters. The description that Claude Code shows Claude is the one your server returns from tools/list, so improving it means editing the server's tool definitions.

Sources45

3.Resources: show the catalog, skip the exploring

Without a map of the data, an agent explores. It calls a list tool, then a search tool, then a get tool, just to find out what exists. MCP has a separate primitive for this, the resource. Tools are model-controlled actions. Resources are application-controlled context: data with URIs that a server exposes for the client to attach. Examples include issue summaries, a documentation tree, or a database schema.

A client lists resources with resources/list and fetches one with resources/read. Each entry has a uri and a name, and can optionally have a title, description, mimeType and size. That is enough for an agent to see the whole catalog in one response and read only the item it needs. Annotations add more guidance: audience says whether content is meant for the user or the assistant, and priority (0.0 to 1.0) helps the client decide what to put in context.

{
  "uri": "file:///project/README.md",
  "name": "README.md",
  "title": "Project Documentation",
  "mimeType": "text/markdown",
  "annotations": {
    "audience": ["user"],
    "priority": 0.8,
    "lastModified": "2025-01-12T15:00:58Z"
  }
}

Claude Code supports resources in two ways. When a server offers resources, Claude Code gives Claude tools to list and read them. You can also reference a resource directly in a prompt with an @ mention, which fuzzy-searches resource paths. If the catalog changes, a server that declares listChanged sends a notification so clients can refresh.

Sources63

4.Existing server or custom build?

The Claude Code docs describe two ways to get a server. You can add an existing one: the docs' examples include Notion, Asana, Sentry, Stripe, GitHub, Airtable and a PostgreSQL server, and they point to the Anthropic Directory for more. Or you can build your own with the MCP SDK, helped by an mcp-server-dev plugin with a build skill. The sources don't state a rule for choosing between them. The exam guide's rule is to use an existing server for standard integrations such as Jira and keep custom servers for workflows specific to your team. The architecture supports that split: MCP servers are meant to be focused and composable, so a custom server for your internal workflow can run alongside off-the-shelf servers for standard SaaS.

Sources21

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.Resources are just another kind of tool that the model decides to call.Why is that wrong?

   Resources are application-controlled context that the client attaches and manages. Tools are the model-controlled primitive. Claude Code adds list and read tools so Claude can reach resources.

   Covered in Resources: show the catalog, skip the exploring

2. 2.A short description is enough as long as the tool name is clear.Why is that wrong?

   Anthropic's guidance asks for detailed descriptions covering when to use the tool and when not to, with at least 3–4 sentences per tool.

   Covered in Descriptions that win against built-in tools

Practise it for real

Add a remote MCP server, confirm that its tools reach Claude, and move it from the default scope to user scope.

1. 1.Run claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

   Why: This registers a hosted server. With no --scope flag, it goes into local scope.

   You should see: The server is added for the current project only.

2. 2.Run claude mcp list

   Why: This confirms that the connection and tool discovery succeeded.

   You should see: claude-code-docs shows ✔ Connected.

3. 3.Start claude and ask: Use the claude-code-docs server to look up what MCP_TIMEOUT does

   Why: This shows a discovered MCP tool being called, labelled with the server name you chose.

   You should see: Claude answers using a claude-code-docs tool.

4. 4.Run claude mcp remove claude-code-docs --scope local, then claude mcp add --scope user --transport http claude-code-docs https://code.claude.com/docs/mcp

   Why: This moves the server so it loads in all your projects without being shared.

   You should see: The server is now under the top-level mcpServers key in ~/.claude.json.