12 Treat the agent as a real interface user

An agent-facing interface has users with limited attention, incomplete knowledge, and predictable ways of making mistakes. Those users are not human, but the design questions remain recognizable. Can they discover the right operation? Can they understand what it does? Does the response tell them how to recover? Can they distinguish a successful action from a merely valid call?

Puma treats these questions as central to the stack because agents are intended to consume and build the software. An API that is technically available but difficult for an agent to use is a product problem, not merely a prompting problem.

Examine the whole interaction

The interface includes more than the tool schema. It includes names, descriptions, available examples, discovery mechanisms, error messages, execution latency, and the state visible after an operation.

Suppose an agent must find a model, inspect its requirements, choose a runtime, acquire artifacts, wait for readiness, and request inference. If each step returns ambiguous identifiers or hides the next valid action, the agent must reconstruct the protocol from scattered clues. A large context window does not make that reconstruction reliable or cheap.

Observe a real interaction. Where does the agent guess? Where does it repeat a call because the response was unclear? Where does it retrieve an entire catalog to answer one question? Those observations suggest specific interface changes. “Make the tools better” does not.

SWE-agent's experiments provide bounded evidence that tools and feedback can affect issue-resolution performance with a model held fixed. They support treating the interaction as a design variable. They do not establish one permanently optimal tool set for all models or repositories. SWE-agent.

Make mistakes informative

A schema error can be a useful teaching moment if it identifies the invalid field, the expected form, and the relevant constraint. A generic rejection may force the agent to try several guesses.

Do not make an error response silently grant authority or recommend an unsafe action. Its job is to explain the boundary. If the requested operation is not allowed on the current revision, say which precondition failed. If a capability is absent, distinguish absence from a temporary failure. If the outcome is uncertain, provide a way to inspect the authoritative state.

The response should match the caller's decision. An internal stack trace may help a maintainer but overwhelm an agent trying to determine whether retry is valid. Structured failure data and a concise explanation can serve both, with deeper diagnostics available when needed.

Prefer a demonstrated improvement to a new layer

An agent-first system does not automatically need a dedicated protocol for every action. Armin Ronacher's practical recommendations emphasize fast feedback, useful errors and logs, and application permission checks near the relevant operation. He often favors existing shell or database tools before adding MCP machinery. This is a first-person account, not a universal ranking, but it challenges the assumption that a new agent interface is inherently more usable. Agentic Coding Recommendations.

For the resource example, a reliable command that returns stable identity and readiness information may be enough. A domain operation becomes valuable when it removes recurring choreography, centralizes a real invariant, or makes recovery understandable. The new layer should earn its cost through those effects.

Evaluate outcomes rather than presentation alone

A smaller catalog can reduce information load while making discovery harder. A compact response can omit a field needed for safe recovery. A friendly description can conceal a consequential default.

Compare interfaces on the same tasks. Record whether the agent achieved the intended result, made an invalid or unauthorized attempt, recovered from a failure, and required human intervention. Count calls, latency, and information volume as explanatory measures, not substitutes for success.

For an exercise, give an agent a task using an unfamiliar tool. Preserve the interaction. Identify one point where it lacked information needed for a decision. Change the interface or discovery path, then try a comparable task. A single improvement is not a general benchmark, but it can establish a concrete defect and a plausible repair.

The objective is not to prevent every mistake through longer instructions. It is to make the system's important distinctions discoverable, its operations understandable, and its failures recoverable.