If you support more than one model provider, you've probably written the same tool definition several times. The idea is the same every time: a name, a description, and a JSON Schema for the arguments. But each provider wraps it differently and accepts a slightly different dialect of JSON Schema. A schema that works in one place can be rejected outright in another. Worse, it can be accepted and then quietly behave differently.

This post covers what actually differs, the pitfalls that cost me the most time, and a small standalone converter (one TypeScript file, no dependencies). It turns one canonical definition into all five shapes.

The canonical form

Keep one source of truth per tool: a name, a description, and a plain JSON Schema whose root is an object. Everything else is a build artefact you generate from it. Here's the example used throughout (descriptions and one nested field trimmed; the full version is at the bottom of the code):

{
  "name": "create_reminder",
  "description": "Schedule a reminder for the user. Use when the user asks to be reminded; not for calendar events with attendees.",
  "parameters": {
    "type": "object",
    "properties": {
      "message":   { "type": "string" },
      "remind_at": { "type": "string", "format": "date-time" },
      "priority":  { "type": "integer", "enum": [1, 2, 3] },
      "repeat":    { "$ref": "#/$defs/Repeat" },
      "channel":   { "type": "string", "enum": ["push", "sms"], "default": "push" }
    },
    "required": ["message", "remind_at"],
    "$defs": { "Repeat": { "type": "object", "properties": { "every": { "type": "string", "enum": ["day", "week", "month"] } }, "required": ["every"] } }
  }
}

It's deliberately awkward. It has optional fields, a numeric enum, a $ref and a default, which are the things that tend to break.

What actually differs

OpenAI (Chat Completions). Each tool is {"type": "function", "function": {name, description, parameters}}. The Responses API flattens this to {"type": "function", name, description, parameters, strict}, so watch which endpoint you're targeting. Without strict mode, OpenAI is fairly tolerant about ordinary JSON Schema.

OpenAI strict mode ("strict": true). This is where most conversions break. With strict mode, the model's arguments are constrained to your schema, but only a subset of JSON Schema is supported, and it has rules:

• every object must set "additionalProperties": false, including objects nested inside arrays;
• every property must appear in required;
• so an optional field has to become a required, nullable one: "type": ["string", "null"], or an anyOf with a {"type": "null"} branch;
• the root must be an object, not an anyOf.

The set of supported keywords (pattern, format values, length and range bounds) has changed over time and differs for fine-tuned models. Check the current Structured Outputs docs rather than trusting a blog post, including this one.

Anthropic. Each tool is flat: {name, description, input_schema}. The name must match ^[a-zA-Z0-9_-]{1,64}$, so no spaces, dots or slashes. A tool called get weather.v2 will be rejected. If you're adapting code written for OpenAI, the two mechanical traps are the input_schema key and the missing function wrapper.

Gemini. Declarations go in tools: [{functionDeclarations: [...]}]. Each one is flat: {name, description, parameters}. The classic parameters field takes an OpenAPI 3.0-style Schema object, not full JSON Schema. In practice:

• one type per schema, with nullable: true instead of ["string", "null"];
• enum values are strings;
• no $ref or $defs; inline them;
• no additionalProperties, const or default;
• property names should be letters, digits and underscores (so a page-size parameter is a problem);
• a tool with no arguments simply omits parameters.

Newer Gemini models also accept a separate parametersJsonSchema field that takes regular JSON Schema. It's mutually exclusive with parameters in the same declaration. If your models support it, it removes most of the down-conversion below. The classic field is still the most widely accepted, so the converter targets that.

MCP. A tool returned by tools/list has name, an optional title, description, inputSchema (an object schema), and optionally outputSchema and annotations. The annotations are readOnlyHint, destructiveHint, idempotentHint and openWorldHint. The spec says clients must treat annotations as untrusted unless they come from a trusted server, so they're hints for the UI, not a security boundary.

The pitfalls that bite

1. Optional fields under strict mode. The canonical schema says priority is optional. Strict mode says every key is required. The fix changes your wire contract: the model will now send "priority": null instead of leaving it out. Your executor has to accept both shapes if you ship both formats.
2. enum plus null. If you make an enum field nullable by changing its type to ["integer", "null"] but leave the enum as [1, 2, 3], then null is still invalid. Add null to the enum too.
3. default is not applied for you. Models often omit optional fields, and validators don't fill in defaults. If channel defaults to push, your code has to apply that. The converter strips default where it isn't supported and warns you.
4. Numeric enums on Gemini. [1, 2, 3] becomes ["1", "2", "3"]. The model will send a string, so convert it back in your code.
5. $ref. Inline local references before generating Gemini output, and preferably for every target, since not every client resolves them. Recursive schemas can't be inlined. The converter throws instead of looping forever.
6. Nested objects. The strict-mode rules apply at every level. A common bug is to lock down the root and leave repeat (or the items of an array) open.
7. Silently dropped keywords. Every converter has to remove things. A good one tells you what it removed. Each function below returns a warnings list with a JSON-pointer-style path, so nothing disappears silently.

