---
type: email
from: Engineer Abdullah Iqbal <notifications@github.com>
subject: [openai/openai-agents-python] Improved docstrings for model settings

 parameters to provide clearer explanations (PR #1958)
received: 2026-03-06 08:11:08
date_header: Tue, 21 Oct 2025 00:08:33 -0700
priority: normal
status: awaiting_approval
uid: 33236
---

## Email Content

**From:** Engineer Abdullah Iqbal <notifications@github.com>
**Subject:** [openai/openai-agents-python] Improved docstrings for model settings

 parameters to provide clearer explanations (PR #1958)
**Date:** Tue, 21 Oct 2025 00:08:33 -0700

### Body (preview)

Improved docstrings for model settings parameters to provide clearer explanations of their behavior and valid ranges.



## Changes

- Enhanced `temperature` docstring with range and behavior details

- Enhanced `top_p` docstring with nucleus sampling explanation

- Enhanced `frequency_penalty` docstring with use case

- Enhanced `presence_penalty` docstring with distinction from frequency_penalty

- Enhanced `tool_choice` docstring with available options



## Why this need

The current docstrings merely repeat the parameter names without explaining what they do or how they affect model behavior, which can confuse developers.

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



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



-- Commit Summary --



  * Agent name validation

  * Error Message Updated

  * Merge branch &#39;openai:main&#39; into main

  * Updated Routing with session

  * file name corrected

  * routing with session

  * Merge branch &#39;main&#39; of https://github.com/EngineerAbdullahIqbal/openai-agents-python

  * Settings Definations Update

  * Merge branch &#39;main&#39; of https://github.com/openai/openai-agents-python

  * Merge branch &#39;main&#39; of https://github.com/EngineerAbdullahIqbal/openai-agents-python



-- File Changes --



    A docs/routing_with_session.md (130)

    D examples/agent_patterns/routing.py (70)

    A examples/agent_patterns/routing_with_session.py (91)

    M src/agents/model_settings.py (28)



-- Patch Links --



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

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



-- 

Reply to this email directly or view it on GitHub:

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

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



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

---

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