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

Beginne bei ClientSession.validate_tool_result() und der bestehenden Befüllung von _tool_output_schemas in list_tools() und _absorb_tool_listing(). Füge den im Issue beschriebenen öffentlichen Registrierungseinstiegspunkt hinzu und überprüfe anschließend, dass ein dynamisch entdecktes Tool registriert werden kann und sein structuredContent validiert wird, ohne eine Warnung wegen eines fehlenden Tools auszulösen.

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

• Search for tools in your AgentCore gateway with a natural language query — Official docs for the x_amz_bedrock_agentcore_search tool
• Tool discovery - AWS Prescriptive Guidance — Documents "search function" as a canonical MCP tool discovery strategy
• aws-samples/sample-aws-ops-agentcore-gateway-search — Working example with 268+ tools behind semantic search, reduced to 10-15 per query