[DOCS] Discrepancy between documentation and implementation for `TypedDict` support in SDK MCP Tools (Python)

Documentation Type

Missing documentation (feature not documented)

Documentation Location

• https://platform.claude.com/docs/en/agent-sdk/python#input-schema-options - https://github.com/anthropics/claude-agent-sdk-python/blob/main/src/claude_agent_sdk/__init__.py (Docstrings for @tool)

Section/Topic

The Input Schema Options section under the Python SDK Reference, specifically concerning how to define schemas for in-process MCP tools.

Current Documentation

The Python SDK Reference states:

Input Schema Options 1. Simple type mapping (recommended): {"text": str, "count": int, "enabled": bool} 2. JSON Schema format (for complex validation): {"type": "object", "properties": {...}}

Furthermore, the docstring for the @tool decorator in the source code (src/claude_agent_sdk/__init__.py) states:

input_schema: type | dict[str, Any] "Can be either: A dictionary mapping parameter names to types... A TypedDict class for more complex schemas... or a JSON Schema dictionary."

What's Wrong or Missing?

There is a critical logic flaw where the implementation does not match the documentation. While the documentation claims to support TypedDict and class-based types for schemas, the code in create_sdk_mcp_server (located in src/claude_agent_sdk/__init__.py) explicitly drops all property definitions if the input_schema is not a plain dictionary.

As seen in the source:

# src/claude_agent_sdk/__init__.py
else:
    # For TypedDict or other types, create basic schema
    schema = {"type": "object", "properties": {}}

If a developer follows the "recommended" path or uses a TypedDict as suggested by the docstring, the resulting tool definition sent to Claude has an empty properties object. Consequently, Claude receives no information about what arguments the tool requires, leading to execution failures or Claude being unable to use the tool.

Suggested Improvement

Until the implementation is updated to include a schema generator (using pydantic or inspect), the documentation should be corrected to reflect that only plain dictionaries are supported.

Suggested Text for the "Input Schema Options" section:

Note: Currently, only dictionary-based schema definitions are supported. Class-based types or TypedDict will result in an empty schema. Supported Format: ``python {"text": str, "count": int, "enabled": bool} ``

Additionally, the docstring in src/claude_agent_sdk/__init__.py should be updated to remove references to TypedDict support until the feature is implemented.

Impact

High - Prevents users from using a feature

Additional Context

• Related Documentation: Custom Tools Guide
• Technical Context: The current implementation in src/claude_agent_sdk/__init__.py (Line ~188) lacks the introspection logic necessary to turn a Python class into a JSON schema. Projects like the Anthropic Client SDK use @beta_tool to handle this via pydantic, but the Agent SDK is currently discarding this data.