u/EdwinChittilappilly

You’ve probably had this happen. You ask your AI assistant to do something, check an order, look up a record, call an API, and instead of doing it, it makes something up. Confidently, plausibly, and wrong.

The usual assumption is that the model hallucinated because it’s a model, and models hallucinate. But there’s a specific fixable reason this happens and it has nothing to do with the model’s capabilities. It has to do with something boring and structural that most people never think about.

The AI and the app it’s trying to talk to are working from different instruction manuals.

Here’s how that works in practice. When an engineer builds a tool, like a function that looks up a customer by ID, they have to write it twice. Once as a web endpoint (so dashboards and scripts can call it), and once as an MCP tool (so an AI agent like Claude or Cursor can discover and use it). Both versions share the same core logic, but each has its own wrapper: routing, validation, schema definitions. The web version says the lookup takes a numeric ID. The agent version says it takes a text name. Or rather, it used to take a text name, three updates ago, before someone changed it to a numeric ID and forgot to update the agent’s copy.

When the agent tries to call the tool using the old instructions, it sends the wrong format. The tool rejects it. And instead of surfacing a clear error, the agent often fills in the gap with a plausible-looking guess. That’s not the model being dumb. That’s the model being given a stale map and then getting blamed for walking into the wall.

A 2025 study by Mastouri and colleagues confirmed that 88.6% of MCP servers, the tool layer that AI agents rely on, are just wrappers around existing web APIs. Let me explain why that number matters.

MCP is the language AI agents use to discover and call tools. HTTP is the language everything else uses: web dashboards, scripts, mobile apps, batch pipelines. Two different languages describing the same capabilities. When someone builds an MCP tool for an agent, they’re almost never building something from scratch. Nine times out of ten, they already have a working web API that does the thing. The MCP version is just a second description of the same capability, translated into a different format.

And that’s exactly the problem. Every one of those wrappers is a second copy. Someone has to maintain it by hand. When the web API changes, and web APIs change constantly, someone has to remember to update the MCP wrapper too. Not sometimes or most of the time. Every single time.

People forget. That’s not a character flaw; it’s how maintenance works. You update the thing you’re actively using (the web API) and you don’t think about the translation layer sitting in a config file somewhere until your agent starts confidently calling a function with the wrong parameters.

So the 88.6% isn’t a trivia point about how popular wrappers are. It’s saying the dual-maintenance problem isn’t a hypothetical edge case. It’s the default condition for almost everyone running agent tools. The thing that makes agents hallucinate tool calls isn’t rare. It’s the starting position.

Patil et al. showed that when type schemas are absent or out of date, LLMs hallucinate API calls at significantly higher rates. These two facts connect directly: the dual-maintenance problem is causing the hallucination problem.

The root cause is architectural. Frameworks like FastAPI are “route-first.” You define an HTTP route, and that’s your registration. If you want the same capability available to an AI agent, you write a second registration in MCP’s vocabulary. The two declarations share nothing structural. If the schema changes, both need manual updates, independently. FastMCP, the agent-side framework, is “tool-first” but doesn’t know anything about HTTP. The developer stands in the middle, copying changes back and forth.

This is where HarnessAPI comes in, and the idea is simpler than the problem suggests. Instead of building the communication channels first and bolting the capability onto them, you start with the capability itself.

In HarnessAPI, a “skill” is a folder containing two files: a handler (what the skill actually does) and a schema (what data it accepts and returns). That’s the single source of truth. From that one definition, the framework derives everything else: a streaming HTTP endpoint with Swagger documentation, an MCP tool registration for agents, and the content negotiation that lets both work from the same code. The handler, the HTTP schema, and the MCP schema are always identical, not by convention, not by diligent updating, but because they all resolve to the same Python object at runtime.

You can’t drift if there’s only one thing to maintain.

The practical upshot is that adding a new skill to an agent doesn’t require touching the framework code. You drop a folder into the skills directory, and the system discovers it, registers it for both web and agent access, and starts serving it. The framework code stays the same size no matter how many skills you add.

There are a few engineering details worth knowing about. They’re the kind of thing that makes the difference between a nice idea and something that actually works.

One handler, two modes. An interactive AI session needs a live stream of partial results. Think of watching a summary appear token by token. A batch pipeline just wants the finished output in one piece. HarnessAPI handles both from the same handler code. If the client sends the right Accept header, the framework buffers and returns the full result. Otherwise it streams. The skill author doesn’t think about this at all; the transport decision belongs to the caller.

Module isolation. Multiple skills commonly define classes named Input and Output. Load them naively, and the second skill overwrites the first. HarnessAPI creates a synthetic package namespace for each skill so they coexist. It’s a small thing, but it’s the kind of detail that would bite you the moment you had more than a handful of skills.

One process, two services. Normally you’d run a web server and an MCP server as separate processes, managing two deployments, two sets of environment variables, two sets of credentials. HarnessAPI subclasses FastAPI and mounts the MCP server inside it. Both run in a single process. Fewer moving parts, fewer failure modes, simpler deployment.

The numbers are straightforward. Across six representative skills, the traditional dual-stack approach (a FastAPI server plus a FastMCP server) required 170 lines of framework-facing code. HarnessAPI’s skill-first approach: 44 lines. That’s a 74% reduction in the boilerplate where bugs hide.

The system also ran twelve third-party skills through it, skills built by outside developers who never designed for this framework, and it registered and served them all without any manual changes. Drop-in ready.

There’s a detail I like that the paper almost glosses over: each skill has a configuration flag that lets you hide it from the agent layer while keeping it available via HTTP. If you’re running an agent that can use tools, you probably have some tools you want it to see and others you’d rather it didn’t. That’s not an afterthought. That’s the kind of access control that matters when you’re actually living with an agent, not just demoing one.

The reason your AI agent breaks, hallucinates, or gives garbled responses often isn’t that the model isn’t smart enough.

It’s that the infrastructure connecting the model to the tools it needs is held together with duct tape: two parallel copies of the same information, maintained by hand, drifting apart in silence. The skill-first inversion doesn’t make the model smarter. It makes the scaffolding reliable enough that the model can use what it actually knows.

That’s a different kind of fix. It doesn’t require a bigger model or a better prompt. It requires recognizing that the gap between what the tool expects and what the agent thinks it expects is where most of the silent failures live. And closing that gap structurally instead of hoping people will remember to update both copies.

Edwin Jose. “A Skill-First Framework for Unified Streaming APIs and MCP Tools.” arXiv:2605.22733. May 2026.