The converter

One file, no dependencies. Save it as convert.ts and run node convert.ts (Node 22.18+ strips the types itself), or use npx tsx convert.ts on older versions. It exports toOpenAI, toOpenAIStrict, toAnthropic, toGemini and toMCP, and prints all five for the example when run directly.

// convert.ts: convert one canonical tool definition (name + description + JSON Schema)
// into OpenAI, OpenAI strict, Anthropic, Gemini and MCP tool formats.
// No dependencies. Run with: node convert.ts   (Node 22.18+ runs TypeScript directly)
//                       or: npx tsx convert.ts

type Schema = { [key: string]: any };

export interface CanonicalTool {
  name: string;
  description: string;
  parameters: Schema; // JSON Schema for the arguments; root must be an object
}

export interface Result<T> {
  tool: T;
  warnings: string[];
}

const NAME_RE = /^[a-zA-Z0-9_-]{1,64}$/; // Anthropic's rule; also a safe portable choice

// Inline local "#/$defs/..." / "#/definitions/..." refs. Recursive schemas can't be inlined: throw.
function inlineRefs(schema: Schema, root: Schema = schema, seen: string[] = []): Schema {
  if (Array.isArray(schema)) return schema.map((s) => inlineRefs(s, root, seen)) as any;
  if (!schema || typeof schema !== "object") return schema;
  if (typeof schema.$ref === "string") {
    const ref = schema.$ref;
    if (!ref.startsWith("#/")) throw new Error(`external $ref not supported: ${ref}`);
    if (seen.includes(ref)) throw new Error(`recursive $ref cannot be inlined: ${ref}`);
    const target = ref.slice(2).split("/").reduce((node: any, key) => node?.[key.replace(/~1/g, "/").replace(/~0/g, "~")], root);
    if (target === undefined) throw new Error(`unresolved $ref: ${ref}`);
    const { $ref, ...siblings } = schema;
    return inlineRefs({ ...target, ...siblings }, root, [...seen, ref]);
  }
  const out: Schema = {};
  for (const [key, value] of Object.entries(schema)) {
    if (key === "$defs" || key === "definitions") continue;
    out[key] = typeof value === "object" && value !== null ? inlineRefs(value, root, seen) : value;
  }
  return out;
}

function prepare(tool: CanonicalTool): { params: Schema; warnings: string[] } {
  const warnings: string[] = [];
  if (!NAME_RE.test(tool.name)) warnings.push(`name "${tool.name}" does not match ${NAME_RE}`);
  const params = inlineRefs(structuredClone(tool.parameters ?? { type: "object", properties: {} }));
  delete params.$schema;
  if (params.type !== "object") throw new Error("parameters root must be {type: 'object'}");
  for (const r of params.required ?? []) {
    if (!(r in (params.properties ?? {}))) throw new Error(`required lists unknown property "${r}"`);
  }
  return { params, warnings };
}

// ---------- OpenAI (Chat Completions) ----------
export function toOpenAI(tool: CanonicalTool): Result<Schema> {
  const { params, warnings } = prepare(tool);
  return { tool: { type: "function", function: { name: tool.name, description: tool.description, parameters: params } }, warnings };
}

// ---------- OpenAI strict mode ----------
// Every object: all properties required + additionalProperties:false. Optional fields become nullable.
function makeNullable(s: Schema): Schema {
  if (Array.isArray(s.type)) return s.type.includes("null") ? s : { ...s, type: [...s.type, "null"], ...(s.enum ? { enum: [...s.enum, null] } : {}) };
  if (typeof s.type === "string") {
    if (s.type === "null") return s;
    // Objects and arrays: wrap in anyOf so the nested keywords stay attached to their own branch.
    if (s.type === "object" || s.type === "array") return { anyOf: [s, { type: "null" }] };
    return { ...s, type: [s.type, "null"], ...(s.enum && !s.enum.includes(null) ? { enum: [...s.enum, null] } : {}) };
  }
  // no type (e.g. anyOf): add a null branch
  if (Array.isArray(s.anyOf)) return { ...s, anyOf: [...s.anyOf, { type: "null" }] };
  return { anyOf: [s, { type: "null" }] };
}

