Skip to content

Tool input schemas: Zod in Node.js, JSON Schema in Go, Pydantic in Python - #1336

Merged
tbarbugli merged 1 commit into
acceleratefrom
tommaso/tool-input-schemas
Oct 27, 2026
Merged

tbarbugli merged 1 commit into
acceleratefrom
tommaso/tool-input-schemas

Conversation

@tbarbugli

Copy link
Copy Markdown
Member

Tool input schemas, the idiomatic way in each SDK, with every call's arguments checked before the function runs.

Node.js: Zod

parameters takes a Zod 4 schema, or any Standard JSON Schema (ArkType, Valibot). The model is told the JSON Schema it describes (~standard.jsonSchema.input, draft 2020-12), and each call is parsed by ~standard.validate before run, which gets the parsed, typed value with defaults filled in. The SDK does not import Zod; it is a dev dependency for tests. A non-object schema, or a Standard Schema with no JSON Schema, is refused at registration. Hand-written JSON Schema is passed through unchecked, as before.

Go: JSON Schema

  • Every call is validated against the tool's schema (santhosh-tekuri/jsonschema/v6, draft 2020-12, formats asserted) before the function runs. Errors read /seats: maximum: got 12, want 9.
  • New struct tags: enum, minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf, minLength, maxLength, minItems, maxItems, pattern, format, default, example, plus invopop-style jsonschema:"k=v,...".
  • RegisterSchema takes the schema as any (a map, raw JSON, or another library's schema type); new RegisterWithSchema[In] decodes into a struct.
  • default is only told to the model; a field left out arrives as its zero value.

Python: Pydantic

  • register_function builds a Pydantic model from the signature (Annotated[..., Field(...)] works), and the schema the model sees is that model's, with $refs inlined, titles dropped and Optional[X] shown as X.
  • A function taking a single BaseModel gets its fields as the tool's arguments and is handed the parsed model.
  • Arguments are validated and converted; failures raise ToolArgumentsError (a TypeError). Only the fields the model sent are passed, so the function's own defaults still apply; unknown arguments are still dropped.
  • parameters_schema= is unchanged. Adds pydantic>=2.7.

uv.lock only gains the two pydantic lines: the lock on accelerate was already stale (uv lock --check fails there, and a full relock drops the unrelated livekit packages), so that is left for its own change.

Tests

  • JS: tests/schemas.test.ts (6), 315/315 pass.
  • Go: tools/validate_test.go (10), full suite passes.
  • Python: tests/test_tool_schemas.py (14); pytest -m "not integration" tests/ plugins/*/tests/*.py gives 1978 passed with no new failures against accelerate (the 3 collection errors are on accelerate too).

Docs: GetStream/getstream.io#811.

…thon

Node.js takes a Zod 4 (Standard JSON Schema) schema as a tool's parameters
and parses each call's arguments with it. Go checks every call's arguments
against the tool's JSON Schema, reads more struct tags, and takes a schema
written by hand with RegisterSchema and RegisterWithSchema. Python
describes a function's arguments with Pydantic, flattens a single model
parameter, and checks and converts each call's arguments.
@tbarbugli
tbarbugli merged commit 6705d40 into accelerate Oct 27, 2026
53 checks passed
@tbarbugli
tbarbugli deleted the tommaso/tool-input-schemas branch October 27, 2026 15:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant