[DOCS] Confusing/ambiguous descriptions for `tools` vs `allowed_tools` parameters in Agent SDK reference

Documentation Type

Missing documentation (feature not documented)

Documentation Location

• https://docs.anthropic.com/en/docs/agent-sdk/python (ClaudeAgentOptions reference table) - https://docs.anthropic.com/en/docs/agent-sdk/typescript (Options reference table) - https://docs.anthropic.com/en/docs/agent-sdk/subagents (AgentDefinition table)

Section/Topic

Parameter description tables for ClaudeAgentOptions (Python) and Options (TypeScript), specifically the tools and allowed_tools/allowedTools parameters.

Current Documentation

Python SDK (ClaudeAgentOptions)

| Property | Description |
|----------|-------------|
| tools | Tools configuration. Use {"type": "preset", "preset": "claude_code"} for Claude Code's default tools |
| allowed_tools | List of allowed tool names |

TypeScript SDK (Options)

| Property | Description |
|----------|-------------|
| tools | Tool configuration. Pass an array of tool names or use the preset to get Claude Code's default tools |
| allowedTools | List of allowed tool names |

AgentDefinition (both SDKs)

| Property | Description |
|----------|-------------|
| tools | Array of allowed tool names. If omitted, inherits all tools |

What's Wrong or Missing?

The descriptions for tools and allowed_tools are confusingly similar and fail to communicate their critical semantic difference:

1. tools restricts which tools are available to the agent. The agent cannot use tools not in this list.

1. allowed_tools bypasses permission prompts for the listed tools. These tools execute without user confirmation.

The current descriptions ("Tools configuration" vs "List of allowed tool names") don't convey this distinction. The problem is compounded by the AgentDefinition table using the phrase "allowed tool names" for tools, which matches the description of allowed_tools.

Security Concern

A developer might write:

options=ClaudeAgentOptions(allowed_tools=["Bash", "Edit"])

Believing this restricts the agent to only Bash and Edit. In reality:

• All tools remain available (since tools defaults to all)
• Bash and Edit now auto-execute without permission prompts

This is the opposite of the intended behavior and could grant unintended autonomous system access.

Evidence from CLI Documentation

The CLI documentation (cli-reference.md) is clear about the distinction:

--allowedTools - Tools that execute without prompting for permission. To restrict which tools are available, use --tools instead. --tools - Restrict which built-in tools Claude can use.

The SDK documentation should match this clarity.

Suggested Improvement

Python SDK (ClaudeAgentOptions)

| Property | Description |
|----------|-------------|
| tools | Restricts the agent to ONLY these specific tools. Pass a list of tool names to limit availability, or use {"type": "preset", "preset": "claude_code"} for Claude Code's default tools. Default: All tools available. |
| allowed_tools | Bypasses permission prompts for these tools. Listed tools execute automatically without user confirmation. Security warning: Only list tools you trust to run unattended. |
| disallowed_tools | Blocks these tools entirely. The agent cannot use listed tools even if they appear in tools. |

TypeScript SDK (Options)

| Property | Description |
|----------|-------------|
| tools | Restricts the agent to ONLY these specific tools. Pass an array of tool names to limit availability, or use the preset to get Claude Code's default tools. Default: All tools available. |
| allowedTools | Bypasses permission prompts for these tools. Listed tools execute automatically without user confirmation. Security warning: Only list tools you trust to run unattended. |
| disallowedTools | Blocks these tools entirely. The agent cannot use listed tools even if they appear in tools. |

AgentDefinition (both SDKs)

Change from:

tools - Array of allowed tool names. If omitted, inherits all tools

To:

tools - Restricts the subagent to ONLY these specific tools. If omitted, inherits all tools from the parent agent.

Additional Suggestions

1. Add a "Permissions vs Availability" callout box near the parameter tables explaining the difference
2. Include a code example showing the interaction between tools (restriction) and allowed_tools (auto-approval)
3. Consider renaming the CLI flag from --allowedTools to something like --autoApproveTools to eliminate ambiguity (breaking change, but would prevent future confusion)

Impact

High - Prevents users from using a feature correctly and may cause security issues

Users attempting to restrict agent capabilities may inadvertently grant unrestricted autonomous access to sensitive tools. The naming collision between "tools configuration" and "allowed tool names" actively misleads developers about the security model.

Impact

High - Prevents users from using a feature

Additional Context

Files affected in documentation mirror

• platform-claude/docs/en/agent-sdk/python.md (lines 492-493, 683)
• platform-claude/docs/en/agent-sdk/typescript.md (lines 100, 132, 182)
• platform-claude/docs/en/agent-sdk/subagents.md (lines 77, 125, 156)
• platform-claude/docs/en/agent-sdk/overview.md (all examples only use allowed_tools)

Positive example (CLI docs are clear)

From code-claude/docs/en/cli-reference.md:

| Flag | Description |
|------|-------------|
| --allowedTools | Tools that execute without prompting for permission. See permission rule syntax for pattern matching. To restrict which tools are available, use --tools instead. |
| --tools | Restrict which built-in tools Claude can use. Use "" to disable all, "default" for all, or tool names like "Bash,Edit,Read" |

This explicit cross-reference and use of the word "restrict" makes the distinction clear.

Related documentation

• Permissions guide: https://docs.anthropic.com/en/docs/agent-sdk/permissions
• CLI reference: https://docs.claude.com/en/cli-reference