Skip to content
IsoKron

Updates send the change, not the whole object

An update tool that replaces the whole object overwrites every field the caller sends, including ones it did not mean to change; offer a field patch (only the named fields change) or an update_mask, and require a version on full replacement.

Check surface-full-replace · Write-surface design · default severity: advice · rubric 2.1.0

What fails

The tool reads as a full replacement (replace, overwrite or put) and takes no field mask, so every field the caller sends overwrites what is stored, including fields it did not mean to change.

The rule

A tool that replaces a whole object, deletes an object or accepts a version MUST refuse the write with a conflict when the object has changed since the state the caller read, wherever the backend can detect the change.

Source: MCP Write-Safety Requirements 0.9

How to fix it

Offer a field-patch update that changes only the fields named, or take an update_mask, and require a version on full replacements.

  1. Make update arguments optional fields: only the ones sent change.
  2. Or take an update_mask listing the fields to change.
  3. If you keep a full replace, require expected_version (see the version-guard check).

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(
  'update_issue',
  {
    title: 'Update issue',
    description: 'Change only the fields you send on one issue; fields you leave out stay as they are. Use when the user asks to edit an issue.',
    inputSchema: z.strictObject({
      issue_id: z.string().describe('Issue ID, for example ISS-42'),
      title: z.string().optional().describe('New title'),
      state: z.enum(['open', 'closed']).optional().describe('New state'),
      expected_version: z.number().int().describe('The version get_issue returned'),
    }),
    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
  },
  async ({ issue_id, title, state, expected_version }) => ({ 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="Update issue",
    annotations=ToolAnnotations(readOnlyHint=False, destructiveHint=True, idempotentHint=True, openWorldHint=False),
)
def update_issue(
    issue_id: Annotated[str, Field(description="Issue ID, for example ISS-42")],
    expected_version: Annotated[int, Field(description="The version get_issue returned")],
    title: Annotated[str | None, Field(description="New title")] = None,
    state: Annotated[Literal["open", "closed"] | None, Field(description="New state")] = None,
) -> str:
    """Change only the fields you send on one issue; fields you leave out stay as they are. Use when the user asks to edit an issue."""
    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

PATCH or PUT for an MCP update tool?

PATCH semantics: the model sends only what should change. With PUT semantics it must resend every field, and anything it gets wrong or stale is written back.

Why is this worse with models than with people?

A model fills the whole object from what it read earlier, which may be stale or summarised. Every field it echoes is a chance to overwrite a newer value.

Further reading

How this check is graded

It counts toward: Write-surface design. See the rubric.

Last verified against MCP Write-Safety Requirements 0.9 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