feat(api): document agent tool limits

[dpiet-oai]

Summary

clarify the 3 MiB tool limit for beta agents and sessions.

Changes

• Document that agent creation tools must fit within 3 MiB of compact UTF-8 JSON.
• Explain the tool replacement, clearing and session override semantics and their size limits.

[github-actions]

Castiron custom code

Evaluated main: a0dc1bcfcfe0a3834bc85346e3f2e78ec2e74385.

✅ No new custom-code files detected.

102 mixed files remain; 0 existing customizations changed.

Compared a0dc1bcfcfe0 → 72c24caf0285. Generated baselines verified.

102 existing customizations unchanged

• openai-java-core/src/main/kotlin/com/openai/models/audio/AudioResponseFormat.kt
• openai-java-core/src/main/kotlin/com/openai/models/beta/agents/vaults/credentials/CredentialAuth.kt
• openai-java-core/src/main/kotlin/com/openai/models/beta/agents/vaults/credentials/CredentialAuthCreateParam.kt
• openai-java-core/src/main/kotlin/com/openai/models/beta/agents/vaults/credentials/CredentialAuthRotateParam.kt
• openai-java-core/src/main/kotlin/com/openai/models/beta/responses/BetaResponse.kt
• openai-java-core/src/main/kotlin/com/openai/models/beta/responses/BetaResponseInjectEvent.kt
• openai-java-core/src/main/kotlin/com/openai/models/beta/responses/BetaResponseInjectFailedEvent.kt
• openai-java-core/src/main/kotlin/com/openai/models/beta/responses/BetaResponseStreamEvent.kt
• openai-java-core/src/main/kotlin/com/openai/models/beta/responses/BetaResponseToolSearchOutputItemParam.kt
• openai-java-core/src/main/kotlin/com/openai/models/beta/responses/BetaResponsesServerEvent.kt
• openai-java-core/src/main/kotlin/com/openai/models/chat/completions/ChatCompletionCreateParams.kt
• openai-java-core/src/main/kotlin/com/openai/models/chat/completions/ChatCompletionMessageFunctionToolCall.kt
• openai-java-core/src/main/kotlin/com/openai/models/chat/completions/ChatCompletionToolMessageParam.kt
• openai-java-core/src/main/kotlin/com/openai/models/conversations/ConversationCreateParams.kt
• openai-java-core/src/main/kotlin/com/openai/models/conversations/items/ItemCreateParams.kt
• openai-java-core/src/main/kotlin/com/openai/models/embeddings/Embedding.kt
• openai-java-core/src/main/kotlin/com/openai/models/embeddings/EmbeddingCreateParams.kt
• openai-java-core/src/main/kotlin/com/openai/models/live/ResponseItemCreateEvent.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/Response.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseCreateParams.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseFunctionToolCall.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseFunctionWebSearch.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseInputItem.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseStreamEvent.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseTextConfig.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseToolSearchOutputItemParam.kt
• openai-java-core/src/main/kotlin/com/openai/models/responses/ResponsesServerEvent.kt
• openai-java-core/src/main/kotlin/com/openai/models/videos/Video.kt
• openai-java-core/src/main/kotlin/com/openai/models/webhooks/UnwrapWebhookEvent.kt
• openai-java-core/src/main/kotlin/com/openai/models/webhooks/WebhookEndpointWithSecret.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/BetaServiceAsync.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/BetaServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/ImageServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/ResponseServiceAsync.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/ResponseServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/SkillServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/VideoServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/WebhookServiceAsync.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/WebhookServiceAsyncImpl.kt
• openai-java-core/src/main/kotlin/com/openai/services/async/audio/TranscriptionServiceAsyncImpl.kt

62 more in the full report.

A changed generated baseline means this report cannot reliably identify which handwritten lines changed.

Inspect the custom-code diff

Download the exact patch produced by this run (requires repository access):

gh run download 37666197024 --repo openai/openai-java \
  --name castiron-custom-code-37666197024-1 --dir /tmp/castiron-custom-code-37666197024-1
git apply --stat /tmp/castiron-custom-code-37666197024-1/custom-code.patch
cat /tmp/castiron-custom-code-37666197024-1/custom-code.patch

Or reproduce it from an SDK checkout containing the vendored reporter:

git fetch --no-tags origin a0dc1bcfcfe0a3834bc85346e3f2e78ec2e74385 72c24caf028549966ce325afc5e4681b204993ff
python3 scripts/castiron/custom_code_report.py report \
  --base a0dc1bcfcfe0a3834bc85346e3f2e78ec2e74385 \
  --head 72c24caf028549966ce325afc5e4681b204993ff --fetch --require-head-hash --public \
  --out /tmp/castiron-custom-code-72c24caf0285
cat /tmp/castiron-custom-code-72c24caf0285/custom-code.patch

This is the current full custom patch for mixed files, not an attribution of only the handwritten lines changed by this PR.

Full report and patch