[DOCS] Python SDK Syntax and Type Inconsistencies (Case Sensitivity and Function Signatures)

Documentation Type

Unclear/confusing documentation

Documentation Location

• docs/en/agent-sdk/python.md - docs/en/agent-sdk/mcp.md - docs/en/agent-sdk/overview.md

Section/Topic

• Python ClaudeAgentOptions usage examples. - can_use_tool / custom_permission_handler callback signature definitions.

Current Documentation

In docs/en/agent-sdk/python.md, the ClaudeAgentOptions dataclass is correctly defined using Python's snake_case convention:

@dataclass
class ClaudeAgentOptions:
    allowed_tools: list[str] = field(default_factory=list)
    mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict)
    # ...

However, in docs/en/agent-sdk/mcp.md, the Python code block uses TypeScript-style camelCase:

async for message in query(
    prompt="List files in my project",
    options={
        "mcpServers": {...},
        "allowedTools": ["mcp__filesystem__list_files"]
    }
):

Additionally, regarding the permission callback, python.md provides two different signatures:
Example 1 (Classes section):
async def custom_permission_handler(tool_name: str, input_data: dict, context: dict)

Example 2 (Sandbox Configuration section):
async def can_use_tool(tool: str, input: dict)

What's Wrong or Missing?

1. Case Sensitivity: Python is case-sensitive. The ClaudeAgentOptions dataclass (and the underlying logic) expects allowed_tools and mcp_servers. Providing allowedTools or mcpServers in a dictionary passed to the SDK will result in a TypeError or the options being ignored entirely. It appears TypeScript code snippets were copy-pasted into Python documentation without being adapted to the Python SDK's naming schema.
2. Signature Mismatch: The documentation is inconsistent regarding whether the permission callback (can_use_tool) requires two or three arguments. Example 1 includes a context dictionary, while Example 2 omits it. This will lead to TypeError: can_use_tool() missing 1 required positional argument or TypeError: can_use_tool() takes 2 positional arguments but 3 were given depending on the actual SDK implementation.

Suggested Improvement

1. Audit Case Conventions: Ensure all code snippets labeled "Python" use snake_case for parameters (allowed_tools, mcp_servers, permission_mode, max_turns, etc.) to match the ClaudeAgentOptions definition.
2. Standardize Callback Signatures: Clearly define the expected signature for the can_use_tool callback in the type reference and ensure every example in overview.md, python.md, and permissions.md follows that exact signature.
3. Correction for mcp.md: Update the Python example to:

options=ClaudeAgentOptions(
    mcp_servers={"filesystem": {...}},
    allowed_tools=["mcp__filesystem__list_files"]
)

Impact

High - Prevents users from using a feature

Additional Context

• Links to related documentation:
• Python SDK Reference
• MCP Integration Guide
• This inconsistency likely stems from the recent rename/migration from the "Claude Code SDK" to the "Claude Agent SDK" (v0.1.0), where configuration types were updated but example snippets across the broader documentation set were not fully synchronized.