Definition. For AI agents as API callers, GraphQL reduces token cost via field selection while REST's fixed endpoints are easier for a model to select correctly from a tool list — the right choice depends on which failure mode matters more.
The caller changed, so the trade-offs changed
REST vs GraphQL debates were shaped by human developers writing client code once and reusing it. An AI agent calling an API is a different caller: it selects an endpoint or constructs a query fresh, from a schema, on every relevant step, informed by natural-language reasoning about intent rather than compiled client code. That shift changes which trade-offs actually matter.
Where REST wins for agents
REST's fixed endpoint shapes are easier for a model to select correctly, because the decision is closer to picking the right item from a list than constructing new syntax. A well-documented REST API with clear per-endpoint descriptions maps naturally onto tool-calling interfaces, which is why most agent frameworks default to representing REST endpoints as discrete callable tools.
Where GraphQL wins for agents
GraphQL's field-selection means an agent only pulls the data it actually needs for the current step, which reduces both token cost and the chance the model gets confused by irrelevant fields in a large response. A single GraphQL endpoint with a rich schema can also collapse what would be many REST endpoints into one queryable surface, reducing the raw tool count an agent has to choose between.
The failure modes each introduces
- REST: a large endpoint surface becomes a long, flat tool list, and selection accuracy degrades as that list grows.
- GraphQL: the agent must construct syntactically correct queries against the schema, which introduces a query-construction failure mode REST doesn't have.
Compare: REST vs GraphQL for agent tool calling
| REST | GraphQL | |
|---|---|---|
| Selection model | Pick from a list of fixed endpoints | Construct a query against a schema |
| Token efficiency | Lower — fixed response shape | Higher — only requested fields returned |
| Failure mode | Wrong endpoint selected | Malformed query syntax |
| Scales well past 20+ operations | No — tool list grows flat and long | Yes — one schema, many query shapes |
Frequently asked questions
Is GraphQL always better for AI agents because it saves tokens?
Not always — correct query construction is a second failure mode REST doesn't have. For simple lookups, REST's predictability often wins.
How does tool count affect the REST vs GraphQL decision?
A large REST surface becomes a long flat tool list that degrades selection accuracy. One GraphQL endpoint can serve many query shapes, reducing discrete tool count.
Do agents need different API documentation than human developers?
Yes — schema clarity, consistent naming, and explicit examples in the machine-readable spec matter more than prose a human would skim.