Add toolChoice parameter to agent definitions
Problem
Custom agents defined in .claude/agents/*.md cannot control the tool_choice API parameter. This causes a common problem: agents output text before invoking tools, even when explicitly instructed not to.
Current Behavior
Agent definitions support:
---
name: my-agent
tools: Task, AskUserQuestion
model: opus
---
But there's no way to set tool_choice. Even with explicit instructions like:
<MANDATORY>
YOUR FIRST OUTPUT MUST BE A TOOL CALL. NOT TEXT.
</MANDATORY>
The model still frequently outputs text before tool calls, especially for orchestrator agents that should always delegate.
Proposed Solution
Add a toolChoice field to agent frontmatter:
---
name: team-leader
tools: Task, AskUserQuestion
toolChoice: any # Forces tool use, no text before tools
model: opus
---
Supported values (matching the API):
auto(default) - Model decidesany- Must use a tool, no text before tool blockstool:ToolName- Must use specific tool
Use Case
Orchestrator/delegation agents that should:
- Receive a question
- Immediately invoke Task tool to delegate
- Return results
These agents should never output text before delegating. toolChoice: any would enforce this at the API level instead of relying on prompt instructions that the model ignores.
References
From the Claude API docs:
When usingtool_choice: {"type": "any"}, Claude will prefill the assistant message to force a tool to be used. This means the models will not emit a natural language response or explanation beforetool_usecontent blocks.
This is exactly what orchestrator agents need.
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