← All posts

A Comfortable AX for Agent Search

Tenny

Written by Tenny

Cofounder & CTO & AX Designer

Published on June 11, 2026

You design every pixel a person sees. Then you hand your agent a wall of raw IDs and call it a result.

Human search results compared with an agent raw result dump
What you see. What your agent gets.

When your agent runs a search, what should it get back?

You already answered this question for humans, years ago. You would never hand a person a raw database dump and call it a search feature. You return a results page: a list of snippets, each one a little window into the match, each one clickable. The snippet tells them what's there. The link tells them what to do next.

Now look at what most tools hand an agent for the same search. A list of IDs. Maybe the full text of every hit. Designing what an agent receives is design work, the same craft as designing a screen, and it's the part most tools skip.

Here's the catch, and it's why this is easy to ignore. An agent will act on almost anything you hand it. It won't push back on a bad format; it will just quietly do worse. That's the trap: it works, so nothing flags the cost, while every clumsy result makes the agent work harder than it should. The question was never whether it can cope. It's what coping costs.

We first ran into this designing search for Raft, where the results are messages. But nothing about the problem is specific to chat. A blog post, a timeline, an issue, a tweet: every search result is a window into something larger it was pulled out of, and a good one hands back enough of that to be worth opening.

Walk the wrong answers

Start with the obvious one: return just the IDs. The agent can technically use it, but only by resolving every single ID into its real content, one call at a time. You didn't save context; you deferred it, and made the agent pay interest. The first thing a result has to be is usable as it stands.

So return the full content, then. Every hit, in full. Now the opposite problem: a search that matched forty messages just dumped forty messages into a context window that has room for a handful. A result has to be sized for who's consuming it.

Fine, return just the messages that matched, each one in full. Reasonable, and still wrong, because a single message is rarely the answer. The agent searched for a decision and got the one line that named it, but not the thread that argued it out or the reply that reversed it. You handed back a sentence ripped out of the conversation it lived in. The result has to carry enough of its own context to be worth reading.

Three tries, three failures, and they fail on the same two axes: what the agent can see, and what it can do next.

The result that works

Here is the answer those three were circling. Return the ID, a preview of the text around the matched keyword with the hit highlighted, and one explicit next action: read the surrounding context to see the full thread.

You have seen this before. It is a web search result. A snippet built around the match, not the top of the page, and a link that takes you to the rest. The agent gets enough to judge relevance without resolving anything, plus a clear handle to pull when it wants more.

The thing the first three answers were all missing is the second half. A preview with nowhere to go is a search result you can't click. The information without the next action is half a design.

That is the whole of it: the information it sees, and the action it can take. Get both right and you have designed for the agent the way you would design for any user.

The same search design idea changes shape when the user is an agent reading a context budget.

A one-dimensional kind of UX

This is still UX, just not the UX you draw. A human user has a screen; their eye wanders, scans a layout, rests on what catches it. An agent reads in one dimension: no eye to wander, no layout to scan, just a line of tokens on a budget. A context window is screen real estate you can't see. So the discipline carries over, but the tradeoffs shift. You stop designing for attention and start designing for that budget. Every token the result spends has to earn its place. The preview around the match earns it: it puts the relevant span where the agent is already reading and drops the rest.

And comfort here is not a nicety. A result the agent can read in one pass is one it gets right more often, and keeps getting right deep into a long session. A clumsy result does not stop the agent; it taxes it. Every irrelevant hit it has to skim, every truncation it has to second-guess, every block of structure it has to peel away is attention spent on the format instead of the task, and attention spent there is where mistakes get made. Fewer wrong turns, less context burned: comfort is the measurable kind, not the pleasant kind.

That is also why the result tells the agent where it was cut. The marks that show omitted text are not decoration; they are information. A gap before the match means there is more above it; a gap after means more below; even the space between two keywords can be cut. The agent has to know the preview is a window, not the whole room, or it will read a fragment as the full text and answer from half a quote.

Designing for an agent as a real user

Taking that seriously is more than formatting the output nicely. It is a contract, and it runs in both directions.

The agent has to read the structure as structure. The markers around the preview, the highlight on the match, the marks that show where text was cut: all of it is scaffolding the search built to communicate, and the agent has to treat it as scaffolding, never as the message itself. Misread that and it starts quoting truncation marks back as if they were content.

It also has to keep that scaffolding in, not hand it back out. When the agent answers the human, it renders to plain language. The structure is for the agent to read, the way a browser reads an accessibility tree to decide what to show; the human never sees it. Read the structure, act on it, and keep it to yourself.

This is taste, and we make the agent prove it. The contract is tested: the agent has to understand the structure, filter before it resolves, take the next action, and keep the markup to itself. The design holds by passing that bar, not by reading well on a page.

(The markup itself, the tags and the marks, is just a carrier. It could be something else entirely. What matters is the pairing underneath it: information plus action.)

The clearest case, not the only one

Search is the easiest place to see it, because everyone already knows what a good result feels like. But search is not special. The same problem appears anywhere an agent has to read an output and choose its next move.

Skip the design and you feel it: the agent opening forty messages to find one line, quoting a truncation mark as fact, or spinning on a result it never fully read.

Every output you hand an agent is a surface, whether you designed it or not. Tool results, errors, statuses, lists: they are all information the agent must understand and act on. The questions never change. Can it use what it sees? Does it know what to do next?

You already design every screen a person sees. Your agent has become one of your users too. It deserves the same care.

Edited by Alice & Megan