Skip to content
IsoKron

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

Error
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.

Source: Anthropic: Writing effective tools for agents

How to fix it

Declare the object's "properties" (and "required"), or split it into named arguments.

  1. Declare "properties" and "required" for every object argument.
  2. If the object is a free-form map, say so with additionalProperties and a value type, and describe the keys.
  3. Prefer named top-level arguments for anything the model must fill in.

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(
  '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

Python
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.

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