function strictify(s: Schema, path: string, warnings: string[]): Schema {
  if (!s || typeof s !== "object") return s;
  const out: Schema = { ...s };
  if (out.oneOf) { out.anyOf = out.oneOf; delete out.oneOf; warnings.push(`${path}: oneOf rewritten as anyOf`); }
  if (out.anyOf) out.anyOf = out.anyOf.map((b: Schema, i: number) => strictify(b, `${path}/anyOf/${i}`, warnings));
  if (out.items) out.items = strictify(out.items, `${path}/items`, warnings);
  const isObject = out.type === "object" || (Array.isArray(out.type) && out.type.includes("object")) || out.properties;
  if (isObject) {
    const props: Schema = out.properties ?? {};
    const required = new Set<string>(out.required ?? []);
    const newProps: Schema = {};
    for (const [key, child] of Object.entries(props)) {
      let c = strictify(child as Schema, `${path}/properties/${key}`, warnings);
      if (!required.has(key)) {
        c = makeNullable(c);
        warnings.push(`${path}/properties/${key}: optional -> required + nullable`);
      }
      newProps[key] = c;
    }
    out.properties = newProps;
    out.required = Object.keys(newProps);
    if (out.additionalProperties !== false) {
      if (out.additionalProperties !== undefined) warnings.push(`${path}: additionalProperties forced to false`);
      out.additionalProperties = false;
    }
  }
  if ("default" in out) { delete out.default; warnings.push(`${path}: default removed (apply it in your code)`); }
  return out;
}

export function toOpenAIStrict(tool: CanonicalTool): Result<Schema> {
  const { params, warnings } = prepare(tool);
  const parameters = strictify(params, "#", warnings);
  return { tool: { type: "function", function: { name: tool.name, description: tool.description, strict: true, parameters } }, warnings };
}

// ---------- Anthropic ----------
export function toAnthropic(tool: CanonicalTool): Result<Schema> {
  const { params, warnings } = prepare(tool);
  return { tool: { name: tool.name, description: tool.description, input_schema: params }, warnings };
}

// ---------- Gemini (functionDeclarations[].parameters, OpenAPI-style subset) ----------
const GEMINI_KEYS = new Set([
  "type", "format", "title", "description", "nullable", "enum", "properties", "required", "items",
  "minItems", "maxItems", "minimum", "maximum", "minLength", "maxLength", "pattern", "anyOf",
  "minProperties", "maxProperties", "propertyOrdering",
]);

function geminify(s: Schema, path: string, warnings: string[]): Schema {
  if (!s || typeof s !== "object") return s;
  let src: Schema = { ...s };
  if ("const" in src) { src.enum = [src.const]; delete src.const; }
  if (src.oneOf) { src.anyOf = src.oneOf; delete src.oneOf; }
  if (Array.isArray(src.type)) {
    const types = src.type.filter((t: string) => t !== "null");
    if (src.type.includes("null")) src.nullable = true;
    if (types.length === 1) src.type = types[0];
    else { src.anyOf = types.map((t: string) => ({ type: t })); delete src.type; warnings.push(`${path}: type array -> anyOf`); }
  }
  if (src.enum) {
    const values = src.enum.filter((v: unknown) => v !== null);
    if (src.enum.includes(null)) src.nullable = true;
    if (values.some((v: unknown) => typeof v !== "string")) {
      warnings.push(`${path}: non-string enum converted to strings (convert back in your code)`);
      src.type = "string";
    }
    src.enum = values.map(String);
  }
  const out: Schema = {};
  for (const [key, value] of Object.entries(src)) {
    if (!GEMINI_KEYS.has(key)) { warnings.push(`${path}: "${key}" removed`); continue; }
    if (key === "properties") {
      out.properties = {};
      for (const [k, v] of Object.entries(value as Schema)) {
        if (!/^[A-Za-z_][A-Za-z0-9_]{0,63}$/.test(k)) warnings.push(`${path}/properties/${k}: property name may be rejected by Gemini`);
        out.properties[k] = geminify(v as Schema, `${path}/properties/${k}`, warnings);
      }
    } else if (key === "items") out.items = geminify(value, `${path}/items`, warnings);
    else if (key === "anyOf") out.anyOf = (value as Schema[]).map((b, i) => geminify(b, `${path}/anyOf/${i}`, warnings));
    else out[key] = value;
  }
  return out;
}

