The schema a model is handed is generated by the contract, not the one you wrote
— so it can accept forms the wire never will. Three mistakes models make
reliably are absorbed at the boundary instead of coming back as a failed call.
There is a fourth mistake that is deliberately not absorbed, and it is the
last section on this page: an argument the schema does not declare is refused
rather than dropped.
'{"requests": [...]}' becomes {"requests": [...]}
Models sometimes serialize a nested object as a JSON string instead of passing
it as an object. A model_validator(mode="before") finds any
BaseModel/list/dict-typed field whose value is a string starting with {
or [, and parses it before field validation runs.
"dateTime" becomes date_time
Models send camelCase keys inside nested objects, matching the API’s own docs. A
schema that answered only to its own field names would drop the key as unknown:
the field stays None, the API receives {}, and returns a confusing 400 with
no local validation error at all.
So the contract answers to all three spellings. Every field carries camelCase,
PascalCase and snake_case aliases — dateTime, DateTime and date_time are
all valid input — and this holds whichever convention the schema’s author wrote
in. Stripe’s schemas are snake_case and Gmail’s are camelCase; both resolve in
both directions.
All three are declared aliases rather than merely tolerated ones, which is
what makes the refusal in the next section safe: with unknown keys refused, a
spelling that is only “also allowed” would become an error.
model_dump() is unaffected — it still returns snake_case field names, so the
key-case conversion at serialization time works exactly as before.
An argument the schema does not declare is refused
Pydantic’s default is to ignore unknown keys. At a tool boundary that is the
worst available behaviour, because the result is not an error — it is a wrong
answer that nothing marks as wrong.
A model that invents a filter, or mistypes a real one, previously got a
successful call and an unfiltered page:
That sent limit=2, returned two arbitrary customers, and said nothing
anywhere about the filter it had thrown away. The agent then reasons over rows
it believes were filtered. The same happens for a plausible typo — emails for
email — which is the more likely mistake of the two.
So generated schemas set extra="forbid", and the call above raises
ToolValidationError before the
network:
which is a message a model can read and correct, in the
retry loop this library already has.
to_json_schema() carries additionalProperties: false for the same reason, on
the root and on every nested object — so a provider enforcing strict schemas
mostly prevents the mistake before a call is made at all.
This tightened in a way a host application can notice. If you were passing an
extra key to ainvoke and relying on it being ignored, that call now raises.
The fix is to remove the key, or to declare it on the schema if it should have
been on the wire. Per-call headers are unaffected: they are a keyword-only
argument, not part of the schema, and never were.
A rejection the model can act on
Left to the agent framework, a rejected call comes back wrapped in that
framework’s own template, with the entire kwargs payload dumped at the model:
Charter raises ToolValidationError
carrying a compact rendering instead:
The structured per-field errors are on the exception too (.errors), so a host
application can render its own version.
When the JSON-string coercion above fails, the naive behaviour is to pass the
string through and let type checking complain:
That is a type error. The model concludes it sent the wrong structure, retries
with different content and the same broken syntax, and loops forever — because
the real problem was a syntax error, such as one extra closing brace.
Charter raises with the decoder’s own detail:
Now the model knows it is a syntax problem and where. The check is unambiguous: a
string starting with { or [ for a BaseModel/list/dict-typed field is
always an attempted JSON serialization — there is no other case.