Skip to content

shrink builtin tool schemas to save tokens#2694

Merged
dgageot merged 3 commits intodocker:mainfrom
dgageot:board/2844308683322e21
May 7, 2026
Merged

shrink builtin tool schemas to save tokens#2694
dgageot merged 3 commits intodocker:mainfrom
dgageot:board/2844308683322e21

Conversation

@dgageot
Copy link
Copy Markdown
Member

@dgageot dgageot commented May 7, 2026

Reduces the size of builtin tool definitions sent to LLM providers on
every turn. Most of the savings come from the filesystem and shell
toolsets, which together represented ~1.2k tokens per request.

Changes:

  • SchemaToMap now strips "null" from the type of required fields.
    jsonschema-go emits ["null", "array"] for every Go slice (including
    required ones), which is contradictory and only inflates the schema.
    OpenAI's strict mode still adds null for fields it promotes from
    optional to required, so behaviour is preserved there.
  • Shortened the description text added by AddDescriptionParameter.
  • Trimmed verbose jsonschema:"..." tags on filesystem and shell tool
    arg structs.
  • Drive-by: switched a few slog.Warn calls to slog.WarnContext in
    spots where a context was already in scope (custom linter caught it).

Cassettes were updated to match the new request bodies. No behaviour
change for callers.

@dgageot dgageot requested a review from a team as a code owner May 7, 2026 13:06
Copy link
Copy Markdown

@docker-agent docker-agent left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Assessment: 🟢 APPROVE

Reviewed the schema null-stripping logic, description trimming, struct tag removals, and slog.WarnContext drive-by changes.

Key areas checked:

  • SchemaToMap / removeNullFromType: The filtered := arr[:0] in-place filter pattern is provably safe — Go's range captures the slice header at loop start, so reads always precede writes on the same backing-array positions. No correctness bug.
  • stripNullFromRequiredTypes recursion: Correctly gates removeNullFromType on the required set; recursive descent into nested properties and items is well-scoped.
  • Filesystem/shell struct tag removals: Tags were description-only (jsonschema:"description=..."); JSON serialization keys (json:"...") are untouched. No serialization breakage.
  • AddDescriptionParameter description text: Shortened text is functionally equivalent — no logic change.
  • slog.WarnContext changes: Each call site already had a ctx in scope; the substitution is correct.
  • Cassette updates: Updated request bodies match the new schema shapes for all five providers (OpenAI strict mode, Anthropic, Gemini, Mistral). The type narrowing from ["null","array"]"array" for required fields aligns with the PR's stated intent and preserves strict-mode compatibility.

No bugs found in the changed code.

@dgageot dgageot merged commit 5bd2a27 into docker:main May 7, 2026
8 checks passed
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.

3 participants