MCP tool design: pair full-replace with delta-ops
Designing MCP tools that wrap a REST PATCH endpoint when the same field can be edited either as full-replace or as an additive/subtractive delta.
When exposing a PATCH endpoint via MCP, the easy path is one big edit_x tool that takes the full new state for every field — but this makes simple operations expensive. For instance, add one tag becomes get_person, mutate the tags array, patch_person — three round-trips when the model could have called one add_tag with just the new tag string. The right design is to expose both shapes: keep the catchall edit_person tool for full-replace semantics (tags, aliases, body, relationships as arrays) AND add narrow delta-shaped tools (add_tag, remove_tag, add_relationship, remove_relationship, remove_link) that do the read-modify-write server-side. The narrow tools deduplicate (do not re-add an existing tag) and silently no-op on absent values (idempotent removes). The model picks based on intent — full-replace when it has the new desired state, deltas when it just wants to nudge one value. Mirror this on what the underlying API already accepts — most well-designed PATCH endpoints already support links_add and links_remove deltas next to the replace-shape fields, so the MCP tools are thin wrappers either way.
When wrapping a REST PATCH endpoint as an MCP tool surface, ship both a catchall full-replace edit_x tool AND narrow delta tools for the fields that get touched most often individually. Costs ~30 lines of MCP-tool code per delta-shape, saves the model two round-trips every time it makes a small change.