anthropics / anthropics/claude-agent-sdk-python

Feature request: expose tool_choice parameter in ClaudeAgentOptions

Open
#655 0 comments 4 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
8.1k
Forks
1.3k
Avg merge
2d 31m
Merged PRs (30d)
1

Description

## Summary

The Anthropic Messages API supports a `tool_choice` parameter (`auto`, `any`, `none`, or force a specific tool by name), but the Agent SDK does not expose it in `ClaudeAgentOptions`.

## Use case

When building autonomous agent pipelines, some workflows require an agent to **always** call a specific tool before finishing — e.g., a research agent that must persist its findings via a `save_research_report` MCP tool.

Currently, the only controls available are `allowed_tools` and `disallowed_tools`, which filter tool availability but don't **force** a tool call. The agent can still choose to respond with plain text instead of calling the required tool, which is non-deterministic and leads to lost work.

### What happens today

```python
result = await query(
prompt="Research topic X and save findings",
options=ClaudeAgentOptions(
allowed_tools=["WebSearch", "WebFetch", "save_research_report"],
# No way to force save_research_report to be called
)
)
# Sometimes the agent calls save_research_report ✅
# Sometimes it just responds with text ❌ — findings are lost
```

### What we'd like

```python
result = await query(
prompt="Research topic X and save findings",
options=ClaudeAgentOptions(
allowed_tools=["WebSearch", "WebFetch", "save_research_report"],
tool_choice={"type": "tool", "name": "save_research_report"},
# Or: tool_choice="any" to require at least one tool call
)
)
```

## Workarounds tried

- **Prompt reinforcement** ("you MUST call this tool") — improves reliability but not deterministic
- **Post-processing validation + retry** — works but wastes tokens/budget
- **Fallback extraction** from raw response — lossy, degrades quality

## Notes

- The Messages API already supports this: `tool_choice: auto | any | none | {type: "tool", name: "X"}`
- Known constraint: forced tool use (`any`/`tool`) is incompatible with extended thinking — this should be documented if exposed
- Even partial support (e.g., `tool_choice="any"`) would be valuable for mandatory-persistence workflows

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.