The Agentic Intention Framework

Introduction: The paradox of building with AI in the loop

As modern software engineers, we’re trained in the agile way: ship fast, iterate based on feedback, let design emerge. We start minimal and evolve based on what we learn from users.

But architecting robust, performant, and useful MCP servers demands the opposite: with LLMs in the loop, the system’s effectiveness is significantly improved by intentionally and explicitly defining constraints upfront. These constraints improve the predictability, discoverability, and usability of our tools. Why?

Because for an LLM to make reasonable choices, it must be carefully guided. They can’t read between the lines, infer unstated intentions, or choose between multiple paths to the same goal. They work purely with (their interpretation of) what we explicitly provide. The context we give them becomes their entire universe of what’s possible.

Because LLMs rely heavily on clarity, precision, and explicit structure, defining intentional constraints upfront is critical.

This fundamentally shifts how we measure success. Instead of evaluating how fast we ship and iterate, now we prioritize testing how reliably our constraints allow LLMs to discover and effectively compose our tools.

The Constraint Paradox

• Traditional software development: minimize constraints, maximize flexibility
• MCP server development: maximize constraints, maximize flexibility

The clearer our constraints, the more confidently LLMs can compose our tools into helpful solutions.

A competitive landscape amplifies this new reality. Given the great usability that MCP provides, users are able to seamlessly switch between different servers and tools. And, as the ecosystem matures, they will have an increasing number of options from which to choose.

Instead of thinking of this as me suggesting to abandon agile principles 😱, I’d rather you saw it as a realization that building with AI in the loop has different rules. Where traditional software rewards emergent flexibility, MCP servers reward intentional constraints.

There’s absolutely nothing wrong about yolo’ing your way thru your first MCP servers. I’m just wanting to tell you when I did that, I had to reel myself back from a much deeper abyss than it was fun (or profitable) for me, all because I didn’t have this guide that is now in front of your eyeballs! 

What follows is a practical framework for architecting MCP servers that embraces constraints and upfront intention as competitive advantages. I’ll share concrete pointers for how to architect MCP servers intentionally enough to get considerable gains 💪 quickly, but not so much that it doesn’t feel playful or experimental or productive.

As my Gen Z kid says: “Trust.”

Why MCP makes clear intention so very critical

When developers encounter an unexpected behavior with a tool, we experiment, ask questions, read code, read the logs, read docs. I’m kidding!!! We never read the docs.

When machines (you know, the regular kind) encounter unknown inputs, they follow their programming: retry, retry with different options, follow alternative logic paths, or fail gracefully with error codes. How deterministic of them.

When LLMs encounter a vaguely described tool with seemingly ambiguous parameters, they will either:

• Bypass the tool entirely (missing its value)
• Misuse it with wrong parameters (wasting tokens)
• Chain it incorrectly with other tools (breaking workflows)

The unintended impact from tools designed with vague intentions manifests differently based on the type of MCP client.

When humans are in the loop:

• Every interaction tests clarity: ambiguous tools lead to failed attempts and user frustration
• Trust compounds or erodes with each use: consistent behavior builds confidence, unpredictability drives users away
• Users develop workarounds for what works, building fragile patterns around specific tool quirks

When MCP clients are agents:

• Failure modes cascade silently: agents propagate errors downstream without correction
• Integration assumptions become permanent contracts: some agent developers might hard-code expectations that break with any change
• Latency compounds dramatically: unclear tools trigger multiple attempts with different parameters, multiplying both time and token costs
• There’s no forgiveness: agents interpret tools literally, without human ability to infer intent

Tool metadata: what LLMs actually see

When we build an MCP server, our primary users are LLMs. These “users” must:

• Select appropriate tools based solely on metadata
• Reason about when and how to use them
• Compose them into solutions
• Work within context window limits

If there is ONE THING that LLMs are terrible at, it’s handling ambiguity. Clear metadata is what enables confident tool selection. Vague metadata, then, forces expensive experimentation on the part of the LLMs.

Clear metadata with intentional boundaries

{
  "name": "search_documents",
  "description": "Search markdown documents by content or title",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search term to find in documents"
      },
      "searchIn": {
        "type": "string",
        "enum": ["content", "title", "both"],
        "description": "Where to search"
      }
    },
    "required": ["query"]
  }
}Code language: JSON / JSON with Comments (json)

Vague metadata that hurts LLM usage

{
  "name": "process", // Process what?
  "description": "Processes data", // How? What kind?
  "inputSchema": {
    "type": "object",
    "properties": {
      "data": {
        "type": "string",
        "description": "The data" // What format? What content?
      },
      "mode": {
        "type": "string", // What are valid modes?
        "description": "Processing mode"
      }
    }
  }
}Code language: JSON / JSON with Comments (json)

The difference:

• Clear: LLMs know exactly when to use search_documents and what parameters to provide
• Vague: LLMs must guess what “process” does, what “modes” exist, and what “data” format is expected

Beyond this point, I will demonstrate how to use intention to define boundaries, enable composition, and guide evolution.

The intention statement framework for agentic systems

The beauty of MCP development is we can start with a single tool and grow from there. We don’t need a 50-page specification (didn’t I tell you to trust??!). For maximum precision in your intention, I suggest using the agentic intention framework to define it more completely, and before you write any code:

This MCP server helps [WHO] to [DO WHAT] with [WHAT CONSTRAINTS]so that [WHY THIS MATTERS]

Examples:

• “This MCP server helps individual developers to manage their personal notes with minimal friction so that context-switching doesn’t kill productivity”
• “This MCP server helps SREs to debug production issues with read-only access so that they can find root causes without risking further damage”
• “This MCP server helps data analysts to explore CSV files with read-only safety so that they avoid costly accidental data corruption
• “This MCP server helps developers and technical writers to validate any MCP-related content against official specifications with strict adherence to official definitions on a per-version basis so that they can have high confidence that MCP-related content they read or write is free from misinformation”

Here’s how to know if your intention is strong:

• Weak intention: “This server processes log files” (missing WHO and WHY)
• Strong intention: “This server helps SREs to debug production issues faster so that they can reduce system downtime”

Test: Can you measure if you’re succeeding?

• Processing log files → What does success look like? Who benefits? Why does it matter?
• Helping SREs debug production issues → Measurable: time to root cause, escalation rates, downtime minutes ✓