Tool Call Interface Design for Coding Agent Skills

Coding agents no longer just answer prompts. They plan, call tools, read what comes back, and decide what to do next, often across dozens of steps without a human checking in between. Whether that loop holds together or falls apart has less to do with the underlying model than with the interface sitting between the agent and its tools: how parameters are named, what a return payload looks like, how an error gets phrased. That interface is a discipline in its own right, with its own failure modes and its own evidence base, and it deserves to be treated as such.

Anthropic's 2026 Agentic Coding Trends Report puts a number on the ceiling: developers report fully delegating only 0 to 20% of tasks to an agent. AI is a constant collaborator, not a standalone replacement, and the quality of that collaboration is set almost entirely by interface design. The model generates structured tool calls, nothing more. Everything it can or cannot accomplish downstream of that call is mediated by what the interface exposes, how it's labeled, and what it hands back. Get the interface wrong and the failure rarely looks like a crash. It looks like an agent calling the wrong tool with total confidence, passing a malformed argument, or retrying the same broken action four times because the error message gave it nothing to work with.

What the harness benchmark evidence shows about where performance is won or lost

The clearest evidence that harness design outweighs model choice comes from a string of benchmark results that would look almost implausible if they weren't reproducible. According to Terminal Bench 2.0, the LangChain coding agent moved from 30th to 5th place without touching the underlying model. Terminal Bench records show the same agent improved from 52.8% to 66.5% through harness changes alone.

Princeton's CORE-Bench findings are just as stark: one model scored 42% under one scaffold and 78% under another. Same model, nearly double the outcome, purely as a function of how the surrounding harness structured its inputs and outputs.

Vercel ran an experiment: stripping 80% of the tools available to an agent lifted its success rate from 80% to 100% on the same model. Stripping 80% of the tools available to an agent lifted its success rate from 80% to 100% on the same model. Token usage more than halved. Latency dropped from 724 seconds to 141 seconds. That's not a rounding error, and it isn't a fluke either, it's a signal that tool sprawl actively degrades the planner's ability to choose correctly.

Then there's the cross-harness comparison that ought to unsettle anyone who assumes the first-party tool is automatically the best-tuned one. Terminal Bench 2.0 results show that Letta Code scored 59.1% running Claude Opus 4.5, while Claude Code scored 41.6% on the identical model. A third-party harness outperformed the vendor's own scaffold, on the vendor's own model. The same benchmark data suggests that harness quality can close or reverse gaps between models on real coding tasks.

None of these results say which specific design decision drove the gain. That's the gap this piece is built to close, one interface dimension at a time.

How skill naming and parameter labels shape an agent's ability to plan correctly

A model's planning step runs on token likelihoods, and tool names sit directly inside the prompt that planner reasons over. They are not just identifiers a developer picks for readability. They are semantic signal the model uses to decide what to do next, and sloppy naming corrupts that signal before the agent has done anything wrong.

Consider a skill set with run_command, execute_shell, and shell_exec all present at once. A human engineer glancing at the list understands these probably overlap. The model doesn't get to glance, it has to commit to one, and it will default to whichever name pattern most strongly matches whatever it saw during training, regardless of which one actually fits the current task. That's planner uncertainty manufactured entirely at the naming layer.

The fix is naming discipline: action plus scope, in one phrase. Not a generic verb standing alone, but a name that encodes what's being done, to what, under what constraint. The same logic extends to parameter labels. A parameter simply called path leaves the model guessing: relative or absolute, file or directory. Renaming it repo_relative_file_path makes the ambiguity disappear before the model ever has a chance to misread it.

This becomes more consequential, not less, in multi-agent setups where a planner agent dispatches work to specialist agents. The planner reads tool names to reason about what a specialist can do, not documentation buried three layers down. Work on agent-computer interfaces frames this directly: interface design is central to solving complex tasks, and the challenge is making that interface legible to the agent itself, not just to the person who built it. A workable heuristic follows from that: every tool name should stand on its own, unambiguous, without needing surrounding documentation to disambiguate it.

Parameter structure decisions that keep agents on track across multi-step workflows

Multi-step agentic work is sequential and stateful by nature. An agent edits a file, runs the test suite, reads the failure, and adjusts, and each call in that chain depends on the output of the one before it. Parameter structure is what keeps that chain from snapping.

Flat structures beat deeply nested ones for reliability. Nested objects raise the odds of structural malformation, particularly when the model is generating JSON under context pressure and has to track bracket depth correctly across a long response. It's a small thing until it isn't, and at scale, small things compound.

