Tool count becomes a selection problem
Thirty-two endpoints become thirty-two competing definitions. Tool choice degrades long before the API runs out of routes.
A practical field guide
Endpoints are not tools.
OpenAPI describes programmer operations. An agent needs a smaller, clearer set of capabilities it can select, explain, and safely execute.
The API-to-MCP translation layer, explained
capability compiler
API operationPOST /orders
→
Agent capabilityplace_order
API operationGET /orders/{id}
→
Agent capabilitytrack_order
API operationPOST /payments
→
Agent capabilityconfirm_payment
Context cost ↓ 72%
Decision intent ↑ explicit
Shape the surface•Guide the decision•Constrain the response•Govern execution•Shape the surface•Guide the decision•Constrain the response•Govern execution•
01 / The mismatch
A direct conversion creates a menu, not an assistant.
The model is asked to infer the right task, compose a route chain, hold opaque identifiers, and understand the risk. None of that lives in an endpoint definition.
The abstraction is too low
A customer asks to order dinner; the agent receives POST /cart/items, then a chain of stateful calls.
Route names do not communicate intent
getOrderTracking says what a programmer can call, not when an agent should reach for it.
The docs were written for a human in context
Agents need examples, exclusions, guardrails, and a decision boundary in the tool itself.
02 / Tool anatomy
A useful tool starts with a human-sized outcome.
Keep raw API primitives in the system. Publish an agent surface that speaks in tasks, carries a response contract, and has a clear policy boundary.
From route semanticsTo capability semantics
operationIdgetOrderTrackingparametersorder_id: stringresponsefull_order_payload
→
tooltrack_and_resolve_orderuse whenCustomer needs order statusreturnsstatus, ETA, next_best_action
Agent context budget / curated surface
8 task-level tools → high-confidence selection
The response is the context bill
Every field has to earn its place.
Responses should help the next decision, not recreate the backend payload inside the conversation.
- 01Allowlist fields for the stated task.
- 02Return summaries before details.
- 03Carry readable labels alongside IDs.
03 / Publishing strategy
Curate first. Expand with evidence.
Not every API deserves the same presentation. Pick the serving model from the task shape, operation volume, and risk of getting it wrong.
A / Flat
Curated 1:1
A small, transparent surface for simple domains.
Best when the API already maps cleanly to agent intent.
B / Facade
Capability facades
Bundle route sequences behind a task-level outcome.
Best when workflow orchestration belongs server-side.
C / Default
Intent compiler
Publish 5–8 governed task tools; compile primitives beneath them.
Best for consequential workflows and a clear evaluation surface.
D / Long tail
Dynamic discovery
Search, describe, then invoke curated primitives on demand.
Best for large catalogs that must not tax every turn.
04 / Layer the answer
A good MCP surface is deliberately uneven.
Put common jobs on the shortest, safest path. Let the unusual work reveal more capability only when it needs it.
Layer 01
Default5–8 tools
Default
Compiled intents
Task-level tools such as place_order and track_and_resolve. Testable, reviewable, governable.
Layer 02
Long tailOn demand
Long tail
Dynamic discovery
Search, describe, and invoke surfaces expose the uncommon catalog without expanding every conversation.
Layer 03
Escape hatchOptional
Escape hatch
Transparent primitives
A flat curated mode gives architects a direct view when trust and diagnostics require it.
05 / Build sequence
More than tools: a complete interface for agent work.
Tools
Actions with consequences, shaped around a result.
Resources
Reference data and raw evidence, retrieved deliberately.
Prompts
Reusable workflows that make the right process visible.
Elicitation
Human confirmation exactly where risk enters the flow.
The operating principle
Do not expose your API to an agent. Design its capabilities.
The difference is task fit, predictable context, and a policy boundary that can be understood by people as well as models.
Back to the model