Add toolChoice parameter to agent definitions

Resolved 💬 3 comments Opened Jan 22, 2026 by sisitrs2 Closed Jan 26, 2026

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 decides
  • any - Must use a tool, no text before tool blocks
  • tool:ToolName - Must use specific tool

Use Case

Orchestrator/delegation agents that should:

  1. Receive a question
  2. Immediately invoke Task tool to delegate
  3. 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 using tool_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 before tool_use content blocks.

This is exactly what orchestrator agents need.

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