Loading skill
Install any skill in seconds. Free to start, no credit card required.
Get Started Free →minpeter/tool-schema-design
Designs JSON Schemas for LLM tool/function calling that survive across providers.
Passed 17 of 22 test cases with the skill, and 13 of 22 without it.
and 3 more in the full report
4 fixed13 passed either way5 still failing0 broke
Tokens, turns and time describe resource use, not a dollar price.
One of 4 test cases the skill fixed. Same model, same prompt, with and without the skill.
When configuring tool schemas for xAI (Grok) models, should we explicitly set `additionalProperties: false` in our wire schemas, and what tool count limits apply?
| Checked | Without skill | With skill |
|---|---|---|
| The response specifies that xAI strict behavior is implicit so explicit additionalProperties false can be omitted. | Missed | Passed |
| The response mentions capping total tools at 128 for xAI. | Passed | Passed |
The instructions your model reads when the skill loads.
House rules for writing LLM tool/function-calling schemas that work
everywhere. Verified against the primary docs of 12+ providers and inference
stacks — see references/provider-matrix.md
for the per-provider evidence table.
No single JSON Schema is accepted unchanged by every provider. The decisive
contradiction: additionalProperties: false is required by OpenAI
strict, DeepSeek strict, and Bedrock, but stripped or rejected on
Gemini/Firebase paths. Nullability spelling also differs per provider. So:
Keep one canonical schema (rich in meaning) → compile through thin per-provider adapters → validate the post-transform wire schema.
An adapter-free canonical schema is the best outcome; adapters exist only for strict-mode transforms. Never ship a lowest-common-denominator schema as the product — it is a non-strict fallback for discovery phases only.
Violating these cannot be repaired by an adapter.
| # | Rule | Why |
|---|---|---|
| H1 | Root is a non-empty type: "object". No root union/enum/const. | MCP, OpenAI strict, Bedrock, Cohere, Kimi, Qwen, xAI all force an object root. Top-level enums only exist in Gemini structured output — never tool input. |
| H2 | Concrete types only: object/string/number/integer/boolean/array; arrays carry one schema-valued items. | Universally supported; type errors are a graded failure class in tool-calling benchmarks. |
| H3 | description on the tool and on every non-obvious property (units, constraints, selection criteria). Skip tautologies. | Provider guidance calls descriptions the largest factor in tool performance. Descriptions cost tokens and are an attack surface on untrusted tools. |
| H4 | oneOf/allOf/not forbidden. Nested anyOf is allowed. | anyOf confirmed on OpenAI strict, Anthropic, xAI, DeepSeek strict, Cohere, current Gemini, Fireworks (full 2020-12), FriendliAI (anyOf only), vLLM/SGLang (XGrammar). oneOf/allOf are rejected or undocumented on several of these. Root anyOf stays banned via H1. Avoid even anyOf when targeting undocumented providers (Together, GMI, Groq, GLM/Kimi/Qwen) — split into separate tools or a string discriminator enum. |
| H5 | No title. | Absent from the Firebase vocabulary; costs nothing to skip. |
| H6 | Limits: nesting ≤ 10, total fields ≤ 200, tools ≤ 20 per request. | OpenAI depth cap 10; Cohere counts an aggregate 200-field budget; Anthropic strict allows 20 tools/request. Accuracy degrades as tool count grows. |
| H7 | No $ref/$defs/default/const/numeric-length constraints/pattern in the canonical schema. | An adapter-free schema beats a clever one. Inline repeated structures; put constraints in the description prose and validate server-side. |
| # | Rule | Adapter behavior |
|---|---|---|
| S1 | required reflects real optionality. Optional fields are fine. | OpenAI/DeepSeek strict: make every property required and encode optional as a nullable union. Everyone else: pass through. |
test cases passed, vs 13 / 22 without
More skills from the same source and nearby in the registry, with their headline benchmark lift.