export function toGemini(tool: CanonicalTool): Result<Schema> {
  const { params, warnings } = prepare(tool);
  const decl: Schema = { name: tool.name, description: tool.description };
  // A tool with no arguments omits "parameters" entirely.
  if (Object.keys(params.properties ?? {}).length > 0) decl.parameters = geminify(params, "#", warnings);
  return { tool: decl, warnings };
}

// ---------- MCP ----------
export function toMCP(tool: CanonicalTool, annotations?: Schema): Result<Schema> {
  const { params, warnings } = prepare(tool);
  return { tool: { name: tool.name, description: tool.description, inputSchema: params, ...(annotations ? { annotations } : {}) }, warnings };
}

// ---------- demo ----------
const example: CanonicalTool = {
  name: "create_reminder",
  description: "Schedule a reminder for the user. Use when the user asks to be reminded; not for calendar events with attendees.",
  parameters: {
    $schema: "https://json-schema.org/draft/2020-12/schema",
    type: "object",
    properties: {
      message: { type: "string", description: "What to remind the user about." },
      remind_at: { type: "string", format: "date-time", description: "ISO 8601 timestamp with offset." },
      priority: { type: "integer", enum: [1, 2, 3], description: "1 = low, 3 = high." },
      repeat: { $ref: "#/$defs/Repeat" },
      channel: { type: "string", enum: ["push", "sms"], default: "push" },
    },
    required: ["message", "remind_at"],
    additionalProperties: false,
    $defs: {
      Repeat: {
        type: "object",
        properties: { every: { type: "string", enum: ["day", "week", "month"] }, count: { type: "integer", minimum: 1 } },
        required: ["every"],
      },
    },
  },
};

if (import.meta.url === `file://${process.argv[1]}`) {
  for (const [label, fn] of Object.entries({ openai: toOpenAI, openai_strict: toOpenAIStrict, anthropic: toAnthropic, gemini: toGemini, mcp: toMCP })) {
    const { tool, warnings } = (fn as (t: CanonicalTool) => Result<Schema>)(example);
    console.log(`\n=== ${label} ===`);
    console.log(JSON.stringify(tool, null, 2));
    if (warnings.length) console.log("warnings:\n  " + warnings.join("\n  "));
  }
}

Running it on the example gives, among other things, this strict-mode version of repeat and priority:

"priority": { "type": ["integer", "null"], "enum": [1, 2, 3, null], "description": "1 = low, 3 = high." },
"repeat": {
  "anyOf": [
    { "type": "object", "properties": { "every": { "type": "string", "enum": ["day", "week", "month"] }, "count": { "type": ["integer", "null"], "minimum": 1 } },
      "required": ["every", "count"], "additionalProperties": false },
    { "type": "null" }
  ]
}

Notice that count, which was optional, is now required inside repeat and nullable. The Gemini version of priority comes out as {"type": "string", "enum": ["1", "2", "3"]}, with a warning that you need to convert it back.

A few design choices worth stating:

• Nullable objects use anyOf. For objects and arrays I wrap the schema in anyOf: [schema, {"type": "null"}] rather than using a type array, so the nested properties and required stay clearly attached to the object branch.
• oneOf becomes anyOf. Neither OpenAI strict mode nor the Gemini subset supports oneOf, and for model arguments the difference rarely matters. It's reported as a warning anyway.
• Gemini uses an allow-list, not a deny-list. Unknown keywords are removed and reported. That's safer than trying to list everything Gemini rejects.
• It doesn't validate arguments. That's your executor's job, and it should check everything the schema can't express: path containment, ID formats, read-only SQL, and so on.

Testing it

The converter itself has been run and type-checked. That doesn't mean the output will be accepted. To check a conversion properly:

• Snapshot the five outputs for each tool in your repo and diff them in code review.
• Send each generated tool to its provider once in CI, with a cheap model and tool_choice forced, and assert the request isn't rejected.
• Feed the arguments the model returns back through your own validator, especially the null versus missing cases.

Provider rules change, which is the main reason to keep the canonical form and regenerate everything else instead of hand-editing four files.

If you'd rather not maintain this yourself: I run a small paid API that does these conversions and lints them, including batch and OpenAPI-to-tools: ToolSchema Forge. Agents pay per call in USDC via x402. There's also a $7 cookbook and template pack with 23 ready-made tools in all these formats. The converter above is free to copy either way.

Rowan Vale