modelcontextprotocol / modelcontextprotocol/python-sdk

Add `ClientSession.register_tool_schema()` for dynamic tool discovery patterns

Open Beginner friendly
#3,145 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement needs decision P3 v1 v2
Dominant language
Python
Stars
24.3k
Forks
4k
Avg merge
1d 1h
Merged PRs (30d)
31

Description

Description
Problem

ClientSession.validate_tool_result() validates tool results against cached output schemas in self._tool_output_schemas, which is populated exclusively by list_tools(). When a tool is invoked that wasn't returned by list_tools(), two things happen:

  1. A warning is logged: "Tool {name} not listed by server, cannot validate any structured content"
  2. If the tool returns structuredContent with an outputSchema, validation is skipped entirely — a correctness gap.

This affects MCP servers that use dynamic tool discovery, where list_tools() intentionally returns only a small subset of available tools (e.g., meta-tools like a search tool) and actual tools are discovered at runtime via semantic search or catalog queries.

Use case

AWS Bedrock AgentCore Gateway is an MCP-compatible server that can host hundreds or thousands of tools. Rather than returning all tools in list_tools() (which would overwhelm LLM context windows), it exposes a built-in tool called x_amz_bedrock_agentcore_search. Clients call this tool with a natural language query, and the gateway returns matching tool definitions — including names, descriptions, input schemas, and output schemas. The client then invokes these discovered tools by name via call_tool().

At that point, the SDK doesn't recognize these tools because they never appeared in a list_tools() response. This triggers the warning and skips output validation. The only workaround today is accessing the private _tool_output_schemas dict directly.

AWS Prescriptive Guidance documents this "search function" approach as one of three canonical tool discovery strategies for MCP (alongside static definition and dynamic discovery via list_tools()).

Proposed API

A single public method on ClientSession:

def register_tool_schema(
    self, name: str, output_schema: dict[str, Any] | None = None
) -> None:
    """Register a tool's output schema for result validation.

    Use this when tools are discovered dynamically (e.g., via a catalog
    search API) and won't appear in list_tools() responses.
    """
    self._tool_output_schemas[name] = output_schema

Usage:

# Client discovers tools via semantic search (not list_tools)
search_results = await session.call_tool("x_amz_bedrock_agentcore_search", {"query": "data analysis"})

# Register discovered tools for proper validation
for tool in parse_discovered_tools(search_results):
    session.register_tool_schema(tool.name, tool.output_schema)

# Now call_tool validates structuredContent correctly, no warning logged
result = await session.call_tool("data_analysis_v2", {"input": "..."})

This is purely additive — no changes to existing behavior, no new data structures. It writes to the same dict that _absorb_tool_listing() already populates.

References

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at ClientSession.validate_tool_result() and the existing _tool_output_schemas population in list_tools() and _absorb_tool_listing(). Add the public registration entry point described in the issue, then verify that a dynamically discovered tool can be registered and its structuredContent is validated without the missing-tool warning.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
api, backend
Issue type
Feature
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
72/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.