Skip to content

docs: clarify Field description handling for variadic tool parameters - #4954

Draft
subhashpolisetti wants to merge 1 commit into
openai:mainfrom
subhashpolisetti:docs/variadic-field-descriptions
Draft

docs: clarify Field description handling for variadic tool parameters#4954
subhashpolisetti wants to merge 1 commit into
openai:mainfrom
subhashpolisetti:docs/variadic-field-descriptions

Conversation

@subhashpolisetti

Copy link
Copy Markdown
Contributor

Summary

This pull request clarifies how a Pydantic Field description is handled for variadic tool parameters.

The section is titled "Constraining and describing arguments with Pydantic Field" and states that Field adds constraints and descriptions to tool arguments. The variadic paragraph then mentions only constraints, so the wording reads as though Field(description=...) also reaches a variadic parameter. It does not: on v0.22.2, *scores: Annotated[int, Field(description="Exam scores", ge=0, le=100)] advertises the constraints on each collected value and no parameter description.

The added sentence states that the SDK ignores a description passed to Field(...) on a variadic parameter and names the two supported ways that description is taken, following the guidance given when #4951 was closed.

Test plan

  • Verified on v0.22.2 that *scores: Annotated[int, "Exam scores", Field(ge=0, le=100)] and a docstring entry alongside Field(ge=0, le=100) each produce the parameter description together with the per-value constraints, and that Field(description=...) alone produces no description.
  • make build-docs completes with no errors and no new warnings. Generated pages under docs/ja, docs/ko, and docs/zh are untouched.
  • This is a docs-only change, so the SDK verification stack does not apply; make build-docs is the applicable check.

Checks

  • I've added new tests, if relevant
  • I've run .agents/skills/code-change-verification/scripts/run.sh
  • I've confirmed all verification steps pass
  • If using Codex, I've run /review before submitting this PR

The section covers constraining and describing arguments with Field, and the
variadic paragraph mentions only constraints, so the wording reads as though a
Field description also reaches a variadic parameter.

State that the SDK does not read Field(description=...) for a variadic
parameter and name the two supported ways to supply that description.
@seratch seratch added the documentation Improvements or additions to documentation label Sep 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants