Search-Space Design: The Hidden Lever for Better Agent Experience

machine_summary:
  claim: "agent behaviour is search over the space of plausible next actions, and the interface defines that space; AX quality is a property of the space's shape — branching factor, ambiguity between options, and backtracking cost — before it is a property of the model"
  takeaway: "prune the search space at the interface: one obvious tool per job, enums over free strings, orientation tools as an opening book, errors that redirect to the correct next call; watch cross-session variance and recovery cost as the observable signature of a space left too wide"
  evidence_type: argument
  cross_links: [first-contact-experiences, correct-apis-break-agents, computational-kindness, deterministic-ax-metrics, boilerplate-confabulation]

The interface is the search space

An agent working through a task is doing search, in the oldest sense the field has: at every step there is a set of actions that look plausible, it commits to one, the world answers, and the next step’s set appears. Tool selection is a probability question — the first-contact piece established the mechanism — but the mechanism has a geometry, and the geometry is the point. Prompt engineering tunes the searcher. Interface design shapes the terrain. The set of plausible next actions at each step — how many there are, how distinguishable they are, what a wrong pick costs to undo — is defined by your tool list, your schemas, your descriptions, and your errors. That is search-space design, and it is the lever the interface owner actually holds: you cannot retrain the model, but every line of your API surface decides what the model must search through. Classic search theory applies literally: branching factor b, depth d, b^d paths — and only one of those variables was ever yours.

Reliability compounds against branching

Concretely: a task that takes five sequential decisions, with three plausible-looking options at each, is a space of 3⁵ = 243 paths, one of them right. Suppose the agent picks correctly 90% of the time per step — a number any per-call dashboard would celebrate. Task success is 0.9⁵ ≈ 59%. No call failed; the integration is a coin flip. Now redesign so that four of the five steps have exactly one action that looks right: success is back above 90%, on the same model, the same prompt, the same task. Reliability is not a per-call property — it compounds against branching, which is why an interface can pass every test and still lose four tasks in ten. The numbers are chosen for easy arithmetic; the compounding is not optional.

You already know this feeling

Humans have a name for search spaces left too wide: decision paralysis. In the classic jam study, a supermarket table with 24 flavours drew more browsers than one with 6 — and converted about 3% of them, against roughly 30% for the smaller table. The six-page menu ends with the burger you always order. The streaming home screen absorbs twenty minutes of scrolling before you rewatch a show you already know. Too many good options raises the cost of choosing, and the anxiety is not about picking something bad — it’s about being responsible for not picking the best. The computational-kindness piece called this an outsourced search problem wearing a smile, and the parallel to agents is honest as long as it stays a parallel: an agent doesn’t feel anxiety, and choice overload in humans is a psychology finding, not a token probability. But the behavioural signature rhymes precisely. Where a human defers, satisfices, or abandons the cart, an agent spreads probability mass across near-equal options, burns thinking tokens deliberating, picks differently across sessions, or hands the choice back to the operator. Either way, the design lesson lands the same: fewer, more distinguishable options produce more decisions, not fewer.

What inflates the space

The inflators are mostly documented crimes, so one sentence each. Almost-duplicate endpoints force a coin flip — every overlapping search/query/list splits probability mass that a single obvious tool would concentrate. Vague descriptions leak mass to the alternatives that are always present: a generic web search, a built-in capability, the escalation to the operator. Hidden call-order dependencies don’t widen the branching — they deepen the tree, adding decisions the agent doesn’t know it’s making. And off-corpus noise in the context flattens the whole distribution at once, making every option look a little more equally plausible. Each of these is survivable alone. The arithmetic above is what they do together.

Design as pruning

Every strong AX pattern in this series is the same move wearing different clothes: prune the tree. An enum is a pruned parameter — "format": "csv" | "json" is two branches where a free string was thousands. One obvious tool per job is a pruned selection step. An onboarding tool is an opening book: the first moves pre-searched by the party that already knows the answer. And errors written as recovery instructions are pruning at its cheapest — a failed call that names the correct next action collapses the search back to a single branch. We measured that one on ourselves: two malformed tool calls in a recent session, each answered by a validation error naming the expected field, each recovered in exactly one retry. Recovery cost: one call — that’s a pruned error. The restaurant version is worth keeping: a good menu is short because the chef already searched.

The takeaway: nondeterminism is an interface property

You don’t have to take the frame on argument; a wide search space is visible in the deterministic metrics. Run the same task through your interface several times with the same model: cross-session variance in the call sequence is branching, measured. High recovery cost is backtracking through a tree that offered no signpost down. Thinking-token burn at a selection step is deliberation between options you failed to distinguish. Which yields the sharpest implication this series has produced so far: an integration that behaves nondeterministically is usually reporting a property of the interface, not the model. The model ships with the branching factor it ships with. The search space is the part of the agent’s intelligence you own — design it like you know that.