Building For Agents
A practical guide for engineers designing APIs, MCP servers, observability systems, or delegated services for AI agents.
Postman's 2025 State of the API report noted the following: 89% of developers use AI, but only 24% design APIs for AI agents.
This is interesting because if you're building a product behind an API in 2026, chances are your users are agents.
We've only slowly began to discuss what it means to build for agents though. This blog will discuss several case studies and challenges faced when people tried to build agent facing APIs.
Today, most products assume this path:
Human -> UI -> Product
Increasingly, they also support this one:
Human -> Agent -> MCP / API -> Product
The second path has different constraints.
An agent pays for every schema and response in tokens, latency, and model attention. It may call a service hundreds of times during one task. It needs errors it can recover from programmatically. It needs stable identifiers, explicit permissions, bounded results, and a retry mechanism when the results need improvement.
Most generally, it needs a higher-level primitive that moves the task forward.
That creates a new engineering surface: agent-native product design.
Your existing API is not automatically an agent interface
The fastest way to ship an MCP server is to put a tool around every API endpoint. It is also a reliable way to make an agent waste context.
Datadog learned this while building its MCP server. Its first version was a thin wrapper around existing APIs. In real investigations, agents filled their context windows with logs, retrieved unexpectedly large records, and tried to infer trends from raw samples.
LLMs struggle with accurate tool calling. It turned out, it takes a lot of effort to build and maintain a MCP server for agent use.
The redesign followed a different question:
What does the agent need in order to take the next useful reasoning step?
That question produces a very different tool surface.
Suppose an observability platform exposes these APIs:
GET /logs
GET /spans
GET /deployments
GET /services
GET /incidents
GET /monitors
Those endpoints may be excellent building blocks for a web application. An incident-investigation agent is more likely to need operations like these:
find_changes(service, time_window)
get_error_path(trace_id)
compare_before_after(service, deployment_id)
get_related_evidence(entity, time_window)
The second interface lets the server perform joins, filtering, pagination, ranking, and aggregation before the result consumes model context.
Anthropic's guidance for agent tools reaches the same conclusion from the model side: build a small number of distinct tools, give each one an unambiguous purpose, return high-signal information, and make error responses actionable.
To put it in a sentence:
APIs were designed to return data, Tool calls and their responses are a conversation.
Context efficiency is product quality
For an agent-facing API, verbosity has a real cost.
An agent must spend context on four things at once:
- Tool definitions
- Tool inputs
- Tool results
- The reasoning needed to finish the task
Datadog changed its logs tooling in several practical ways. It trimmed rarely used fields, chose CSV over JSON for brevity, paginated by tokens instead of record count, and gave agents query capabilities instead of forcing them to retrieve raw data.
They report that some tools can now fit about five times as many records in the same token budget.
The same principle applies to tool inputs. In Datadog's Cloud SIEM workflow, a bulk-triage tool originally accepted a list of long signal IDs. The team changed it to accept a query and resolve those IDs on the server.
Progressive disclosure reduced schema token usage by 41% to 47% in one tested configuration.
Cloudflare has taken the idea further with Code Mode. Instead of exposing its enormous API as thousands of MCP tools, its server exposes two primitives: search() and execute().
The agent discovers the relevant typed API and composes calls in code. Cloudflare measured about 1,000 tokens of fixed tool context, compared with 1.17 million tokens for the equivalent naive MCP surface.
These examples point to a useful rule:
Do not expose your database or API taxonomy to the agent. Expose the smallest set of primitives from which it can reliably complete real tasks.
The best agent-facing product may not have the most tools. It may have the least context per successful outcome.
Case study in the Observability space
The shift is already visible.
Datadog exposes logs, traces, metrics, monitors, incidents, and infrastructure context through its MCP server.
Grafana offers a hosted Cloud MCP endpoint with user-scoped OAuth access to metrics, logs, traces, dashboards, alerts, and incidents.
Tempo actually serves TraceQL documentation in a MCP server, so an agent can retrieve current query guidance instead of relying on training data.
The more interesting opportunity, however, sits below the protocol layer.
Most observability systems were optimized for interactive human queries. A person opens a dashboard, changes a filter, waits for a graph, drills into a trace, and then opens related logs.
An agent behaves more like an automated investigator:
alert
-> affected service
-> recent change
-> anomalous traces
-> relevant logs
-> dependency
-> evidence for or against a hypothesis
That access pattern suggests different primitives and perhaps different storage.
Deductive has proposed organizing observability data around an investigation context: an entity, a time range, related signals, and dependency edges. Instead of making an agent issue separate reads across metric, log, trace, deployment, and topology stores, the backend could co-locate the data commonly needed for one investigation.
There is also a counterintuitive compression opportunity. Interactive databases prioritize decompression speed because a human is waiting for each query. In an agent loop, a storage read may be followed by 10s of seconds of model inference.
Loosening the latency requirements allows us to use more sophisticated compression algorithms, reducing storage requirements manyfold.
MCP exposes capabilities
The Model Context Protocol is easiest to understand without the AI vocabulary. It lets an application discover and invoke capabilities exposed by another process or service.
An MCP server can expose three core primitives:
- Tools: operations the model can invoke
- Resources: addressable context such as files, schemas, or records
- Prompts: reusable templates or workflows
This architecture has a clear philosophy:
MCP exposes capabilities. The intelligence usually remains on the caller side.
That makes MCP a natural boundary when your product is a tool or data source that many different agents should be able to compose.
The 2026-07-28 MCP specification made this boundary easier to operate at scale. It removed the initialize handshake and protocol-level session identifier. Each request now carries its protocol version, client information, and capabilities. Optional discovery happens through server/discover, while application state can still be represented explicitly through ordinary tool arguments or state handles.
For HTTP deployments, Mcp-Method and Mcp-Name headers expose the operation to gateways without requiring them to parse the JSON-RPC body. That gives infrastructure a clean place to implement per-tool authorization, quotas, metering, routing, and rate limits.
Agent
-> MCP call: delete_monitor
-> gateway: authenticate, authorize, meter, audit
-> MCP server
-> product API
The protocol does not make a dangerous operation safe by itself. A production MCP surface still needs least-privilege credentials, explicit scopes, input validation, bounded outputs, approval gates for destructive actions, idempotency, and audit trails.
MCP standardizes the connection. You still own the trust boundary.
A2A exposes responsibility
Agent2Agent, or A2A, solves a different problem.
Suppose the valuable thing you provide is not a set of deterministic operations. It is a specialist capable of owning work.
You may have built an incident-investigation agent with its own model, memory, prompts, tools, search strategy, and evaluation system. A caller should not need to understand those internals. It should be able to delegate an outcome:
Investigate the checkout latency regression after today's deployment.
An A2A service publishes an Agent Card describing its capabilities, supported interfaces, skills, and security requirements. The standard discovery location is /.well-known/agent-card.json, although registries and direct configuration are also possible. A2A v1.0 supports signed Agent Cards so clients can verify that capability metadata came from the claimed provider.
Substantial work is represented as a Task. Tasks have a lifecycle, emit status updates, and produce artifacts. Callers can follow long-running work through streams, polling, or push notifications without needing access to the remote agent's private reasoning, memory, or internal tools.
The philosophy is almost the inverse of a tool call:
MCP: "Give me the tools. I will own the workflow."
A2A: "Here is the job. You own the workflow."
A2A v1.0 is now the latest released specification, and the Linux Foundation reported in April 2026 that more than 150 organizations supported the project.
MCP and A2A belong at different boundaries
MCP and A2A are not competing answers to the same question. They expose different levels of abstraction.
A useful production architecture will often use both:
General SRE Agent
/ | \
MCP MCP A2A
| | |
Telemetry Deployment Database Specialist
tools tools Agent
|
MCP
|
DB metrics and runbooks
The general agent calls tools directly for straightforward operations. When it encounters a database problem requiring deeper expertise, it delegates the outcome to a database specialist over A2A. That specialist may use several MCP servers internally.
MCP turns software into tools. A2A turns software into coworkers.
Further reading
- Postman: 2025 State of the API Report
- Anthropic: Writing effective tools for agents
- Datadog: Designing MCP tools for agents
- Datadog: Building agentic Cloud SIEM workflows with MCP
- Cloudflare: Code Mode gives agents an entire API in 1,000 tokens
- Model Context Protocol: The 2026-07-28 specification
- A2A Protocol v1.0 specification
- Grafana Cloud MCP server documentation
- Deductive: Observability storage for the agentic era