Sitelet https://github.com/openai/openai-agents-python/pull/4951
Skip to content

fix(core): preserve Field descriptions on variadic tool parameters - #4951

Closed
subhashpolisetti wants to merge 1 commit into
openai:mainfrom
subhashpolisetti:fix/variadic-field-descriptions
Closed

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

Conversation

@subhashpolisetti

Copy link
Copy Markdown
Contributor

Summary

This pull request fixes lost Pydantic Field descriptions on variadic tool parameters.

*scores: Annotated[int, Field(description="Exam scores", ge=0, le=100)] advertises the constraints on each collected value but drops the description, so the model is shown an undocumented array argument. The same applies to values collected through **kwargs. Descriptions already reach variadic parameters through docstrings (#3956) and through an annotated string, leaving Field(description=...) as the one documented spelling that still loses them.

A Field() inside Annotated splits into attributes such as description and constraints collected as metadata. #4739 routed the metadata half to each collected value; this carries the description half to the parameter the schema advertises. It applies only when neither a docstring nor an annotated string supplies a description, so the existing precedence is unchanged, and reading only the description keeps the container's default_factory and the value-level constraint placement #4739 established. Extending the shared _extract_description_from_metadata helper would be broader than the need: it feeds every parameter kind and would also reorder precedence between a Field(description=...) and a sibling string for ordinary parameters.

Test plan

  • test_variadic_field_description_in_schema covers *args and **kwargs under strict and non-strict schemas, asserting the description lands on the parameter while the constraints from the same Field(...) stay on each collected value. Both cases fail on main with KeyError: 'description'.
  • Two precedence tests pin that a docstring and an annotated string still take priority.
  • make format, make lint, make typecheck and uv run mypy --platform win32 src are clean.
  • .agents/skills/code-change-verification/scripts/run.sh does not complete in my environment: 14 tests in tests/test_code_change_verification_runner.py fail with Timed out waiting for a controlled process transition. They reproduce identically on unmodified main here and are unrelated to this change. Excluding that file, the suite reports 9673 passed, 32 skipped.

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

A Field() inside Annotated splits into attributes such as description and
constraints stored as metadata. Variadic parameters routed the constraints to
each collected value but dropped the description, so the advertised tool schema
omitted it while the constraints from the same Field() were applied.

Fall back to the annotated Field description when no docstring or annotated
string supplies one, matching the ordinary-parameter behavior.
@seratch

seratch commented Sep 11, 2026

Copy link
Copy Markdown
Member

Thanks for the contribution. The loss of Field(description=...) on variadic parameters is real, and the fallback is narrowly scoped.

However, the released SDK already supports the same description and constraints through Annotated[int, "Exam scores", Field(ge=0, le=100)], or through a parameter docstring. The PR does not establish a concrete application constraint that makes those supported paths insufficient. The broad documentation wording could also be clarified to explain the existing behavior.

I am going to close this PR for now. We can reconsider if there is a concrete integration that must reuse existing Field metadata and cannot reasonably supply the description through the supported paths.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants