
# 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.

MCPs and Agents: Lessons From Building Tools


# A Software Engineer's Quick Guide to Generative AI

## Introduction: A Paradigm Shift in Software Engineering

Every so often, software engineering faces a paradigm shift — a moment when the foundations of how we build and reason about systems are challenged. Cloud computing, microservices, and APIs all forced us to rethink our assumptions. Generative AI is the latest of these paradigm shifts. Like those before it, it isn't about discarding everything we know, but about integrating a powerful new tool into our workflows.

## LLMs as Programs You Don't Write

Think of a large language model (LLM) as a massive precompiled binary. You didn't write the code, but you can run it by supplying inputs and reading outputs.

- **In-weight memory** (training data) is like the functions and constants baked into the binary.
- **In-context memory** (prompts, documents you supply) is like runtime arguments and heap allocations.

Your job as an engineer isn't to understand every internal parameter, but to use the model effectively — just as you don't need to know every optimization inside a compiler to write good code

## Context Windows: The Call Stack and Heap of AI

LLMs don't have infinite memory. Instead, they operate inside a context window, the maximum amount of information they can handle at once.

- The **system prompt** is like the main() method — it sets the rules of execution.
- **Conversation history** is like a call stack — every new input builds on prior frames.
- **Retrieved documents** (via retrieval-augmented generation, or RAG) are like heap memory 

Overflow the context window and tokens get dropped — a silent segmentation fault for your conversation.

## Tokens: The Assembly Language of AI

Tokens are the machine instructions of generative AI. A token might be a whole word, a prefix, punctuation, or even part of a number.

Processing scales quadratically with tokens. Double the context size, and you get roughly four times the compute cost

It's the same tradeoff engineers faced with compilers analyzing entire dependency graphs instead of reading files line by line.

## Context Engineering: Debugging the Prompt

Working with AI is as much about what you don't say as what you do. Context engineering is the craft of supplying only the most relevant inputs.

- **Avoid irrelevant imports.** Don't clutter the context with unnecessary data.
- **Summarize and refactor.** Roll up conversation history into compact summaries, like refactoring repetitive code into utilities.
- **Load tools dynamically.** Only bring in the APIs and connectors that matter to the current task

The principle is the same as good software design: keep things lean, modular, and relevant.

## MCP: APIs for AI

The Model Context Protocol (MCP) standardizes how AI systems connect to external tools and data sources. It's the REST API of the AI world.

- **Hosts** (IDEs, CLIs) = clients consuming the API.
- **Servers** = lightweight programs exposing capabilities.
- **Registries & Gateways** = discovery and routing layers

With MCP, you can connect AI to codebases, ticketing systems, and wikis. Instead of manually context-switching between five tabs, the model can fetch logs, docs, and assignments in one session. It's the same productivity leap developers saw when APIs become standard practice.

## Best Practices for Engineers

- **Keep context lean.** Don't overload the model — treat tokens as scarce resources.
- **Design tools with tasks in mind.** An MCP tool should be like a small, reusable function.
- **Stay problem-focused.** The goal isn't to use AI for its own sake, but to solve real engineering problems

## Conclusion: Navigating the Paradigm Shift

Generative AI isn't magic — it's another paradigm shift in how we build software. It gives us a new runtime environment, one that excels at fuzzy reasoning and language-driven workflows. Like any tool, it requires practice, experimentation, and craftsmanship.

You don't need to understand every detail of its inner workings, just as you don't need to know every compiler optimization to write efficient code. What matters is learning how to apply it thoughtfully, with an engineer's mindset.

The paradigm has shifted — now it's our turn to navigate it.

Lachlan Kuhr

About

Blog

MCPs and Agents: Lessons From Building Tools

A Software Engineer's Quick Guide to Generative AI