[DOCS] Python SDK `@tool` decorator missing `allowed_callers` parameter for Programmatic Tool Calling

Documentation Type

Unclear/confusing documentation

Documentation Location

https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling

Section/Topic

Programmatic tool calling configuration / SDK Custom Tools definition

Current Documentation

The Programmatic tool calling documentation states that tools can be configured with an allowed_callers field:

{
  "name": "query_database",
  "description": "Execute a SQL query...",
  "input_schema": {...},
  "allowed_callers": ["code_execution_20250825"]
}

However, the Python SDK source code for the tool decorator in src/claude_agent_sdk/__init__.py has this signature:

def tool(
    name: str, description: str, input_schema: type | dict[str, Any]
) -> Callable[[Callable[[Any], Awaitable[dict[str, Any]]]], SdkMcpTool[Any]]:

What's Wrong or Missing?

The documentation claims that tools can be configured to allow programmatic calling via the allowed_callers field. However, the claude-agent-sdk implementation for defining custom tools (the @tool decorator and SdkMcpTool dataclass) does not accept or store this parameter.

As a result, users cannot define in-process SDK tools that support programmatic tool calling, despite the feature being advertised for the platform. The metadata required to enable this feature (allowed_callers) is dropped or impossible to set when using the SDK's helper functions.

Suggested Improvement

This is primarily a library feature gap that causes a documentation inconsistency.

Recommended Fix:
Update the tool decorator and SdkMcpTool class in the Python SDK to accept an optional allowed_callers list.

Code Update Example:

@dataclass
class SdkMcpTool(Generic[T]):
    name: str
    description: str
    input_schema: type[T] | dict[str, Any]
    handler: Callable[[T], Awaitable[dict[str, Any]]]
    allowed_callers: list[str] | None = None  # Add this field

def tool(
    name: str, 
    description: str, 
    input_schema: type | dict[str, Any],
    allowed_callers: list[str] | None = None  # Add parameter
) -> ...

If the feature cannot be implemented immediately, update the Custom Tools documentation to explicitly state that programmatic tool calling is not yet supported for SDK-hosted (in-process) tools.

Impact

High - Prevents users from using a feature

Additional Context

• SDK File Location: src/claude_agent_sdk/__init__.py
• Impact: Users following the Programmatic Tool Calling guide cannot implement it using the Agent SDK's custom tool functionality.