# 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. Last verified against MCP schema.ts, revision 2026-07-28 on 2026-11-18.

## Error message you’ll see

```text
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: https://github.com/aaif-goose/goose/issues/12773

```text
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: https://github.com/Wei-Shaw/sub2api/issues/7915

## 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](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2026-07-28/schema.ts)

## 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

```ts
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"
```

## 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](https://isokron.ai/mcp-check/checks/spec-input-schema-root-object)
- [inputSchema and outputSchema are valid JSON Schema](https://isokron.ai/mcp-check/checks/spec-schema-valid)
- [Object arguments declare their fields](https://isokron.ai/mcp-check/checks/schema-open-object)
- [MCP tool input and output schemas](https://isokron.ai/mcp-check/checks/schema)

Counts toward: Schema and description quality.

Rubric: https://isokron.ai/mcp-check/rubric

Check your tool list: https://isokron.ai/mcp-check
