GraphQL vs REST for AI agents: which API style holds up under tool calling

You're designing an API — or extending one — and your agents are now first-class consumers. The question lands on someone's desk: GraphQL or REST? Both work. Both have serious production deployments behind agents in 2026. But they fail differently under tool calling, and the failure modes matter more than the feature lists.

This piece is for platform engineers and Heads of AI weighing the two for agent-facing surfaces. Short version: REST wins for most agent tool-calling scenarios today because the ecosystem — OpenAPI, tool schemas, per-endpoint auth, per-endpoint rate limits — aligns with how foundation models actually invoke tools. GraphQL wins when a single agent call needs to compose data across many related resources and you control both ends of the pipe. The rest is trade-offs.

How REST works for agents

REST exposes resources through HTTP verbs against URLs. GET /customers/123, POST /invoices, PATCH /subscriptions/abc. Each endpoint has a fixed contract: parameters, request shape, response shape, status codes. Agents consume it the way developers do — one endpoint, one call, one response — except the caller reasoning about which endpoint to hit is a language model, not a human.

The ecosystem is what makes REST fit agent tool calling so cleanly. An OpenAPI spec describes each endpoint as a discrete operation with typed inputs and outputs. That maps almost one-to-one to the tool schema format that OpenAI, Anthropic, and Google use for tool calling — each requires a name, description, and a JSON Schema for parameters, though the field names differ across providers (Anthropic's input_schema vs OpenAI's parameters, for example). Generators can walk an OpenAPI spec and produce tools an agent can invoke immediately. Per-endpoint auth scopes, per-endpoint rate limits, per-endpoint observability all work the way they did before agents existed. Nothing about the runtime shape is new.

How GraphQL works for agents

GraphQL exposes a single endpoint — usually /graphql — and a typed schema describing every field, type, and relationship the API can serve. Clients send a query specifying exactly the fields they want, across whatever nested resources they need, and get back a response shaped precisely to that query. One round-trip, no over-fetching, no under-fetching.

For agents, this looks appealing at first. An agent needing a customer's recent invoices, the associated subscription, and the primary contact would need three REST calls; in GraphQL it's one query. The schema itself is introspectable, so in theory an agent can discover the surface at runtime. In practice, that introspection surface is enormous — a mid-size GraphQL schema has hundreds of types and thousands of fields — and the reasoning problem shifts from "which endpoint do I call" to "which fields do I select, at what depth, with which arguments." That's a harder problem for models, not an easier one. Query complexity, depth limits, and cost analysis (see GitHub's approach) all become runtime concerns the agent has to reason about — or the runtime has to enforce for it.

Comparison

When to choose REST

Pick REST when your agents are calling third-party or partner APIs, when your consumers include foundation model tool-calling loops as a primary case, and when you want the standard HTTP tooling — gateways, rate limiters, WAFs, per-endpoint observability — to keep working without a custom layer on top.

REST is also the right choice when you're generating tools from an existing API surface. The mapping is direct: an OpenAPI operation becomes a tool, its parameters become the tool's schema, its response becomes the tool's return type. Agents reason about "which tool" the same way they reason about "which function" — a bounded, named choice with a typed contract. This is why every major agent framework has first-class OpenAPI support and why most agent-ready SaaS APIs published in the last two years are REST. For a deeper look at REST design specifically for agent callers, see our REST API design best practices for the agent era.

One more case for REST: when per-user authorisation and audit are non-negotiable. REST's per-endpoint scope model maps cleanly to OAuth 2.1 scopes, and the audit trail is per-call, per-endpoint, per-user. GraphQL can do this — but the field-level authorisation surface is harder to reason about, and most production GraphQL servers still enforce coarser-grained rules. If your security review is going to ask "who called what, when, as whom," REST gives you the cleaner answer.

When to choose GraphQL

Pick GraphQL when the agent's job involves composing data across many related resources in a single interaction, when you control both the API and the agent, and when you're willing to invest in a query layer that treats agents as sophisticated clients rather than tool callers.

A good example: an internal agent that answers questions about a customer's entire relationship — subscription state, recent invoices, open support tickets, contract terms, product usage. In REST that's five or six calls, each with its own latency and failure mode. In GraphQL it's one query, shaped by the agent's actual need. Latency is lower, over-fetching is zero, and the agent's reasoning gets simpler because it's assembling one response, not orchestrating six.

GraphQL also fits when your existing product is already GraphQL-first — Shopify and Linear expose GraphQL as the primary (or only) API, and GitHub offers a first-class GraphQL API alongside REST — and building a parallel REST surface for agents would double your maintenance burden. In that case, invest in GraphQL-to-tool generation, operation whitelisting for agents, and per-operation observability. Don't try to make agents introspect the raw schema; pre-define the operations they can invoke, treat each operation as a named tool, and you get most of GraphQL's composition benefits with most of REST's tool-calling ergonomics.

How Pontil fits

The REST-vs-GraphQL question is really a question about which API surface your agents can actually reach. That's the gap most SaaS teams hit: their product does far more than the API exposes, and the agent project stalls not because the model can't reason but because the surface isn't there.

Pontil is a Tools-as-a-Service platform. We generate agent tools directly from the codebases and API surfaces you already have — REST, GraphQL, or a mix — and run them through a managed runtime that executes as the authenticated user. The API-style debate matters less when you're generating tools from what already exists: whichever surface you have, the tools compose the same way at the agent layer, with the same auth, observability, and maintenance discipline. If you want the deeper argument for why the tools layer is where agent projects actually get unstuck, our product page covers it in more depth.

What we'd choose

For most agent-facing surfaces in 2026: REST. The tool-calling ecosystem is built around it, per-endpoint auth and rate limiting align with how foundation model providers actually invoke tools, and the failure modes are legible to agents. If you're starting fresh and your primary consumer is an agent, REST plus a well-maintained OpenAPI spec is the shortest path to something that works.

GraphQL wins on composition-heavy internal agents where you control the whole loop, and it's the right answer when GraphQL is already your product's primary API and doubling to REST would be wasted work. In that case, don't hand the agent your raw schema — pre-define the operations, treat each as a tool, and you get the composition benefits without the reasoning tax. The variable that decides between them isn't preference; it's whether the agent needs to compose across resources in one call, or invoke discrete capabilities in a bounded loop. Answer that first, and the API style follows.