Designing APIs for AI Agents as First-Class Citizens

For as long as we’ve been building web APIs, we’ve designed them for two kinds of users. Humans clicking through a website and developers designing connected systems.

A third user has arrived, and it’s on a fast track to becoming number one. AI agents use APIs to get real work done, and their needs are quite different from a website or a developer.

Almost nobody designs for this yet. Most teams expose the same REST endpoints and JSON payloads they always have, wrap them in an MCP server, and assume the agent will cope. It does cope, but does so inefficiently. Financially, not to mention environmentally.

As I’ve been working on the APIs for VIA (our AI-native product platform), used by our agents to get most of their work done, I went looking for what it means to design them agent-first.

Here’s what I’ve learned so far, and how it’s shaping the design of VIA’s APIs.

The Context Window Is Your Real Budget

#

By comparison, humans effectively have unlimited working memory and screens to filter noise. Agents have neither. Everything they know about our APIs, tool definitions, schemas and response payloads, has to fit inside their context window, and that window is a hard budget.

Most agents are stateless between steps. For every reasoning step, the entire conversation, including active tool schemas and intermediate results, gets retransmitted to the model.

This makes token efficiency matter more than you think.
It isn’t just a cost line item; it’s affecting the agent’s reasoning ability.

Research into token consumption shows a single ten-step task quickly burns 50,000 to 100,000 tokens, which is compounded by re-sending verbose tool descriptions and intermediate data.

In traditional distributed systems, over-fetching data costs a few milliseconds of network latency. In agentic systems, over-fetching burns tokens on every subsequent step and pollutes the context the agent has to reason over.

This shift from ‘over-fetching is a latency problem’ to a compounding cognitive tax should guide the design decisions we make on our APIs.

1. Discover Capabilities, Don’t Dump Them

#

Default MCP clients load every tool definition into the context window up front. At small scale that’s fine. Connect a dozen servers exposing a few hundred tools and the context is flooded with schemas before the agent has read a single word of the user’s request.

One benchmark put static loading of 60 tools at roughly 47,000 tokens spent before any reasoning begins. The same capabilities exposed through dynamic discovery cost about 400 tokens. That’s a significant reduction for identical work.

It gets worse, because most definitions are of low quality. An academic study of 856 tools across 103 MCP servers found that 97% of tool descriptions carried at least one structural or semantic defect, and 56% failed to state their core purpose clearly.

Agents lean entirely on the natural-language semantics to pick the right tool and map arguments. Vague descriptions mean wrong tool selection, hallucinated arguments and unnecessary retries. Each retry pays the token toll again.

You can’t just write more verbose descriptions to fix that: the same study found that richer descriptions lifted task success by a median of 5 points but inflated step counts by 67% and actively regressed in 16% of cases.

The lesson is to keep capabilities out of the context until they’re needed. Represent them as files an agent can scan on demand. A skill’s frontmatter costs a few dozen tokens to read, and the full instructions only load if the task calls for them.

The takeaway: Don’t hand the agent your whole toolbox. Let it reach for them one at a time.

2. Let Agents Run Code, Not Carry Data

#

In a normal tool-calling loop, every result the agent fetches is appended to its context, whether it needs to read that data or not.

Take a common task: pull a meeting transcript from cloud storage and attach it to a CRM record.

With standard tools, the agent loads the transcript into its context (thousands of tokens), then passes that same transcript back out in the next tool call. The model never needed to read a word of it, but it paid for every token twice and got a chance to corrupt the data in between.

The alternative is to let the agent use a custom tool that pipes the data directly from one system to the other, on the host, without the payload ever entering the model’s context.

The capability is just a typed function on disk; the agent reads its signature and runs it. One benchmark of complex multi-tool workflows saw the context overhead drop from 150,000 tokens to 2,000. A 98% saving by moving away from standard tools to fit-for-purpose tools.

There’s a second payoff here that matters more in my world than tokens: privacy.

If sensitive content never enters the model’s context, it was never exposed to the model or its provider. For a platform handling regulated data, “the data never touched the LLM” is a far stronger position than “we have a retention agreement.”

In today’s world, how hard is it to have a coding agent build such tools for you?
Additional benefits? Execution is deterministic and can be audited.

The takeaway: Where possible, move data between systems with code. Reserve the context window for decisions and orchestration, not data transport.

3. Use Semantic over Generic Endpoints

#

