Choose the right tool surface

Coding agents work best when the systems around them offer clear operations. That operation may come from a command-line program, a web API, or an MCP server. The names sound more complicated than the underlying choice.

Three ways an agent can use a tool

These are not maturity levels. MCP is not automatically better than a CLI, and a CLI is not a crude version of an API. They are interfaces for different jobs, and the decision is an old one: ship a library, expose a service, or adopt the shared protocol. The new part is that the caller is an agent.

Start with the interface that already works

A CLI is often the best default for repository work. The agent can read --help, pass explicit flags, pipe output to another command, inspect an exit code, and show you exactly what it ran:

vault-doctor --root ./notes --json

An API is useful when the source of truth lives in a service. Put the request behind a small script or CLI when you will repeat it. That wrapper can handle authentication, pagination, retries, and response validation once instead of asking the agent to improvise them in every session:

customer-lookup cus_123 --json

MCP is useful when the agent host should discover a shared set of operations and context directly, such as searching a knowledge base or creating an issue in a signed-in service. It can remove one-off connection code. It does not remove the need to understand permissions, side effects, or the quality of the underlying API.

A practical decision order

1. Is there already a reliable CLI? Let the agent use it.
2. Does the service expose an API? Call it directly or wrap the repeated calls in a small CLI.
3. Would MCP improve discovery, shared authentication, or reuse across agent workflows? Add it for that reason, not for the label.
4. Is the only route a visual interface? Browser control can be valid, but expect it to be slower and more sensitive to layout changes.

Before asking an agent to click through a screen, ask whether the product already has a CLI or API. Agents use those interfaces natively, and the record of inputs and outputs makes the work easier to inspect.

Keep judgment outside the mechanism

The interface should do the exact operation well. The agent should decide how that operation serves the larger goal.

For example, a release-notes --since v2.1 --json command can return every relevant change deterministically. The agent can then group the changes, decide what readers need, and draft the prose. Code supplies dependable facts; the agent supplies selection, orchestration, and explanation.

Try it

Try it with your agent

For this task, inspect the available tool surfaces before choosing an
approach. Look for an existing CLI first, then a documented API, then an MCP
connection that offers a clear advantage. Explain the choice in plain
language, including authentication, cost, side effects, and how we will verify
the result. If we will repeat several API calls, propose a small CLI wrapper
with structured output instead of rebuilding the requests in each session.

Watch out

• MCP by reflex: adding a server creates configuration and permission surface. Use it when the shared agent connection is the benefit.
• Raw API improvisation: repeated hand-built requests invite inconsistent pagination, error handling, and field names. Wrap the stable operation.
• UI-first automation: clicking is sometimes necessary, but it should not be the default when a documented, inspectable interface already exists.
• Hidden authority: any surface that can publish, send, charge, or delete needs an explicit human gate (AF-09).