Walk me through what tools/list returns and when the host calls it.

Flashcard·Easy·4.0 · 0·~30s·Relevant atAnthropic

Attempt it

tools/list is the JSON-RPC method the client calls right after the initialize handshake to discover every tool a server exposes. The response is an array of tool definitions, each with a name, a description, and an inputSchema (JSON Schema). The host calls it once per session per server, caches the result, translates the definitions into the LLM provider's tool format, and injects them into every inference request. When the model picks a tool, tools/call carries the actual invocation. If the server advertised tools.listChanged, it can push a refetch notification mid session.

Your answer

**`tools/list`** is the MCP method the host uses to discover what tools a server offers. The client sends a JSON-RPC request with method `tools/list` and typically no params. The server responds with a `result.tools` array where each entry is a tool definition. Each tool definition has three fields. `name` is a unique identifier the host uses when invoking the tool. `description` is human readable text explaining what the tool does; this text gets presented to the LLM so it knows when to pick the tool. `inputSchema` is a JSON Schema object describing the tool's arguments: which fields exist, which are required, and what types they accept. The host calls `tools/list` once per session per server, right after the `initialize` handshake completes. It then translates the MCP tool definitions into whatever format the LLM provider expects (OpenAI tools array, Anthropic tools parameter, Gemini function_declarations) and includes them on every inference request to the model. When the model decides to use a tool, it emits a structured tool call via function calling. The host receives that call, finds which MCP server owns the tool, and sends a `tools/call` JSON-RPC request to that server with the model's arguments. `tools/list` is discovery; `tools/call` is invocation. Two methods, two jobs.

**`tools/list`** is the JSON-RPC method MCP clients use to discover the tools a server exposes. The host calls it immediately after the `initialize` handshake completes (specifically after sending `notifications/initialized`), and the server responds with an array of tool definitions. The response shape is `{tools: [{name, description, inputSchema}, ...]}`. `name` is the unique identifier used in `tools/call` requests. `description` is human readable text the model reads to decide when to invoke the tool. `inputSchema` is a JSON Schema object describing the tool's arguments, including which properties exist, which are required, what types they accept, and any enum constraints or per property descriptions. The host workflow is straightforward. Once it has tool lists from each connected MCP server, it translates each tool definition into the LLM provider's expected tool format. For Anthropic, this means building entries in the `tools` parameter with name, description, and input_schema. For OpenAI, it means building the `tools` array with type `function` and an embedded function definition. For Gemini, it means filling `function_declarations`. The translated catalog gets included on every inference request so the model always knows the available tools. Caching is the expected behavior. The host calls `tools/list` once per session per server and stores the result. If the server advertised the `tools.listChanged` capability during initialize, it can later emit `notifications/tools/list_changed` and the host refetches. Otherwise the list is assumed static for the session. The complementary method is `tools/call`, which carries the actual invocation: the host sends a JSON-RPC request with method `tools/call` and params `{name, arguments}`, and the server executes the tool and returns a content array as the result.

Quick reference

TL;DR

`tools/list` is the discovery call run once per session per server after initialize. It returns an array of tool definitions (name, description, inputSchema). `tools/call` handles the actual invocation.

Memory aid

Easy to grasp

Imagine walking into a workshop for the first time. Before you can use any tools, you need to know what the workshop has. So you ask the foreman 'show me the toolbox.' The foreman hands you a list: 'here is a hammer, here is a screwdriver, here is a saw, and here is what each one does and what it needs.' That list is what `tools/list` returns in MCP. The host asks the server 'what tools do you have' and the server replies with a catalog. Later, when the model decides to use a tool, the host says 'use the hammer with this nail' and that is `tools/call`. Discover first, then call.

Key concepts

tools/list tools/call Input Schema Tool Discovery

Detailed answer & concept explanation

~7 min read

Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.

Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example.

Quick scan · 2–4 min

Everything important, quickly.

4 min: name the three fields in a tool definition, walk the host workflow from initialize through cached `tools/list` to translation into the provider's schema, distinguish from `tools/call`, and close with the dynamic list refresh mechanism.

Real-world examples

Real products, models, and research that use this idea.

Claude Desktop calls `tools/list` against each configured MCP server at session start, merges the results with server prefixed names, and injects them into Anthropic's tools parameter for every Claude inference request.
Cursor and VS Code Copilot Agents follow the same pattern: discover tools at startup, translate to the underlying LLM's tool schema, and refresh on `notifications/tools/list_changed`.
The MCP Inspector lets you call `tools/list` against any server interactively, showing the full tool array including descriptions and JSON Schema, which is the standard sanity check when authoring a new server.
Official MCP servers (filesystem, sqlite, git, brave-search) all implement `tools/list` and return small, well documented tool catalogs that demonstrate good description style.

Interviewer follow-ups

What an interviewer would ask next. Try answering before peeking at the approach.

QWhat happens if the server's tool list changes mid session?

QHow does the host translate MCP tool definitions into the LLM provider's tool schema?

QWhat can a server include beyond name, description, and inputSchema in a tool definition?

Don't say this

Red flags and common mistakes that signal junior thinking. Click to expand.

Most common mistake

Calling `tools/list` on every model turn. The host should call it once per session per server and cache the result. The server pushes `notifications/tools/list_changed` if the catalog ever changes mid session.

60-second cheat sheet

The night-before-the-interview bullets. Scan these on the way to the call.

References

Primary sources. Skim if you want the original framing.