Required versus optional parameters carries a similar tension. Lean too hard on optional fields and the agent has to infer which combinations even make sense together, which is its own form of ambiguity. Lean too hard the other way and every call becomes needlessly verbose, burning context budget the agent needs for actual reasoning. A parameter typed as an enum of valid branch names closes off invention entirely, since the model has no room to hallucinate a value outside the defined set.

Idempotency affects how well an agent can recover from failure. Agents self-correct largely by retrying, so a tool that produces different side effects when called twice with identical arguments actively punishes the exact recovery behavior you want to encourage.

The clearest illustration of good parameter design in practice comes from S1 research on what's been called the file-system-as-toolbox approach. Exposing a small set of primitives, read_file, grep, find, shell, each with a clear and composable parameter contract, raised the "Intent Met" score from 45% to 75% on novel incidents. That outperformed more specialized tooling that was, on paper, better suited to the task but harder for the model to parameterize correctly. Richer structure can pack more intent into a single call, but every added layer is more surface area for something to break. Simpler contracts trade some efficiency for a lot more reliability.

Return shape design and why what an agent reads back determines whether it can self-correct

Self-correction is the mechanism that makes an agentic loop worth running at all: the agent executes something, reads what comes back, and decides whether to retry, revise, or stop and ask for help. The return shape is the entire input to that decision. Get it wrong and there's no decision to make, just noise to react to.

A raw stdout blob forces the model to parse before it can reason, which wastes a reasoning step just recovering information that should have been structured from the start. Compare that to a return with typed fields: exit_code, failing_test_names, error_location, suggested_fix_hint. The planner can act on that immediately, no interpretation required.

Partial failure representation deserves particular attention. A return that just says "failed" throws away information the agent needs. A return that says three of five steps succeeded and failed at step four with a specific cause lets the agent resume from where things broke, rather than restarting the entire sequence from scratch. A return that says three of five steps succeeded and failed at step four with a specific cause lets the agent resume from where things broke, turning what could be a wasted execution cycle into a fast, in-session recovery.

Context budget is a constraint too easily ignored. Long return payloads eat into the space the agent needs for its own reasoning, so return shapes should surface the minimum signal necessary, not everything the tool happens to have on hand. exe.dev identifies a specific and common failure tied to this: an agent's context window is gone by the time a CI failure email lands in an inbox somewhere. The fix isn't a smarter model, it's giving the agent a local test command that returns structured results before merge, so the failure can be read and acted on inside the same execution session that produced it.

Anthropic's harness-design guide, published April 2026, offers a related principle: build on tools the model already knows. That applies to return formats as much as to tool selection. Returning standard JSON and familiar error patterns, formats the model has seen constantly in training, cuts down the parsing overhead on the other end.

The most common failure in this whole category is subtle: a tool reports success: true because the operation technically completed, even though the output it produced was wrong, like a file that got written but contains invalid syntax. Conflating "the tool ran" with "the outcome was correct" is the single most frequent return-shape mistake, and it's an easy one to make because it looks, on the surface, like the interface is working fine.

Error contract design as the difference between an agent that recovers and one that loops or gives up

An error isn't just a failure notice, it's the next prompt the agent is going to reason from. Whatever information it contains, or fails to contain, determines everything that happens next.

Errors need a taxonomy. Recoverable errors, like a wrong parameter value, a rate limit, a missing file, should look different from non-recoverable ones like a permission denial or a schema violation. Ambiguous cases, a timeout being the obvious one, need their own handling too, since a timeout could mean "try again" or could mean "stop and escalate," and the agent has no way to tell which without help from the contract itself.

Actionable errors state what failed, why, and what a valid next step looks like. A message that just says "operation failed" gives the model nothing to correct toward, and a model with nothing to correct toward tends to either retry blindly or give up. Neither is the model's fault. If the error contract doesn't distinguish "try again" from "try differently" from "stop and ask a human," there's no basis on which the agent could choose correctly between them, and that gap is a harness design failure, not a reasoning failure.

Anthropic's April 2026 guide makes a point that applies directly here: UX, cost, and safety boundaries need to be set deliberately. Error contracts are one of the main places those boundaries actually get encoded, at the interface level rather than somewhere inside the model's judgment. Part of that encoding should be an explicit "human judgment required" error class, the kind of signal that lets an agentic merge queue reserve human attention for decisions that actually need it, instead of routine failures that don't.

