Quick answer: Pasting a large OpenAPI document into an AI editor does not give the model better API knowledge; it burns the context window on schemas the current task never touches, which degrades the quality of the actual change. The better approach is to give the agent targeted, spec-derived tools that expose only the relevant operations, or to provide the minimal slice of the spec for the task at hand. Context is a finite budget, and spending it on an entire contract is the same failure as loading every table in a database when a query needs one row.
The temptation is understandable. A whole spec seems like the most complete context, so a developer drops it into the prompt and asks the agent to build a feature. The model then juggles hundreds of unrelated schemas, and the signal-to-noise ratio drops: it may reference an operation from a different service, miss the one relevant field, or run out of room for the code and reasoning. The fix is not a bigger window; it is curation. Giving the agent the right tools and a narrow contract slice keeps the context focused and the output accurate.
Whole spec versus targeted context
The two approaches differ in what the model actually has to work with.
| Dimension | Whole spec in prompt | Targeted tools / spec slice |
|---|---|---|
| Context usage | High, mostly irrelevant | Low, task-scoped |
| Signal-to-noise | Low | High |
| Wrong-operation risk | Elevated | Reduced |
| Room for reasoning | Crowded | Preserved |
| Maintenance | Re-paste on change | Tools regenerate from spec |
Give the agent tools instead of raw text
An MCP server generated from the spec exposes callable operations, so the model invokes only what it needs and receives structured, validated responses rather than reading a wall of schema text.
# expose only the operations the team's agent actually needs # generated from the OpenAPI spec, not hand-copied into a prompt mcp: spec: ./openapi.yaml operations: - getOrder - listOrders - createOrder - captureOrder # unrelated schemas never enter the context window # the agent calls a tool when it needs data, instead of holding # the entire contract in its working memory
Slice the spec when a tool is overkill
For a one-off task, a minimal bundle containing the relevant paths and component schemas is enough. A bundler can resolve the needed refs into a small document, keeping the context tight while preserving accurate definitions.
# produce a minimal document containing only the needed operations # and the schemas they reference, resolving refs automatically openapi-cli bundle \ --spec ./openapi.yaml \ --paths /v1/orders \ --output /tmp/orders-slice.yaml # the agent receives a small, complete contract instead of the whole API, # so every token in the context is relevant to the task
Keep the source authoritative and the context thin
A local-first workflow keeps the full spec as the source of truth while generating focused tools and slices on demand, so the agent always works from accurate, current definitions without carrying the entire document. As the contract grows, this scales where prompt-pasting does not, and it removes the quality drop that comes from a crowded context. The principle is worth treating as a habit: give the model the smallest complete context that answers the task, not the largest document that happens to be available.
Frequently asked questions
Won't a larger context window eventually make this moot?
Bigger windows help with volume but not with focus; irrelevant schemas still add noise and distract the model. Curation remains valuable even when everything technically fits.
How do I know which operations to expose?
Start with the operations the team's workflows actually use, and expand as needed. A focused set that covers the real tasks beats a broad set that invites the agent down irrelevant paths.
Is a spec slice at risk of being stale?
Generate it from the authoritative spec at the time of the task rather than maintaining a hand-written copy, so the slice is always derived from current definitions.
What if the task genuinely spans many services?
Prefer callable tools the agent invokes as needed rather than loading every service's schema up front, so only the operations actually used enter the context.
This is part of the Powerduck vs Cursor comparison — start there for the full decision around AI editors and API contract tools.
Top comments (0)