MCPs and Agents: Lessons From Building Tools

Over the past few months I've been experimenting with Model Context Protocol (MCP) servers and how they interact with agents. The line between "what belongs in the tool" and "what belongs in the agent" isn't obvious, and I've made a few mistakes along the way. Here's where I've landed so far.

Tool Description vs Agent Knowledge

The clean split looks like this:

• MCP tool description: "What this tool does and how to call it."
• Agent knowledge: "When and why this tool should be called."

Keep tool definitions lean — just enough detail to ensure correct invocation. Too much description not only blurs responsibilities but also consumes valuable context window space.

Specific vs Generic Tools

One of the trickiest balances has been tool granularity.

• Generic tools (e.g., "query database") maximize flexibility but force the agent to hold more logic.
• Specific tools (e.g., "get today's order backlog") are easy for the agent to use but can lead to tool sprawl.

My working strategy is a layered approach:

1. Start with generic tools to cover broad ground.
2. Observe where the agent consistently struggles.
3. Wrap those pain points into thin, specific tools on top of the generic base.

The CLI as the First-Class Interface

One lesson that surprised me: the best way to design MCP tools is to start by designing a robust CLI application.

Why? Because:

• A CLI forces ergonomics. If it's painful for me to type, it'll be worse for an agent.
• A CLI doubles as documentation in motion. Engineers can discover tools by playing with commands, not just reading schemas.
• Most importantly: if the MCP tool layer simply wraps the CLI, then both humans and AIs get access to the same capabilities. I can use it in my shell, and the agent can use it in context.

I've started thinking of the CLI as the canonical surface, and MCP tools as thin wrappers that plug agents into it. That way:

• Agents gain the ability to call powerful, well-tested commands.
• Engineers get a human-friendly CLI they can use directly.
• Maintenance is simpler, because there's one implementation behind both.

In other words: build once, serve twice.

Closing Thoughts

The relationship between MCPs and agents is about drawing a clean seam. Tools are capabilities. Agents are decision-makers. CLIs are the proving ground.

When tool descriptions grow too verbose, you lose clarity and waste context space. When they're too sparse, the agent flails. The sweet spot is:

• Tight, minimal tool descriptions
• Agent reasoning layers for usage context
• A CLI-first design philosophy so both humans and AIs can leverage the same system.

That's the model I've been working towards. It's lean, flexible, and gives me confidence that I'm not building for AI alone—but for engineers too.