What it does
The `tools/list` request is sent by the client to the server to retrieve the full catalog of tools the server currently exposes. Before sending this request, the client must have completed the `initialize` handshake and confirmed that the server's `capabilities.tools` object is present in the `InitializeResult`; if that capability is absent, sending `tools/list` is a protocol error and the server is expected to return a JSON-RPC error response rather than a tool array. The request body carries an optional `cursor` string for pagination — omitting it fetches the first page. The server responds with a `result` object containing a `tools` array, where each entry is a full `Tool` definition including `name`, `description`, and an `inputSchema` (a JSON Schema object describing accepted parameters). If the server's tool catalog spans multiple pages, the response also includes a `nextCursor` opaque string; the client repeats the request with `cursor` set to that value until `nextCursor` is absent, signalling the final page. Servers are not required to implement pagination and may return all tools in a single response. Clients should re-issue `tools/list` (resetting pagination from the beginning) whenever they receive a `notifications/tools/list_changed` notification, because the server's tool set may have grown, shrunk, or had schemas updated. Caching the previous result and replaying it after a `list_changed` event is a common source of stale-tool bugs. Clients that miss this notification — for example due to a reconnect — should treat a reconnected session as a fresh `initialize` flow and re-enumerate all capabilities.
When to use
After initialize, and after list_changed notifications.
When NOT to use
Repeatedly without cause — listen for list_changed instead.
Notes
Capability gate is mandatory
A client must only call `tools/list` when the `InitializeResult.capabilities.tools` field is present. Calling it on a server that did not advertise tool support is undefined behavior; well-behaved servers return a JSON-RPC `-32601 Method not found` error. Always check capabilities before enumerating.
Pagination with opaque cursors
Cursors are server-defined opaque strings — do not parse, store persistently, or assume they are stable across server restarts. Page through by passing the previous response's `nextCursor` as the next request's `cursor` parameter until `nextCursor` is absent. There is no guaranteed page size; servers may return any number of tools per page.
Re-enumerate on list_changed notification
When the server sends `notifications/tools/list_changed`, the client must restart pagination from `cursor: undefined` to get a consistent snapshot. Partial re-reads (continuing from a saved cursor) risk mixing tool definitions from two different generations and can cause schema-mismatch errors when tools are later called.
Race between list_changed and call
A tool may disappear between a `tools/list` response and a subsequent `tools/call`. Servers signal this with a `-32601` or a domain-specific `ToolNotFound` error on the call. Clients should handle this gracefully by refreshing the tool list and surfacing a user-friendly message rather than treating it as a fatal protocol error.
SDK caching behavior varies
The TypeScript MCP SDK's high-level client caches the tool list in memory and invalidates it automatically on `list_changed`. The Python SDK (as of 1.x) does not cache by default — callers must manage their own cache or call `list_tools()` on demand. Relying on implicit caching without verifying SDK version can introduce subtle consistency bugs in long-running client processes.
Request parameters
| Name | Type | Purpose |
|---|---|---|
| cursor | string? | Opaque pagination token from a prior call. |
Response fields
| Name | Type | Purpose |
|---|---|---|
| tools | Tool[] | Available tools. |
| nextCursor | string? | Pagination cursor for the next page. |
Examples
Listing tools
{ "method": "tools/list" }Common mistakes
❌ Caching forever without subscribing to list_changed
✅ Refresh on notifications/tools/list_changed.