Best practice 6

Design agent interfaces around user tasks, not raw endpoints

Practicepro·con

• An agent interfaceInterfaceA component added to an agent's harness so it can reach a tool, data source, or action outside the model, for example an MCP server, a skill, or a plugin. An interface runs code and acts for the user, so it is where much of the risk enters, which is why interfaces are registered and vetted (see Register, vet, and manage agent interfaces). works best when it is built around the tasks a user wants to complete.4·0
  For

  • Writing effective tools for agents (2025) tools built for high-impact workflows
  • Model Context Protocol specification the interface substrate
  • ELIXIR AI strategy (2026) §6 adopt and adapt MCP and agentic frameworks as external standards
  • The GenAI Divide (2025) Executive Summary, pg. 3; §5.1, pg. 15
  AgainstNone recorded
• Simply passing on pre-existing endpoints ("wrapping") is fast but often does not respect agent patterns.1·0
  For

  • Writing effective tools for agents (2025) tools that merely wrap existing endpoints
  AgainstNone recorded
• Wrapping an API one call at a time forces the agentAgentA system built around a language model that carries out multi-step work: it plans, calls tools, reads the results, and decides what to do next. The model supplies the reasoning; the surrounding harness does the acting. Distinct from a chat model that answers one prompt at a time. to assemble each task itself, which is slow, costly, and error-prone.2·0
  For

  • Code execution with MCP (2025) token cost of per-endpoint tool use
  • Advanced tool use (2025) tool-surface size vs accuracy
  AgainstNone recorded

For practitionersFor providersFor governance

If a routine task takes many awkward steps, report it. Providers shape interfaces around real use from this kind of feedback, and your cases are the evidence they need.

Start from the tasks users do, not the endpoints you already have. Shape operations so a common goal takes as few calls as possible, and watch for ones that trigger many small calls. Learn what your users want; it may be different from your assumptions.

Interfaces built around user tasks cut load and cost, and work more reliably. Governance is barely involved directly, but it is worth supporting and funding the user research that makes this possible.

Reasons

An API for programmers exposes small operations that a developer combines by hand. An agent given the same operations has to work out how to combine them for every task. That means many small calls, more server load and cost, and more chances to go wrong. Vendor engineering guidance reports the same failure mode: tools that merely wrap existing endpoints perform worse than a few tools built for high-impact workflows, and a large, fine-grained tool surface measurably raises token cost and lowers the agent's accuracy at picking the right call. An interface built around real tasks (the questions users ask, the analyses they run) lets the agent reach the goal in a few calls. There is more than one way to get there: shaping task-level tools is one, and for very large APIs, letting the agent write code against the endpoints (progressive disclosure, code execution) is another. Both need to know what users are trying to do, and providers often do not, so learning the real use cases is part of the job.

Examples

• A provider exposes its API one endpoint per tool; to answer one common question the agent makes dozens of small calls, hits rate limits, and stitches the pieces together wrong.
• The provider replaces those with a single operation shaped around the question users actually ask, and the same task now takes one call.
• Watching real usage, a provider finds users mostly want a comparison the API never offered directly, adds a task-level tool for it, and drops an assumption about what people wanted that turned out to be wrong.
• A spike of many tiny calls aimed at one goal flags an interface that is misaligned with how it is used, and prompts a redesign.
• For a very large API, instead of hand-building a task tool for every workflow, the provider lets the agent write code against the endpoints (progressive disclosure and code execution).

Sources

• ELIXIR TF Agentic AI: agenda and rolling best practice (2026), Best Practice item 4, and the July 2026 discussion on providers' limited view of their users.
• Anthropic, Writing effective tools for agents (2025). Wrapping existing endpoints is a common error; build a few tools for high-impact workflows. Vendor-primary grounding for this practice.
• Anthropic, Code execution with MCP (2025) and Advanced tool use (2025). Quantify the token cost of per-endpoint tool use and the accuracy loss from a large tool surface; document progressive disclosure as the alternative remedy.
• Model Context Protocol specification. The interface substrate the practice is about.
• MIT Project NANDA, The GenAI Divide (2025). Enterprise field evidence that tools fail on workflow fit rather than model quality: custom systems stall due to "brittle workflows ... and misalignment with day-to-day operations", and buyers want a "deep understanding of our workflow" (pg. 3, pg. 15). Out-of-domain business report; cited as external context.

Change history

• 2026-07-27: Added The GenAI Divide (MIT NANDA 2025) as a supporting source on workflow fit (bp6-a1).
• 2026-07-27: Renumbered from BP05 to BP06 on inserting the new BP01 (match the method to the task).
• 2026-07-27: Rewrote Examples as concrete scenarios (actor, action, outcome), including an anti-pattern, replacing restatements of the practice.
• 2026-07-26: Rewritten to add vendor-primary grounding (the Anthropic tool-design guidance, with quantified evidence) and to note the two accepted remedies to endpoint-wrapping (task-level tools and code execution for very large APIs). "Providers don't know their users" kept as stated judgement.
• 2026-07-25: Created from the ELIXIR TF distillation (hooks 5, 12).

Discussion