From APIs to Agent Tools: Designing for Multi-Agent Systems

Quick Overview

In this article, I explore key principles of agent and tool design — and how they integrate with your backend in ways that can make or break your project.

We’ll look at the problem areas that matter most:

Why multi-agent systems → when and why specialization helps.
Organizing agent tools and responsibilities → minimizing context switches and enabling success.
MCP design concepts → using Model Context Protocol to wrap APIs safely.
Integration patterns → how to connect agents to your APIs without breaking what already works.

The goal: a clear set of principles you can apply to design agents that are effective, safe, and production-ready.

1. Why Multi-Agent Systems

One agent with every tool sounds simple. In practice, it quickly collapses under complexity. Multi-agent systems solve this by:

Specialization → Agents are scoped to a domain (e.g., Business Analyst, Project Manager, Resource Manager). Narrow context = better focus.
Reduced context switching → Each agent carries fewer tools and instructions. Smaller prompt = more consistent behavior.
Collaboration → Agents hand off results or share context where needed.

Think of it as organizational design for AI: teams succeed when roles are clear, responsibilities aligned, and overlap limited to backup coverage.

Orchestration: Supervisor vs. Swarm

Multi-agent systems don’t just need specialized roles — they need a way to decide who acts when. Two common orchestration models are:

Supervisor pattern → A central coordinator (a “manager agent”) delegates tasks to domain agents and integrates results. Great for hierarchical workflows and strict governance.
Swarm pattern → Each agents is aware some or all other agents and their expertise, when a task is out of the bounds of the current agent, they’ll hand it off to the agent based on their expertise. The specialist takes over the conversation and you engage with it until it can’t, it then hands off the task to another specialist and so on.

Mezzoic uses a swarm approach. This means:

Agents are given overlapping tool access to minimize context switching.
Context and workflow orchestration live in the platform, not in a single “boss agent.”

👉 The trade-off: swarms require more careful tool design (clear descriptions, scoped responsibilities, overlapping coverage) so agents don’t collide or wander.

2. Organizing Agent Tools and Responsibilities

Tools are the bridge between your backend and your agents. Organizing them well is critical.

Principles:

Start from use cases → Map what the agent must accomplish end-to-end, then derive tools.
Minimize context switches → Prefer one agent completing a flow over bouncing between agents.
Specialize, but don’t over-partition → Give agents enough overlap to complete work instead of stalling.

Exclusive domains:
Each tool should have a clear, non-overlapping responsibility. Ambiguity (two tools that can both edit a quote) leads to failure.

How to define:

Purpose → specific outcome it achieves.
Scope → what it doesn’t do.
Trigger conditions → when the agent should call it.

👉 Treat tools like team roles: overlap creates confusion, clarity enables success.

Agent to tool mapping diagram:

These agents have a primary set of tools that enable their roles, but they also have access to the same utilities, access to the users details, security modules and any tangentially related tools that they may need.

These tools are thin wrappers around mcp_clients that in turn are proxies to mcp_servers.

3. MCP Design Concepts

What is an MCP server? MCP servers are a standard way to provide tools for your agents. Just like APIs are a standard way to define your core business logic. In a micro services architecture, there’s typically another layer above your microservices, a specialized API Wrapper that implements a set of use cases that use the micro services but is dedicated to an application. These Backend For Frontends BFFs are similar to MCP Servers, or an MCP server is similar to a BFF, it’s a dedicated tool for your agent, that in this case wraps around your micro services.

MCP servers:

Wrap existing APIs in a standard interface agents can query at runtime.
Expose available actions (quote.add_line_item, quote.set_delivery_date) instead of generic endpoints.
Provide consistent descriptions that become the agent’s “manual.”

Marshal-by-Value vs Marshal-by-Reference

Let’s briefly talk about Marshal by Reference vs Value. Agents have a hard time constructing complex objects, an LLM doesn’t edit a json object, it regenerates it on the fly and more often than not, gets it wrong. You can solve this by providing a rich set of instructions and describe every field etc, that’s a lot of work, adds to context and it’ll still get it wrong. Instead we design the tools with simple responsibilities and parameters that are easy to undertand.

Traditional APIs (marshal-by-value):
- Clients (like SPAs) hold a rich domain object (e.g., a Quote).
- They apply business logic locally, then send the whole or partial object back (PUT /quote {…}).
- Works great with deterministic clients — humans don’t forget required fields.
Agents (marshal-by-reference):
- LLMs are bad at reconstructing complex objects. They often drop fields, mis-format, or overwrite.
- Instead, agents do better when they reference an entity ID and apply small, intent-driven changes.
- Example:
  - quote.set_delivery_date(quote_id, date)
  - quote.add_line_item(quote_id, sku, qty, price)

Why it matters:

Smaller prompts → less chance of hallucination.
Narrow scope → fewer invalid states.
Server enforces business rules → no fragile prompt gymnastics.

Yes, it’s two hops (fetch + patch), but in agent workflows the LLM’s “thinking time” dwarfs network latency. Reliability wins over raw performance.

Tool Design Patterns (recap)

Intent verbs > CRUD → tools reflect user goals, not table ops.
Patch over PUT → safe partial updates instead of risky overwrites.
Validation at the edge → business rules live in MCP, not the LLM.
Idempotency → every tool call safe to retry.

Example

Instead of:

PUT /quotes/123
{
  "id": "123",
  "customer": { ... },
  "lineItems": [ ... ],
  "deliveryDate": "2025-09-12",
  ...
}

Expose tools like:

quote.set_delivery_date(quote_id, date)
quote.add_line_item(quote_id, sku, qty, price)
quote.assign_owner(quote_id, user_id)

Each one mutates a small part of the aggregate by reference. The MCP server handles the fetch → patch → persist cycle.

4. Integration Patterns with APIs

The second principle of SOLID — Open/Closed — matters here: extend, don’t modify. Keep your backend stable, add MCP Servers as extensions. Don’t break what works.

Patterns:

Backend-for-Frontend (BFF) → MCP server as the backend for your agent, wrapping API calls into intent-driven tools.
Sidecar → MCP deployed alongside a service, tightly coupled to its API.
Gateway → centralized MCP layer, routing requests to many services.

Security:

Agents act on behalf of users → OAuth OBO flow.
Tools inherit API-level RBAC/ABAC → no shadow permissions.
Narrow scopes → tool:quote.read, tool:quote.create.

5. Trade-offs and Reality Check

Pros:

Clearer prompts, fewer invalid states.
Agents behave more predictably.
Security and governance aligned with backend.

Cons:

More tools to design and maintain.
Extra round trips (fetch + patch).
Need for concurrency control.

But in practice: reliability > raw RPS. Agents spend more time “thinking” than calling APIs. Safe, intent-driven tools are worth the overhead.

6. Practical Takeaways

APIs don’t translate 1:1 into tools.
Wrap APIs into intent-driven MCP servers.
Organize tools with exclusive domains and clear responsibilities.
Treat prompts and tool descriptions as first-class code — versioned, tested, and owned.
Build agents as extensions, not modifications, of your backend.

Closing

APIs power your systems. But agents need something more: tools they can discover, understand, and use safely. MCP servers bridge that gap, transforming APIs into intent-driven capabilities that agents can wield reliably.

The takeaway: don’t let agents call APIs raw. Wrap them, describe them, test them — and you’ll move from fragile demos to production-ready multi-agent systems.

From APIs to Agent Tools: Designing for Multi-Agent Systems

Quick Overview