REST gives an agent generic verbs against server-defined resources, a poor fit for how agents reason. Query a typical REST endpoint and you get a monolithic object with timestamps, nested IDs, relational links, and metadata, almost none of which the agent needs for its task.

The agent spends reasoning capacity filtering signal from noise, burning tokens for the entire payload. Go the other way and fetch narrowly, and you hit the n+1 problem, with each extra call burning tokens again. In a stateless agent loop, this compounds fast.

GraphQL fits agents better, because it hands control of the response shape to the caller. The agent asks for exactly the fields it needs (a user’s name, not the entire account object) and traverses related entities in a single request instead of a sequence of round-trips.

The strong typing acts as a guardrail reducing schema mistakes and the retries they cause.

IBM researchers built a benchmark for sequential function calling and found that giving the model a GraphQL schema as source of truth for response structure measurably improved its ability to chain interdependent calls, where REST and OpenAPI specs fell short.

The query structure lines up with what these models are already good at: generating code.

You can tighten it further on the server: aliases to rename obscure legacy fields into clear domain terms, hard-coded arguments to hide parameters the agent shouldn’t set and concise inline comments instead of sprawling auto-generated docs.

The takeaway: Give agents a sharp semantic graph they can query precisely, not generic endpoints that force them to over-fetch and re-assemble.

4. Make the Schema Searchable

#

GraphQL has its own scaling trap. The standard introspection query returns the entire schema, and enterprise schemas quickly grow to thousands of fields and types. Having an agent ingest the whole graph on every turn defeats the purpose.

The emerging answer is what the GraphQL AI working group calls semantic introspection.

Instead of downloading the schema, the agent issues a natural-language search (“how do I find a user by email?”) and the server returns only the relevant coordinates: the matched types and the path from the root query to them, backed by a vector or BM25 index over the schema.

Discover, then resolve, with token cost bound to what the task actually needs.

The cost difference at discovery time is significant:

Discovering against an OpenAPI spec burns more than ten times the tokens of semantic introspection, at over four times the dollar cost. Same domain, same task.

The difference is purely how the agent finds what it needs.

The takeaway: Let agents search your schema in natural language and get back just the relevant slice. Don’t make them download the library to find one book.

5. Match the Wire Format to the Data

#

JSON won the web, but it’s a poor fit for an LLM’s context window. Every brace, bracket, quote, and repeated key is tokens spent on structure rather than meaning. The syntax is also brittle for models to generate: one missing comma invalidates a payload and triggers a retry.

Switching the serialization the agent actually sees buys real headroom. YAML trades brackets and quotes for indentation and typically cuts 10–25% of tokens for the same data.

For flat, uniform data (lists of records, telemetry, tabular results), declaring the fields once in a header and then streaming rows (the idea behind formats like TOON and LEAN) goes further:

The striking part isn’t only the ~47% token cut. Accuracy went up, not down, because the model’s attention isn’t spent parsing repetitive structural noise.

The caveat: tabular formats lose their edge as data gets deeply nested and mixed. So the right move is content-aware serialization: lean tabular formats for flat arrays, YAML for nested structures. Not one format everywhere.

The takeaway: Pick the wire format for the use case. JSON for machines talking to machines; something leaner for your agents.

How This Adds Up for VIA

#

Put together, these aren’t five separate tactics. They’re one stance: design the API for the agent’s constraints, not the human’s habits.

For VIA, that means a strongly typed semantic graph as the agentic data layer with semantic search over that schema for discovery. Custom tools for orchestration and more complex tasks, and content-aware serialization on the wire.

The agents load almost nothing up front, find capabilities by searching, fetch exactly the fields they need, and move data between systems without routing it through their own context.

Let me be clear about what this is: a design direction grounded in current research and benchmarks, not a production system with a year of telemetry behind it. The numbers above come from published studies, not from VIA’s own production statistics.

That part comes next, and I’ll write about what holds up. But the direction is firm. The teams still wrapping REST APIs in MCP servers and calling it agent-ready are optimizing for the wrong user.

Agents are becoming the primary consumers of our APIs. They deserve to be designed for as first-class citizens. Not retrofitted as an afterthought.

The Full Analysis

#

This post covers the principles. The complete analysis (including token economics, research base, benchmarks and an architectural blueprint) is available in the full report.

Download the full VIA Research report (PDF)

A Q2 2026 publication by VIA Research — Swiss engineering, AI-native with Human Insight.