Skip to content
IsoKron

Composition branches carry presence rules, not types

Declare every argument under the root "properties" and keep oneOf/anyOf branches to "required" lists only; type rules inside branches are not enforced, and the Claude and OpenAI APIs refuse composition at the top level outright.

Check schema-oneof-branch-types · Schema and description quality · default severity: attention · rubric 2.1.0

Error message you’ll see

Error
tools.0.custom.input_schema: input_schema does not support oneOf, allOf, or anyOf at the top level

Claude API (400), for any tool sent with a composed root schema. Where this was reported

Error
Invalid schema for function 'mcp__codex_app__automation_update': schema must have type 'object' and not have 'oneOf'/'anyOf'/'allOf'/'enum'/'const'/'not' at the top level.

OpenAI API, when a client forwards the tool as a function. Where this was reported

What fails

A oneOf or anyOf branch at the root declares property types. The specification advises declaring "properties" at the root and keeping branches to "required" lists.

The rule

A subschema that fails on a type error is indistinguishable from one that does not apply, so type constraints placed inside oneOf branches are not enforced for whichever branch does not match.

Source: MCP schema.ts, revision 2026-07-28

How to fix it

Move the property definitions to the root "properties" and leave only "required" in each branch.

  1. Move every property definition to the root "properties".
  2. If exactly one of several arguments is needed, keep a oneOf of "required" lists, or better, make them optional and say in the description which to send.
  3. Do not use a zod union or a Pydantic union as the whole argument model; use optional fields on one object.

TypeScript SDK

TypeScript
import { McpServer } from '@modelcontextprotocol/server';
import * as z from 'zod';

const server = new McpServer({ name: 'issues', version: '1.0.0' });

server.registerTool(
  'find_user',
  {
    title: 'Find user',
    description: 'Find one user by email or by ID; send exactly one of the two. Use when the user names a person.',
    inputSchema: z.strictObject({
      email: z.string().optional().describe('Email address; send this or user_id'),
      user_id: z.string().optional().describe('User ID; send this or email'),
    }),
    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
  },
  async ({ email, user_id }) => ({ content: [{ type: 'text', text: 'Done' }] }),
);

Python SDK

Python
from typing import Annotated

from pydantic import Field
from mcp.server.mcpserver import MCPServer
from mcp.types import ToolAnnotations

server = MCPServer("issues")

@server.tool(
    title="Find user",
    annotations=ToolAnnotations(readOnlyHint=True, destructiveHint=False, openWorldHint=False),
)
def find_user(
    email: Annotated[str | None, Field(description="Email address; send this or user_id")] = None,
    user_id: Annotated[str | None, Field(description="User ID; send this or email")] = None,
) -> str:
    """Find one user by email or by ID; send exactly one of the two. Use when the user names a person."""
    return "Done"

Run against @modelcontextprotocol/server 2.4.0, mcp 2.3.0 and fastmcp 4.2.2 on 2026-11-18; the checker confirms this check passes on the tool list each snippet produces.

Questions

Why does Claude reject a valid JSON Schema?

The schema is valid JSON Schema, but the Claude API accepts only an object schema at the root of input_schema, without oneOf, anyOf or allOf there. The OpenAI API has the same rule for functions.

My SDK generated the anyOf. How do I stop it?

A union type at the top level (z.union([...]) as the input, or a Pydantic union as the only parameter) produces it. Use one object with optional fields and check the combination in the handler.

How this check is graded

It counts toward: Schema and description quality. See the rubric.

Last verified against MCP schema.ts, revision 2026-07-28 on 2026-11-18. The rule above is quoted in the source’s own words. This page as Markdown.

Check your tool list: paste your tools/list, nothing is sent anywhere