Understanding the Model Context Protocol 2: Why AI Models Think Differently

Jussi Hallila

Why AI Models Think Differently: Designing for Machine Intelligence

Part 2 of a 3-part series exploring how MCP revolutionizes AI integration

Here's the most counterintuitive truth about building tools for AI: everything you know about good API design will lead you astray. The patterns that make APIs elegant for human developers can confuse AI models and lead to poor results. Modularity, minimal descriptions, consistent naming are better to be left for humans.

We need to remember that AI and LLMs operate fundamentally differently than human intelligence and our tools need to respect those differences.

The Human Developer vs. The AI Model

How Human Developers Learn APIs

When you encounter a new API as a developer, you have powerful advantages:

You can engage in persistent learning by reading documentation once, experimenting with endpoints, and building mental models that carry forward to future projects. You also have contextual exploration capabilities that allow you to browse Stack Overflow, read blog posts, examine code examples, and ask colleagues for guidance.

When things go wrong, you can perform systematic error recovery by debugging methodically, reading error logs, and iterating until solutions work. Most importantly, you can develop conceptual understanding of the business logic behind an API and make intelligent assumptions about how it should work.

How AI Models Interact with Tools

AI models, despite their impressive capabilities, operate under completely different constraints:

They have no memory between sessions, meaning every conversation starts from scratch and the model can't "learn" your API over time. Their exploration is limited since models can't browse documentation or search for examples—they only have what you provide in tool descriptions.

Models are entirely context dependent, relying on pattern matching from their training data and your specific descriptions without true understanding. Their operation is stateless, with each tool call being independent and no ability to build on previous learning or gradually improve their usage. Unless you want to spend fortunes over and over again to fine-tune or retrain the models.

The Token Economy Problem

Every tool you create for an AI model consumes precious context tokens. Here's the brutal math:

  • Tool name and description: 50-150 tokens
  • Parameter definitions: 20-50 tokens each
  • JSON schema: 50-100 tokens per tool
  • Response handling: Additional tokens for each interaction

A typical API with 50 endpoints converted directly to MCP tools could consume from 15k to 25k tokens just for tool definitions. And after that we need to start prompting the LLM to use those tools which starts the second token slurping, doing the actual work.

This introduces a chicken and an egg problem. More tools, more capabilities. More tools, less context space to do actual work.

Conceptual Confusion in API Translation

Consider this common scenario: You're building MCP tools for a project management platform that has these API endpoints:

/api/projects/list
/api/workspaces/list  
/api/teams/list
/api/groups/list
/api/spaces/list

To human, these endpoints paint an ok picture of what is possible. Each of them represents a different organizational concept. But to an AI model seeing these for the first time, this is a bunch of unrelated endpoints and introduces conceptual chaos. What's the difference between a "workspace" and a "space"? When should it use "teams" vs. "groups"?

The model has no context for these words. It will guess based on names and descriptions, often incorrectly.

The Stateless Challenge

Here's where the differences become most noticeable. Consider this user request:

"Find the top-selling products in our e-commerce platform over the past month that were not included in the recent marketing campaigns."

A human developer would approach this systematically:

  1. Review the database schema or API documentation to understand the data model.
  2. Identify which dataset contains sales data for the platform.
  3. Query the sales data to extract top-performing products while filtering by date.
  4. Understand the structure of the marketing campaign data to identify excluded products.
  5. Cross-reference the sales data with the marketing campaign data.
  6. Combine the results programmatically or manually.

An AI model using direct API translations would need to:

  1. Guess the appropriate API endpoint to fetch sales data.
  2. Infer the date range format for querying sales, often trial-and-error.
  3. Identify what defines "top-selling" (e.g., quantity sold or total revenue) from available endpoints.
  4. Discover how marketing campaigns are represented and correlate excluded products.
  5. Perform these steps across multiple stateless API calls without carrying prior context to refine decisions.

Each step requires precise execution because the AI model cannot iteratively build knowledge across the conversation.

The Error Handling Gap

Traditional APIs often return simple error messages designed for developers to debug systematically:

{
  "error": "Invalid parameters: startDate",
  "code": 400
}

This is precise for a developer but problematic for an AI model. The model needs additional guidance to make sense of the error:

  • What format is expected for the startDate parameter?
  • How to determine the valid values?
  • Suggest alternatives or fixes to resolve the issue.
  • Clarify if this error is recoverable or fatal for the task.

The Discovery Problem

APIs typically expect developers to discover capabilities through documentation. But AI models only know what you tell them in tool descriptions.

That means that if you don't explain everything upfront, the model can't discover it later. But if you try to explain everything, you blow up the token budget and create information overload.

Rethinking Tool Design Philosophy

Understanding these limitations leads to a fundamentally new approach to tool design:

Start with Intent, Not Operations

Instead of exposing API endpoints directly, design tools around specific user goals:

  • Rather than including separate tools like getSalesData, getProductDetails, and getMarketingExclusions, create one tool: analyzeProductPerformance that manages the entire process from start to finish.

Build in Guidance

Each response should include clear instructions to guide the model's next steps:

 {
  "result": "Identified 5 top-selling products",
  "next_steps": "Use excludeFromMarketing() to add these products to the exclusion list",
  "top_selling_products": [
    "Product A",
    "Product B",
    "Product C"
  ]
}

Embrace Intelligent Error Handling

Errors should provide actionable insights rather than just reporting issues:

{
  "error": "No sales data found for the given date range.",
  "suggestion": "Check the date format or use getAvailableDates() for a valid range.",
  "available_date_ranges": [
    "2025-06-01 to 2025-06-30",
    "2025-05-01 to 2025-05-31"
  ]
}

Consolidate Thoughtfully

Group related operations that serve the same user intent but keep destructive operations separate for safety.

The Mindset Shift

The core insight is this: you're not building for a superintelligent being that will figure out your API. You're building for a powerful but constrained system that needs clear guidance, complete context, and intelligent assistance.

This doesn't mean treating AI models as "dumb." It means designing tools that work with their strengths while compensating for their limitations.

The best MCP tools feel almost magical to use because they anticipate what the AI needs at each step, provide exactly the right amount of context, and guide the model toward successful outcomes.

What This Means in Practice

In traditional API design, good practice focuses on creating minimal and focused endpoints with consistent naming conventions. Detailed documentation is usually kept separate from the API itself, enabling developers to explore and figure out workflows on their own. This conventional approach works well for human developers who can use their intuition and problem-solving skills.

In contrast, MCP tool design takes a different path. It prioritizes intent-based tools that handle complete workflows rather than breaking them into fragmented operations. These tools are self-documenting, providing responses that guide the model's next actions along the way. They come with built-in context and meaningful suggestions to assist the AI in navigating tasks. Furthermore, they anticipate common mistakes and aim to prevent them wherever possible.

This shift in mindset is not about simplifying APIs to the point of inefficiency but about optimizing them for a completely different type of intelligence. AI models require a fundamentally new design philosophy to effectively use the tools they are provided.

In Part 3, we'll explore specific strategies for designing MCP tools that AI models can use effectively, including real examples of tool consolidation and response design.

← Back to blog