Adding a tool to your MCP surface is more like adding a column to your database than adding an endpoint to your REST API. Once it's there, agents will use it. Once agents are using it, you can't easily remove it without breaking their behavior. Every tool is a long-lived commitment to a name, a parameter shape, and a semantic contract.
This is true even when the tool seems small. Especially when the tool seems small. The temptation is "just add get_workspace_count real quick" because the implementation is one line. The cost isn't the implementation; the cost is that now agents in the wild will assume get_workspace_count exists and use it for things you didn't anticipate.
This piece is the smallest tool we've actually shipped, the smallest tool we keep almost shipping but don't, and the discipline that decides which side of the line a proposal lands on.
The smallest tool we ship: recent_events
Our smallest MCP tool is recent_events. It takes one optional parameter (a limit, defaulting to 50) and returns a list of recent events the calling principal has access to.
recent_events({ limit: 50 }): Event[]
That's it. No filters, no pagination cursors, no event-type selection, no workspace targeting. The tool returns the last N events the principal can see, ordered by recency.
Why is this small? Because the shape of the response is rich: each event has actor, action, target, timestamp. The agent can filter what it cares about on the client side — "events about workspace X this week" or "events authored by Govind." The tool itself is dumb.
This dumbness is deliberate. We could have shipped recent_events_for_workspace, recent_events_by_actor, recent_events_by_type, and so on. We didn't. Each filter would have been a separate tool name, separate parameter shape, separate test surface, separate documentation page. The agent would have to learn five names instead of one.
By keeping the tool a single shape with a rich response, we let the agent compose. The agent can call recent_events, look at the results, and decide what's relevant. If the agent needs to see only events about a specific workspace, it filters in its own logic — not by us shipping a new tool.
The tool we keep almost shipping: set_workspace_visibility
There's a tool we've considered shipping at least four times: set_workspace_visibility. It would let an agent change a workspace from private to org to public (or vice versa).
We don't ship it. Here's why.
Visibility changes are dangerous in the consent-gate sense — they widen access. An agent flipping a private workspace to public is the kind of mistake that can leak company data. We could ship set_workspace_visibility with a consent-gate handshake, but the more we examined it, the more we realized:
- The use case is rare. Visibility changes are usually a deliberate decision a human makes, not a routine operation an agent automates.
- The recovery is hard. If the agent flips a workspace public and an external party scrapes it before the human approves the gate (which we wouldn't trigger because we wouldn't ship the gated version)... wait, we would gate it. But still: the kind of agent that wants to change visibility is the kind we should be careful giving.
- Adjacent tools are sufficient. The agent can ask the human directly via the chat surface: "I think this workspace should be org-visible — can you change it?" The human does the change in the UI. We lose nothing.
The discipline is "if a tool's failure mode is high and its use case is rare, ship it as a human-only operation." Visibility falls in that bucket. So does account deletion, plan changes (we ship those, but with strong gates), API key rotation, and a few others.
The tool we shipped after a long argument: update_doc
The middle ground is update_doc. This tool replaces the body of a doc with new TipTap JSON. It's the agent's primary write tool for prose.
We argued about this one for a week before shipping. The arguments against:
- It's a write tool, so the cost of mistakes is higher than a read tool.
- The TipTap JSON shape is complex; agents will produce malformed JSON and the tool will fail unhelpfully.
- It bypasses the live-collab merge layer (which humans use), so two agents writing simultaneously will overwrite each other.
The arguments for:
- Agents need to be able to draft prose. There's no smaller version of this.
- The shape-cap protection means even malformed JSON can't take down the doc.
- Last-write-wins is acceptable for now (CRDT is on the roadmap).
We shipped update_doc. The implementation goes through writeDocBody so all the substrate-level protections (shape cap, attribution, etc.) apply. The tool is the right shape for what agents actually do.
The lesson: the question isn't "is this tool dangerous?" The question is "is this tool necessary to a real workflow, and can we make the dangerous parts safe?" update_doc passed both tests; set_workspace_visibility passed neither.
The discipline
What gets a tool onto the surface, in our actual checklist:
- Does it solve a recurring agent need? Not "an agent might want this someday." A real, recurring need that exists in workflows we've seen.
- Is the shape stable? The parameters and response shape need to make sense across the lifecycle of the agent. If we'd want to change the shape in 3 months, don't ship.
- Are the safety surfaces in place? Identity, attribution, scope, consent gates, shape caps — does this tool fit cleanly into the existing layers, or does it require new ones?
- Is there a smaller alternative? Could the agent compose existing tools to do this, even if less directly?
A proposal has to pass all four. Most don't. Most proposals fail at #4 — the agent can already do this with two existing tools and some logic, so we don't ship a new one.
What our surface looks like today
We have 20 MCP tools as of this writing. They're divided into:
- Workspaces (5): list, get, create, update metadata, delete (gated).
- Rows (5): list, get, create, update, delete.
- Doc (2): get_doc, update_doc.
- Comments (2): list, create.
- Billing (3): get_plan, upgrade_plan (gated), downgrade_plan (gated).
- Other (3): support_request, recent_events, search.
The list grows about 1-2 tools per quarter. The discipline of "what gets in" is what keeps the surface stable.
What this composes with
The MCP surface is the agent-facing edge of all the substrate-level protections we've built. It composes with:
- Identity — every tool call is attributed to the calling agent.
- Authorization — every tool checks the agent's workspace memberships before reading or writing.
- Consent gates — gated tools require the propose-confirm pattern; unrelated to the surface size, related to the operation type.
- Shape caps — write tools route through substrate functions that enforce caps.
We covered the bigger pattern in AI-agent-first primitives. The smallest-MCP-tool discipline is one piece of that — keep the surface narrow, every tool earns its slot.
Cross-links
- AI-agent-first primitives — the substrate primitives the surface sits on.
- Consent gates for dangerous operations — why the gated tools are gated.
- Backmerges or bust — substrate-level fixes generalize across surfaces.
FAQ
Why is the MCP surface a long-lived commitment?
Once a tool is on the surface, agents in the wild start depending on it. Removing it later breaks their behavior. The cost isn't the engineering effort to add it; it's the cost of ever having to deprecate it. Treat each tool addition like a database column change.
What makes a "small" MCP tool?
A tool with one job, one parameter shape, and a rich response that lets the agent compose downstream. recent_events is small; recent_events_for_workspace_filtered_by_actor_in_last_24h is not. The smaller the tool's surface, the more flexible the agent's use of it.
Why not ship more tools?
Each tool is a permanent commitment to a name, parameters, and semantic contract. More tools mean more surface for agents to learn, more documentation to maintain, more breakage when shapes change. The discipline of "minimum viable surface" preserves long-term flexibility.
How do you decide what goes on the surface?
Four criteria: real recurring need, stable shape, safety surfaces in place, no smaller composition possible. A proposal has to pass all four. Most fail at the fourth — the agent can already do this with existing tools and some logic.
What's a tool you specifically don't ship?
set_workspace_visibility. It would let an agent change workspace privacy. We don't ship it because the use case is rare, the failure mode is high (data leakage), and the human-only path (user changes it in the UI) is fine. Adjacent tools are sufficient for the agent's actual needs.
{
"@context": "https://schema.org",
"@type": "BlogPosting",
"headline": "The smallest useful MCP tool",
"description": "Every tool on the MCP surface is a permanent commitment. The smallest one we've shipped, the one we keep considering but don't, and the discipline that makes the difference.",
"datePublished": "2026-04-26",
"author": { "@type": "Person", "name": "Argus" },
"publisher": { "@type": "Organization", "name": "Dock", "url": "https://trydock.ai" },
"image": "https://trydock.ai/blog-mockups/style-d-dreamscape/the-smallest-mcp-tool.webp",
"mainEntityOfPage": "https://trydock.ai/blog/the-smallest-mcp-tool"
}