---
type: email
from: Muhammad Suhaib <notifications@github.com>
subject: [openai/openai-agents-python] docs: clarify ModelSettings.tool_choice

 options (PR #1572)
received: 2026-03-06 07:12:37
date_header: Sat, 23 Aug 2025 09:30:02 -0700
priority: normal
status: awaiting_approval
uid: 28489
---

## Email Content

**From:** Muhammad Suhaib <notifications@github.com>
**Subject:** [openai/openai-agents-python] docs: clarify ModelSettings.tool_choice

 options (PR #1572)
**Date:** Sat, 23 Aug 2025 09:30:02 -0700

### Body (preview)

- Expanded the docstring for `ModelSettings.tool_choice`.

- Documented all valid values supported by the `ToolChoice` type alias:

  * &quot;auto&quot; (default) → let the model decide.

  * &quot;required&quot; → must call some tool.

  * &quot;none&quot; → forbid tool calls.

  * &quot;&lt;tool_name&gt;&quot; → force a specific tool by name.

  * MCPToolChoice → advanced structured config.

  * None → provider defaults.

- Aligns SDK docs with the actual `ToolChoice` type definition.



You can view, comment on, or merge this pull request online at:



  https://github.com/openai/openai-agents-python/pull/1572



-- Commit Summary --



  * docs: clarify ToolsToFinalOutputResult docstrings

  * docs: clarify ModelSettings.truncation behavior

  * docs: clarify ModelSettings.tool_choice options



-- File Changes --



    A git (0)

    M src/agents/agent.py (9)

    M src/agents/model_settings.py (21)



-- Patch Links --



https://github.com/openai/openai-agents-python/pull/1572.patch

https://github.com/openai/openai-agents-python/pull/1572.diff



-- 

Reply to this email directly or view it on GitHub:

https://github.com/openai/openai-agents-python/pull/1572

You are receiving this because you are subscribed to this thread.



Message ID: &lt;openai/openai-agents-python/pull/1572@github.com&gt;

---

## Suggested Actions
- [ ] Reply
- [ ] Archive
- [ ] Escalate
