Oleksandr Kuzmenko, EditorPublished 8 min readAI-assisted · editor-reviewed
TL;DR
- Avoid 1:1 REST-to-MCP mappings; 10 consolidated tools can cover the work of 31 naive endpoints.
- Use declarative delta operations instead of full JSON replacement to prevent silent state corruption.
- Store complex payloads server-side and pass opaque handles to subsequent agent tools.
Key facts
- Claude Code Description Limit
- 2,048 characters (default cap March–October 2026)
- Consolidated Read/Write Tools
- 10 tools cover what a naive design would split into 31
- Dashboard Layout Payload
- ~15,000 characters avoided on edits via op lists
Designing Intent-Driven Tools Over Naive Wrappers
Wrapping a REST API directly into Model Context Protocol (MCP) tools creates massive overhead. In Metabase's v1 (version 60), nearly every endpoint became a tool, eventually leaving four separate tools just to run queries. While an obvious design for 11 readable and 10 writable content types would demand 31 separate read and write tools, Metabase 64 consolidated that ground into 10 tools (out of 24 total). A single get_content reads 11 content types in batches, while nine write tools accept a method of create or update. There is no destructive delete tool; an archived boolean allows safe rollback. Optional fields accept null to satisfy strict schemas, while explicit removals use a dedicated "clear": ["description"] list.
Eliminating Silent Corruption with Delta Operations
Language models regenerate text token by token rather than copying state. In Metabase, an example dashboard layout spans roughly 15,000 characters. When models were forced to resubmit the full JSON to tweak a single card, they frequently dropped filter connections or mutated IDs. The redesigned dashboard_write replaces full document replacement with an array of declarative operations (add_heading, add_card, wire_parameter). Negative IDs (like -1, -2) allow referencing new cards before persistence, while autowire: true binds filters across tabs. The operations compile into an atomic transaction supporting dry-run verification via validate_only: true.
Server-Side Handles and Find-and-Replace Updates
For Markdown documents, whole-body rewrites detached paragraph comment threads. Metabase solved this by enforcing find-and-replace diffs with exact old_str and new_str matching. For database querying, execute_query now returns rows alongside an opaque query_handle. Instead of retyping fragile table and column IDs into visualize_query or question_write, the model references the server-side handle, preventing silent data discrepancies.
Try it in 2 minutes
{
"method": "update",
"id": 7,
"edits": [
{
"old_str": "up 12%",
"new_str": "up 14%"
}
]
}When to use
- When designing agent-facing tools for complex SaaS domains with rich relational data structures.
When NOT to use
- When building trivial MCP servers exposing only one or two stateless lookup functions.
What to do today
- Audit existing MCP servers to replace full-document JSON PUT requests with delta operations.
- Implement server-side query handles to eliminate column ID hallucination between query and chart steps.
Step names are taken from What to do today.
Step names are taken from What to do today. Audit existing MCP servers to replace full-document JSON PUT requests with delta operations.. Implement server-side query handles to eliminate column ID hallucination between query and chart steps.
- Audit existing MCP servers to replace full-document JSON PUT requests with delta operations.
- Implement server-side query handles to eliminate column ID hallucination between query and chart steps.
