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
tools.0.custom.input_schema: input_schema does not support oneOf, allOf, or anyOf at the top levelClaude API (400), for any tool sent with a composed root schema. Where this was reported
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
oneOfbranches are not enforced for whichever branch does not match.
How to fix it
Move the property definitions to the root "properties" and leave only "required" in each branch.
- Move every property definition to the root "properties".
- 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.
- Do not use a zod union or a Pydantic union as the whole argument model; use optional fields on one object.
TypeScript SDK
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
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.
Related checks
- inputSchema has type "object" at the root
- inputSchema and outputSchema are valid JSON Schema
- Object arguments declare their fields
- All checks in MCP tool input and output schemas
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