Search results built for an agent

Searching for a symbol across a lot of repositories is exactly the kind of question an agent should be able to answer for itself. The trouble is what comes back. A few hundred matches of raw JSON — every one carrying its own metadata and a snippet of surrounding code — is an enormous payload, and if it lands inline the agent now has less context available than it had before it went looking. It searched, and the search made it worse at its job.

The search writes a compact Markdown file to disk and returns the path. The file is grouped by repository, then by file, with the matching line numbers under each and a deep link that opens the file with the matched range already highlighted.

The interesting decision is what it leaves out: there is no snippet text at all. Snippets are the largest part of the payload and the least necessary part, because anything reading this can open the link when it actually needs the surrounding code. Removing them turns a result set that would not fit into one that is a couple of screens long, and loses nothing that cannot be recovered on demand.

When a tool is built for a person, nobody would dream of answering “where is this used?” with four megabytes of JSON. We would give them a grouped, scannable list with links. The same courtesy is owed to a model, and for a sharper reason: a person can skim past irrelevance at no cost, while for a model every irrelevant token is capacity taken away from the actual task.

So the rule I now apply to anything an agent will call: design the output for the reader’s real constraint. For a model that constraint is context, and the two moves that matter are writing large payloads to a file and returning a path, and giving a reference rather than the content whenever the content can be fetched later. Most tool output aimed at agents is still shaped like an API response, which is to say shaped for nobody at all.