Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

docs: cover list_tools and restore client modules in the SDK reference (#4936)

nate nowack6182642b7ee6
diff --git a/docs/clients/client.mdx b/docs/clients/client.mdx
index 9861ca75d..a1b831d7e 100644
--- a/docs/clients/client.mdx
+++ b/docs/clients/client.mdx
@@ -247,11 +247,11 @@ config = CacheConfig(target_id="weather-api", default_ttl_ms=60_000)
client = Client("https://example.com/mcp", mode="auto", cache=config)
```
-The high-level `list_tools`, `list_resources`, and `list_prompts` methods always use the cache when one is configured. To override the behavior for a single call, use the lower-level `list_tools_mcp`, `list_resources_mcp`, `list_resource_templates_mcp`, and `list_prompts_mcp` variants, which accept a `cache_mode` argument: `"use"` (the default) serves and stores, `"refresh"` stores a fresh result without serving a cached one, and `"bypass"` skips the cache entirely.
+The listing methods use the cache by default when one is configured. To override the behavior for a single call, pass `cache_mode`: `"use"` (the default) serves and stores, `"refresh"` stores a fresh result without serving a cached one, and `"bypass"` skips the cache entirely. `list_tools` accepts it directly; the lower-level `list_tools_mcp`, `list_resources_mcp`, `list_resource_templates_mcp`, and `list_prompts_mcp` variants accept it as well.
```python
async with client:
- fresh = await client.list_tools_mcp(cache_mode="refresh")
+ fresh = await client.list_tools(cache_mode="refresh")
```
### Sharing a cache across clients
diff --git a/docs/clients/tools.mdx b/docs/clients/tools.mdx
index 77389296e..7dfa49919 100644
--- a/docs/clients/tools.mdx
+++ b/docs/clients/tools.mdx
@@ -11,7 +11,32 @@ import { VersionBadge } from '/snippets/version-badge.mdx'
Use this when you need to execute server-side functions and process their results.
-Tools are executable functions exposed by MCP servers. The client's `call_tool()` method executes a tool by name with arguments and returns structured results.
+Tools are executable functions exposed by MCP servers. The client's `list_tools()` method discovers what a server offers, and `call_tool()` executes a tool by name with arguments and returns structured results.
+
+## Discovering Tools
+
+`list_tools()` returns every tool the server advertises as a list of `mcp_types.Tool` objects, each carrying the tool's name, description, and JSON `input_schema`. It follows pagination automatically, so the result is the complete catalog.
+
+```python
+async with client:
+ tools = await client.list_tools()
+ for tool in tools:
+ print(tool.name, tool.description)
+ print(tool.input_schema)
+```
+
+Servers can change their catalog while the connection is open and notify the client with a `notifications/tools/list_changed` notification; a fresh `list_tools()` call reflects the new set. See [Notifications](/clients/notifications) for reacting to that notification.
+
+For page-by-page control over large catalogs, `list_tools_mcp()` returns one raw `ListToolsResult` at a time and accepts the `cursor` from the previous page's `next_cursor`.
+
+```python
+async with client:
+ page = await client.list_tools_mcp()
+ while page.next_cursor:
+ page = await client.list_tools_mcp(cursor=page.next_cursor)
+```
+
+Both methods accept a `cache_mode` argument when the client was built with a [response cache](/clients/client#response-caching).
## Basic Execution
diff --git a/justfile b/justfile
index 2876e6f33..eb11e2df2 100644
--- a/justfile
+++ b/justfile
@@ -1,4 +1,4 @@
-api_ref_package := "fastmcp-slim[anthropic,apps,azure,code-mode,full,gemini,openai,tasks] @ file://" + justfile_directory() + "/fastmcp_slim"
+api_ref_package := "fastmcp-slim[anthropic,apps,azure,client,code-mode,gemini,openai,server] @ file://" + justfile_directory() + "/fastmcp_slim"
# Build the project
build: