# MCP tool discovery: how agents find new tools

URL: https://systemdesignsimple.com/how-ai-agents-find-mcp-tools/
Published: 2026-11-16
Category: AI Systems
Publisher: System Design Simple (https://systemdesignsimple.com)

## Summary

An AI agent finds a new MCP tool by asking for it: the client sends tools/list and the server replies with one entry per tool. In the MCP specification 2025-06-18 an entry needs only two members, name and inputSchema; the rest are optional, and the schema calls the description a hint to the model. Servers that declared listChanged SHOULD send notifications/tools/list_changed when tools change.

## Key facts

- **Tool entry (MCP schema 2025-06-18):** Required: name and inputSchema. Optional: title, description, outputSchema, annotations, _meta
- **Description:** The schema says clients can use it to improve the model's understanding of the tools, like a hint
- **Discovery:** Clients send tools/list; the operation supports pagination through nextCursor
- **Other lists:** resources/list for resources and prompts/list for prompts, both paginated
- **Changes:** Servers that declared the listChanged capability SHOULD send notifications/tools/list_changed
- **Architecture:** Client-host-server: the host creates clients, each client holds one connection to one server

In MCP tool discovery, the agent's MCP client sends `tools/list` and the server replies with one entry per tool. Each entry requires `name` and `inputSchema`; an optional description explains its purpose.

This article covers MCP specification 2025-06-18.

## How does MCP tool discovery work? {#find}

MCP uses a client-host-server architecture ([Architecture](https://modelcontextprotocol.io/specification/2025-06-18/architecture)). The host is the AI app you use. It creates one client per server, and each client keeps one stateful session with its server. The server is the program that offers tools and runs them.

Once the session is set up, the client asks the server what it offers. The Tools page says clients send a <code>tools/list</code> request to discover tools, and that this operation supports pagination ([Tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools)). A reply may carry a <code>nextCursor</code>; if it does, there may be more tools, and the client can send <code>tools/list</code> again with that cursor.

We walked through the full handshake (<code>initialize</code>, the initialized notice, then <code>tools/list</code>) in [MCP tool discovery: 3 new apps, 0 changes to the client code](/how-ai-learns-new-apps-tool-discovery/).

## What fields does an MCP tool need? {#fields}

The schema defines a <code>Tool</code> as a TypeScript interface. Members without a <code>?</code> are required. There are two: <code>name</code> and <code>inputSchema</code> ([Schema: Tool](https://modelcontextprotocol.io/specification/2025-06-18/schema#tool)).

[Image: MCP Schema Reference page showing interface Tool: name and inputSchema without a question mark, title, description and outputSchema with one | The Tool interface on the MCP Schema Reference, version 2025-06-18. Captured 2026-11-15 (UTC). Source: [modelcontextprotocol.io](https://modelcontextprotocol.io/specification/2025-06-18/schema#tool).]

| Member | Required? | What it carries |
|---|---|---|
| <code>name</code> | Yes | The identifier the client uses to call the tool |
| <code>inputSchema</code> | Yes | A JSON Schema object (<code>type: "object"</code>) for the arguments |
| <code>title</code> | No | A display name for people |
| <code>description</code> | No | Human-readable text about the tool |
| <code>outputSchema</code> | No | A JSON Schema for structured results |
| <code>annotations</code> | No | Optional properties describing how the tool behaves |
| <code>_meta</code> | No | Extra metadata (see the spec's General fields) |

The entry only describes the tool. The code that does the work stays on the server, and the client calls it later with <code>tools/call</code>, passing the name and arguments.

The Tools page adds one trust rule: clients MUST treat annotations as untrusted unless they come from trusted servers ([Tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools)). Every field in the entry is text the server chose to send.

## What does the description add? {#hint}

On <code>description</code>, the schema says clients can use it to improve the model's understanding of the available tools: "It can be thought of like a 'hint' to the model." ([Schema: Tool](https://modelcontextprotocol.io/specification/2025-06-18/schema#tool)).

Here is a concept example, not taken from any real server. A server sends an entry with only the required top-level fields:

```json
{
  "tools": [
    {
      "name": "get_wx",
      "inputSchema": {
        "type": "object",
        "properties": { "city": { "type": "string" } },
        "required": ["city"]
      }
    }
  ]
}
```

That entry is valid, but the model gets only a short name and one string called <code>city</code>, and <code>wx</code> could mean weather or something else that takes a city. A clear name and schema descriptions already carry meaning; the optional title and description add a sentence on top:

```json
{
  "tools": [
    {
      "name": "get_wx",
      "title": "Weather today",
      "description": "Gets today's weather for one city. Use when the user asks about weather.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "city": { "type": "string", "description": "City name, for example Kathmandu" }
        },
        "required": ["city"]
      }
    }
  ]
}
```

Write the description the way you would brief a new teammate: what the tool does, when to use it, and what each input means. In our AI 13 simulation, replacing one app's descriptions with vague text cut a keyword matcher's correct picks from 17 of 20 to 8 of 20; that matcher was not a language model, so it says nothing about how much a real model relies on each field ([AI 13](/how-ai-learns-new-apps-tool-discovery/)). Descriptions are also text the model reads and may follow, which is why [a hidden line can steer an AI](/why-the-ai-obeyed-a-hidden-line/) when it comes from an untrusted source.

## Who decides when a tool is called? {#who-calls}

The Tools page says tools are "designed to be model-controlled": the model can discover and call them based on context and the user's prompt ([Tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools)). The same paragraph says implementations may expose tools through any interface they like, and the protocol does not require a particular user interaction model.

So the host can hand the tool list to the model, and the model can pick one to call. The host decides how. For safety the spec says there SHOULD always be a human in the loop who can deny a tool call, with clear signs of which tools are exposed and when one runs. Our article on [AI agent permissions](/would-an-ai-agent-delete-my-files/) shows why that confirmation step matters.

## Resources and prompts have their own lists {#lists}

Tools are one of three things an MCP server can offer. The other two have their own list calls, and both support pagination too.

| Feature | Discovery request | Who is meant to control it |
|---|---|---|
| Tools | <code>tools/list</code> | The model (model-controlled) |
| Resources | <code>resources/list</code> | The application (application-driven) |
| Prompts | <code>prompts/list</code> | The user (user-controlled) |

A resource is context such as a file or a database schema, identified by a URI; the host app decides how to use it ([Resources](https://modelcontextprotocol.io/specification/2025-06-18/server/resources)). A prompt is a template the user picks on purpose, for example through a slash command ([Prompts](https://modelcontextprotocol.io/specification/2025-06-18/server/prompts)). A client that only calls <code>tools/list</code> never sees the other two.

## What happens when a server adds a tool later? {#changes}

The client's tool list is a snapshot from its last <code>tools/list</code>. If the server adds a tool after that, the client still holds the old list until a capability and a notification tell it otherwise.

A server that supports tools must declare the <code>tools</code> capability, and <code>listChanged</code> inside it says whether the server will send change notifications ([Tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools)):

```json
{ "capabilities": { "tools": { "listChanged": true } } }
```

When the list changes, servers that declared <code>listChanged</code> SHOULD send the notification <code>notifications/tools/list_changed</code>.

[Image: MCP Tools page section 3.3 List Changed Notification: servers that declared the listChanged capability SHOULD send a notification, with the notifications/tools/list_changed message | Section 3.3 of the MCP Tools page, version 2025-06-18. Captured 2026-11-15 (UTC). Source: [modelcontextprotocol.io](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#list-changed-notification).]

SHOULD is a recommendation (MUST would be a requirement), and it applies only to servers that declared the capability. The notification carries no tool list either; it only tells the client that the list changed, and the client can then send <code>tools/list</code> again. Resources and prompts have matching notifications on their own pages.

If a server declared <code>listChanged: false</code>, or left it out, your client should not count on a notification and has to decide for itself when to list again.

## Is this service discovery? {#service-discovery}

Partly. In [service discovery (Part 20)](/service-discovery/), a client looks up in a registry where a service lives. In MCP the client is already connected to the server and knows its address, so it asks what the server can do.

## Try it: one tools/list exchange you can print {#run-it}

Our repo has a small stand-in you can run with Node 22 and no installs: <code>node labs/ai-35/measure-tiny-mcp-server-discovery.mjs</code>. It is an in-process simulation, not the official SDK. A hand-written server stand-in talks to a scripted client over an in-memory pipe instead of stdio, and no model reads the result. It also skips pagination and list-changed notifications. We ran it on 2026-11-16 (Node 22.13.1), and every check passed.

On the wire, discovery is one JSON-RPC request and one matching response. After the lifecycle checks, the simulated client sends <code>tools/list</code> with id 5 ([Tools: listing tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#listing-tools)):

```json
{ "jsonrpc": "2.0", "id": 5, "method": "tools/list", "params": {} }
```

The server answers with the same id, and the tool list sits inside <code>result</code>:

```json
{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "tools": [
      {
        "name": "word_count",
        "description": "Count the words in a piece of text.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "text": { "type": "string", "description": "The text to count" }
          },
          "required": ["text"]
        }
      }
    ]
  }
}
```

It also prints a second view. The script combines the results of <code>tools/list</code>, <code>resources/list</code>, and <code>prompts/list</code> into this display; it is not one MCP response:

```json
{
  "tools": [
    {
      "name": "word_count",
      "description": "Count the words in a piece of text.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "text": { "type": "string", "description": "The text to count" }
        },
        "required": ["text"]
      }
    }
  ],
  "resources": [
    { "uri": "notes://today", "name": "notes", "description": "Today's short notes", "mimeType": "text/plain" }
  ],
  "prompts": [
    { "name": "summarize_notes", "description": "Summarize the notes in one line.", "arguments": [] }
  ]
}
```

The tool entry has the two required members plus a description, and the handler stays on the server. Treat this as a picture of the message shape, not as a test of any real client, SDK or model.

## Copy-paste prompt for your tool descriptions {#prompt}

If you run an MCP server, paste this into your AI coding assistant with your tool list:

```text
Rewrite each MCP tool description for a new teammate: what it does, when to use it, and what each input means.
```

Then check each result against the real behaviour of the tool. Cut anything the tool does not really do. If you package the same instructions for several agents, [one SKILL.md file](/how-to-create-an-ai-agent-skill/) is another place this text lives.

## Our take {#our-take}

The protocol asks for very little: a name and an input schema. The text that tells a model what a tool is for, the description and title, is optional, so it is on you as the server author to fill in the description, and on you as the client author to list again when tools change. If you are deciding whether you need MCP at all, [MCP vs API](/mcp-vs-api-when-ai-needs-mcp/) compares the two on one task.

This article summarizes the public Model Context Protocol specification, version 2025-06-18, as checked on 2026-11-16. The weather tool is a concept example, and the payload above comes from our own in-process simulation, not from the official SDK or any AI product.

## Frequently asked questions

**How does an AI agent discover MCP tools?**
After the connection is set up, the agent's MCP client sends a tools/list request. The server replies with a list of tool entries (name, inputSchema and optional fields such as description), and the host can pass them to the model.

**What fields does an MCP tool need?**
In the MCP schema 2025-06-18 a Tool has two required members, name and inputSchema. title, description, outputSchema, annotations and _meta are optional.

**How does an MCP client find out about a new tool?**
If the server declared the listChanged capability, it SHOULD send notifications/tools/list_changed when its tools change. The client can then send tools/list again to get the new list.

## Sources

- [MCP Specification 2025-06-18: Schema Reference, Tool](https://modelcontextprotocol.io/specification/2025-06-18/schema#tool)
- [MCP Specification 2025-06-18: Server Features, Tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools)
- [MCP Specification 2025-06-18: Server Features, Resources](https://modelcontextprotocol.io/specification/2025-06-18/server/resources)
- [MCP Specification 2025-06-18: Server Features, Prompts](https://modelcontextprotocol.io/specification/2025-06-18/server/prompts)
- [MCP Specification 2025-06-18: Architecture](https://modelcontextprotocol.io/specification/2025-06-18/architecture)