Permission scoping belongs in this conversation too. Only 21.9% of teams treat their agents as identity-bearing entities with scoped credentials of their own. A well-built error contract makes a permission boundary violation appear as exactly that, a permission boundary violation, rather than swallowing it into a generic failure message that tells the agent nothing about why the door was locked.

Skill set composition, why adding tools hurts as often as it helps

Removing 80% of an agent's tools lifted success from 80% to 100%, cut token usage by more than half, and dropped latency from 724 seconds to 141 seconds, a fundamental statement about what tool sprawl costs. That is not a marginal tuning gain. That's a fundamental statement about what tool sprawl costs.

Every tool in a skill set occupies space in the planner's context on every single call, whether or not it ends up used. More options mean more disambiguation work for the model, and more disambiguation work means a higher chance it picks wrong. Tools built for a use case that no longer exists don't quietly disappear, they keep appearing in context, consuming budget and adding noise the model can't opt out of, since it has no way of knowing in advance that a given tool is irrelevant.

Skill set design should follow the same logic good API design has followed for decades: expose the minimum surface that covers the required cases, and add to it only when a documented failure proves the gap exists. The file-system-as-toolbox result makes the underlying principle concrete. A small set of well-built primitives, clean parameter contracts, structured returns, tends to beat a larger set of specialized tools with irregular interfaces, even when those specialized tools are individually more powerful.

Building, maintaining, and distributing a wide array of tools is a genuinely hard engineering problem, and that cost gets paid twice: once at design time, and again at every single execution. None of this is an argument for minimalism as an aesthetic preference. Some domains legitimately need specialized tooling. The discipline is in requiring every addition to justify itself, rather than letting the skill set grow by accretion.

How transcript analysis reveals whether the interface you designed is the interface the agent uses

Observability means capturing the full sequence, tool selection, the arguments passed, the model's intermediate reasoning, memory reads and writes, state transitions, decision branches, as a structured trace that can be reconstructed after the fact. Without that trace, there's no way to know whether the interface behaving as designed is the interface actually being used.

Transcript analysis reveals the gap between intention and reality. Which tools get called constantly. Which ones never get called at all, the dead skills sitting in context burning tokens for nothing. Which tools generate retry loop after retry loop. Which return payloads run long and still fail to resolve the underlying task. A tool that's consistently called with malformed arguments is telling you something specific: either its name or its parameter structure isn't communicating the contract clearly enough for the model to construct a correct call.

High call frequency paired with low task-completion correlation is its own signal, a tool that gets tried often but rarely succeeds is a strong candidate for redesign or outright removal.

Production traces have a second life beyond diagnosis. Real transcripts convert directly into eval cases, per Braintrust's GitHub Action approach: the eval suite grows out of actual failures rather than hypothetical ones somebody imagined at a whiteboard. That feedback loop is what makes interface improvement a systematic practice instead of a matter of gut feel.

Red Hat's four-pillar model organizes this kind of work as vibes, specs, skills, and agents, with transcript analysis living at the harness layer. It's the empirical check on which skills are actually earning their place in the interface. The LangChain jump from 30th to 5th on Terminal Bench 2.0 came from exactly this kind of iterative harness optimization: teams that instrument their agents and read the transcripts systematically can chase similar gains without touching the model.

Spec validation and CI gates as the interface's downstream accountability mechanism

Even a well-designed interface needs an external check, because there's a structural gap that no amount of clean parameter naming closes on its own: an agent generates a pull request, the tests pass, the code merges, and production breaks anyway, because the implementation quietly violated a specification the tests never covered.

The risk compounds when the same agent writes both the implementation and the tests. A green test suite is evidence that the agent was internally consistent with itself, not evidence that the interface contract was honored. It's evidence that the agent was internally consistent with itself, which is a different and much weaker claim.

Spec validation as a standalone CI stage is what closes that gap, treating it as the interface's accountability check that lives outside the agent's own judgment. Augment Code's Auggie CLI approach, as described in current research, uses a verifier gate that blocks a merge when agent output drifts from the original plan, making the relationship between spec and implementation something enforced by the pipeline, not something merely hoped for. Evals run on every PR through Braintrust's GitHub Action, with results posted directly to the PR and merges blocked when agent quality drops below the bar, testing the interface's real performance against real cases instead of unit tests alone.

The merge queue is the natural chokepoint for all of this. An agent-operated queue that checks spec compliance before anything lands keeps the discipline enforced at scale, without requiring a human to review every single PR by hand. Interface design was never a task that finishes at the design stage. It's enforced continuously, at the point where code actually ships, or it isn't enforced.