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

Flashcard·Easy·4.0 · 0·~30s·Asked atCloudflare Lepton Ai Tata Digital·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.

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

Concept explanation~2 min read

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

tools/list is half of MCP's tool subsystem. It is the discovery call: the host asks the server 'what tools do you have,' the server replies with a catalog, and the host translates that catalog into whatever format the LLM expects so the model can choose from it. The other half, tools/call, handles invocation when the model picks one.

This explanation walks through the call itself, the response shape, the host workflow around it, and the traps that catch newcomers.

The call and its response shape

tools/list is a JSON-RPC request with method "tools/list" and typically no params. The server responds with {tools: [Tool, ...]} where each Tool is an object with three required fields.

name is a string that uniquely identifies the tool within the server. It is the value the client uses in subsequent tools/call requests. The server is responsible for ensuring uniqueness within itself; the host deals with cross server collisions on its own (typically by prefixing tool names with a server identifier).

description is a human readable string explaining what the tool does, when to use it, and what it returns. This is the most consequential field because it is the only documentation the LLM ever sees about the tool. The model uses the description to decide whether the tool is relevant to the current task. Vague or generic descriptions lead to wrong tool selection; clear, specific descriptions guide the model accurately.

inputSchema is a JSON Schema object describing the tool's arguments. It lists the properties, marks which are required, declares each property's type and any constraints (enums, formats, min/max), and ideally includes a per property description. The host uses this both to validate arguments before forwarding them and to feed the structured output mechanism of function calling.

Recent spec versions also allow an optional annotations object with hint flags: readOnlyHint (the tool does not modify state), destructiveHint (the tool can delete or overwrite), idempotentHint (calling twice gives the same result as once), openWorldHint (the tool reaches out to external systems). Hosts can use these to drive confirmation UI: a destructive tool gets an 'are you sure' prompt while a read only tool runs without confirmation.

When the host calls it and what follows

Dynamic tool sets and the listChanged sub flag

How tools/list and tools/call compose

Common pitfalls and what they reveal

Situations where this technique stops working.

2–4 min · Everything important, quickly.

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`.

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

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

If the server advertised tools.listChanged: true during initialize, it emits notifications/tools/list_changed when the list changes. The host refetches via tools/list and re injects the updated catalog into the next model inference. Without the sub flag, the host assumes the list is immutable for the session.

2 more follow-ups an interviewer would ask next. Sign in to reveal them.

Red flags & common mistakes

The phrases 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 bullets to scan on the way to the call.

Name the three fields in a tool definition: name, description, inputSchema
State when the host calls tools/list: once per session per server right after initialize

Primary sources. Browse if you want the original framing.