Making Your MCP Tools Pleasant for Engineers to Build On

A thin wrapper around your existing API clients gets a new tool shipped fast and stays easy to understand, but it pushes error handling, timeouts, and logging conventions onto every tool author individually, which drifts over time. A fuller internal framework enforces those conventions consistently but takes real investment to build and can feel heavy for a team with only a handful of tools.

Most teams are better served starting with the thin wrapper and a written checklist, then investing in the framework once the number of tools, and the number of people writing them, outgrows what a checklist can keep consistent.

An engineer should be able to call a single MCP tool directly, with a fixed input, and see exactly what comes back, without starting a full conversation with the model. Without this, every small bug fix requires reproducing it through natural language, which is slow and makes the bug harder to isolate than it needs to be.

When a tool behaves correctly but the agent still makes a bad decision, it's often because the tool's description or output format confused the model, not because the tool itself is broken. Give engineers visibility into how the model interpreted their tool's output, not just whether the tool call succeeded, so they can fix the actual problem instead of guessing.

• No local way to test a single tool call. Every change requires a full deploy or a live conversation to verify.
• Inconsistent error conventions across tools. Engineers have to relearn how failures are reported for each tool they touch.
• Tool descriptions written for humans, not for the model. A description that reads well in documentation can still be a poor prompt for a model deciding when to call it.
• No visibility into how the model used a tool's output. Bugs get diagnosed by guessing instead of by looking at the actual trace.

Each of these is individually small, but they compound: an engineer who has to fight all four at once on their first tool contribution tends to conclude that building tools is harder and slower than it actually needs to be, and starts routing around the pattern instead of adopting it.

Say a tool that looks up inventory counts is returning a stale number for one specific warehouse, and an engineer needs to track down why. Before any tooling investment, this means writing a full test conversation, running the whole agent, and reading through a transcript to see the input and output buried in the middle of a much longer exchange, then repeating that cycle for every guess at the cause.

After adding a way to call the tool directly with fixed input and see the model's interpretation of its output, the same investigation takes a few minutes: call the tool with the warehouse ID directly, see the raw response, immediately spot that the cache layer is returning a value that's a day old. The bug itself was the same in both cases; only the cost of finding it changed, and that cost difference is exactly what determines how often engineers are willing to dig into a tool issue instead of working around it.

That second investigation also surfaced something the first approach never would have: a second, unrelated tool sharing the same stale cache layer, quietly returning outdated data for a different warehouse the whole time. Good tooling doesn't just make the bug you're looking for easier to find, it tends to surface the ones you weren't looking for yet.