# 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. Last verified against MCP Write-Safety Requirements 0.9 on 2026-11-18.

## 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](https://isokron.ai/mws#mws-conc-2)

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

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

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

## Related checks

- [Update and delete tools take a version or precondition](https://isokron.ai/mcp-check/checks/surface-version-guard)
- [Create and send tools take a retry key](https://isokron.ai/mcp-check/checks/surface-retry-key)
- [Read tools declare an outputSchema](https://isokron.ai/mcp-check/checks/schema-output-schema)
- [Write-surface design for MCP tools](https://isokron.ai/mcp-check/checks/write-safety)

## Further reading

- [Send the change, not the object](https://isokron.ai/research/send-the-change-not-the-object)
- [MWS-CONC-2: refuse stale writes](https://isokron.ai/mws#mws-conc-2)

Counts toward: Write-surface design.

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

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