Object arguments declare their fields
An object argument with no "properties" tells the model nothing about its shape; declare its fields (and "required"), or replace it with named top-level arguments.
Check schema-open-object · Schema and description quality · default severity: advice · rubric 2.1.0
Error message you’ll see
Invalid schema for function 'hubspot_search_objects': In context=('properties', 'filterGroups', 'items', 'properties', 'filters', 'items', 'properties', 'values'), array schema missing items.OpenAI API, for an array argument with no "items". Where this was reported
What fails
An argument of type object with no "properties" accepts anything, so the model must guess the shape.
The rule
Avoid ambiguity by clearly describing (and enforcing with strict data models) expected inputs and outputs.
How to fix it
Declare the object's "properties" (and "required"), or split it into named arguments.
- Declare "properties" and "required" for every object argument.
- If the object is a free-form map, say so with additionalProperties and a value type, and describe the keys.
- Prefer named top-level arguments for anything the model must fill in.
TypeScript SDK
import { McpServer } from '@modelcontextprotocol/server';
import * as z from 'zod';
const server = new McpServer({ name: 'issues', version: '1.0.0' });
server.registerTool(
'create_issue',
{
title: 'Create issue',
description: 'Create one issue. Use when the user asks to file or report something.',
inputSchema: z.strictObject({
project_id: z.string().describe('Project ID, for example PRJ-7'),
title: z.string().describe('Issue title, one line'),
priority: z.enum(['low', 'normal', 'high']).default('normal').describe('Priority'),
}),
annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
},
async ({ project_id, title, priority }) => ({ content: [{ type: 'text', text: 'Done' }] }),
);Python SDK
from typing import Annotated, Literal
from pydantic import Field
from mcp.server.mcpserver import MCPServer
from mcp.types import ToolAnnotations
server = MCPServer("issues")
@server.tool(
title="Create issue",
annotations=ToolAnnotations(readOnlyHint=False, destructiveHint=False, openWorldHint=False),
)
def create_issue(
project_id: Annotated[str, Field(description="Project ID, for example PRJ-7")],
title: Annotated[str, Field(description="Issue title, one line")],
priority: Annotated[Literal["low", "normal", "high"], Field(description="Priority")] = "normal",
) -> str:
"""Create one issue. Use when the user asks to file or report something."""
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 do my object arguments arrive as strings?
With no declared shape, some models serialise the object into a JSON string. Declaring its properties fixes most of these cases.
How do I allow arbitrary metadata keys?
Use {"type": "object", "additionalProperties": {"type": "string"}} and describe what the keys mean, so the model knows it is a map.
Related checks
- Unknown arguments are rejected
- Every argument has a description
- Composition branches carry presence rules, not types
- 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 Anthropic: Writing effective tools for agents 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