A latticework reading of Anthropic Engineering's guide to writing effective tools for agents — which models of software design hold, which break, and which new ones to add when your runtime is probabilistic.
Anthropic Engineering — anthropic.com/engineering
The Model Context Protocol can give an LLM agent access to hundreds of tools. That sentence sounds like an expansion of capability — and it is. But Anthropic Engineering's guide lands on a less comfortable truth: having access to a tool and being able to use it well are two different things, and the gap between them is the designer's responsibility, not the agent's. The question is no longer "does the tool exist?" but "is this tool legible to a non-deterministic caller?"
In classical software engineering, a function contract is between two deterministic systems. getWeather("NYC") will always call the same function, always parse the same response format, always trigger the same downstream logic. Both sides of the contract are predictable. What Anthropic's post describes is a different kind of contract: between a deterministic tool implementation and a probabilistic agent that may call the tool with different arguments, in different orders, in contexts its designers did not anticipate. The contract is asymmetric. The tool must be robust to a caller that is, by definition, variable.
That asymmetry rewrites most of what we know about API design. It does not retire the old models — separation of concerns, interface clarity, feedback loops — but it forces each of them through a new constraint: will this make sense to an agent reasoning under uncertainty, with a context window of limited size, under instructions it is trying to fulfil rather than instructions it wrote?
Separation of concerns gets a new application here as semantic namespacing. Anthropic's principle that tools should be namespaced to define clear functional boundaries is the old model applied to a domain where the consumer cannot read documentation in the traditional sense — it reads the tool description at inference time. Namespacing is not just a code-organisation choice; it is a cognitive clarity choice for a probabilistic reader. The agent uses namespace as a signal about which tool family to reach for, before it has read the full description.
Feedback loops also appear in a new form: evaluation-driven tool design. Anthropic describes creating comprehensive evaluations of tool performance, then using Claude Code to automatically improve the tools based on those evaluations. The feedback loop is tight and agent-assisted. This is not just testing; it is a continuous improvement cycle where the agent is both the consumer of the tool and the collaborator in its refinement. The loop is the model; its agent-in-the-loop form is new.
Token efficiency maps to the classic model of minimising cognitive load. In human interface design, cognitive load is reduced by surfacing only necessary information at the point of decision. In tool design for agents, the equivalent constraint is the context window: a tool response that returns more information than the agent needs consumes tokens it cannot reclaim. Optimising tool responses for token efficiency is minimising cognitive load for a probabilistic reader with a hard resource limit.
The dominant model in API design is richness as a virtue: return all the data the caller might need, let them filter. This fails with agent callers. An agent cannot efficiently filter a rich payload while also reasoning about what to do next; it must spend context tokens on data it will discard. The principle inverts: return the minimum sufficient context for the agent to take its next action. Lean APIs are not minimalist; they are respectful of a runtime resource that the agent cannot expand.
The model that good documentation solves usability problems also gets bent. Human developers read documentation once and then write code; the mental model persists. Agents read the tool description once per invocation, in context, competing with everything else in the context window. The description cannot assume prior familiarity. It must be self-contained, precise, and short enough to not crowd out other relevant context. That is not documentation; it is prompt engineering. The two disciplines overlap but are not the same.
Finally, the assumption that the developer is the consumer breaks down. In classical tool design, you optimise for the experience of the programmer who will call your API. In agentic tool design, the programmer sets up the tool once; the agent calls it thousands of times. The actual consumer is the agent at inference time, and the agent's constraints — variable context, probabilistic reasoning, limited working memory — are completely unlike a developer's constraints. Design for the runtime consumer, not the setup consumer.
The post's deepest contribution is the concept of non-deterministic contract — a software interface whose caller is probabilistic. Classical contracts assume both sides are deterministic; you can write formal specifications because the behaviour space is bounded. A non-deterministic contract cannot be formally verified in the same way; it must be evaluation-verified. You do not prove it correct; you sample its behaviour under many conditions and build confidence that the agent will call it appropriately. This is not a degraded form of software engineering. It is a new form with its own discipline.
The second new model is semantic legibility — the degree to which a tool's name, namespace, and description give an agent accurate priors about what the tool does and when to reach for it, before the agent has read the full specification. High semantic legibility means the agent's first guess about a tool's behaviour is roughly correct. Low semantic legibility means the agent must spend context tokens resolving ambiguity. Semantic legibility is to agent tooling what API discoverability is to developer tooling — but the consumer has a limited inference-time budget, so the stakes are higher.
A third new model emerges from the evaluation loop Anthropic describes: agent-assisted refinement — using the same agent that consumes a tool to collaborate on improving it. The agent surface where confusions emerge is also the agent that can articulate those confusions and suggest remedies. This closes a feedback loop that would otherwise require manual inspection of thousands of agent traces. It generalises: wherever an agent is the primary consumer of a system, that agent can also be recruited as the primary evaluator of the system.
The shift from deterministic to non-deterministic callers is not a refinement of software engineering; it is a rotation of its fundamental axis. The discipline that was about specifying correct behaviour is now also about legibility to an uncertain reader. Anthropic Engineering's guide is useful not because it is a checklist, but because it is a worked example of what it looks like to take classical software design principles seriously in a domain where the consumer has fundamentally different constraints. The latticework holds all the old models; it just needs to know when to apply them to a probabilistic runtime rather than a deterministic one.
Tools are a new kind of software which reflects a contract between deterministic systems and non-deterministic agents. — Anthropic Engineering