# 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. Last verified against Anthropic: Writing effective tools for agents on 2026-11-18.

## Error message you’ll see

```text
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: https://github.com/HubSpot/mcp-server/issues/2

## 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](https://www.anthropic.com/engineering/writing-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

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

## 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](https://isokron.ai/mcp-check/checks/schema-additional-properties)
- [Every argument has a description](https://isokron.ai/mcp-check/checks/schema-param-description)
- [Composition branches carry presence rules, not types](https://isokron.ai/mcp-check/checks/schema-oneof-branch-types)
- [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
