π 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.mdxindex 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.```pythonasync with client:- fresh = await client.list_tools_mcp(cache_mode="refresh")+ fresh = await client.list_tools(cache_mode="refresh")```### Sharing a cache across clientsdiff --git a/docs/clients/tools.mdx b/docs/clients/tools.mdxindex 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 Executiondiff --git a/justfile b/justfileindex 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 projectbuild: