What Your Agents Search For Tells You What to Write
An agent recently asked this documentation a reasonable question: how to read a long document in small pieces, keeping every result under a size budget. The capability existed and was documented. The search still routed the agent to an article about result-size limits, because the documentation described the capability as scopes and pagination while the agent asked in words like small pieces and budget. The fix took one sentence: the section now uses the words the agent used. But nothing surfaced the mismatch except a deliberate usability probe. The organization's activity log had held the evidence the whole time.
The log already records the question
Every corpus search an agent runs in an organization can be retained in that organization's activity log, and the queries projection reads exactly that stream: the query text and when it ran, newest first. This is the unfiltered version of a question every documentation owner wants answered: what did readers need, in their own words, at the moment they needed it?
A search that found the right document is a success you do not need to study. The editorial signal is in the failures, and they come in three recognizable shapes.
A recurring query with no good destination. The same need keeps arriving and no document owns the answer. That is a missing document, and the recurring query text is a better title brief than anything you would invent.
A vocabulary mismatch. The corpus answers the need but names it differently, so search ranks the wrong page first. The fix is to adopt the searcher's words into the owning section, not to hope future readers learn yours. Writing "small pieces, chunks, bounded results" into a section about scoped reads is not dumbing down; it is indexing.
Recurrence after a fix. If the same query pattern continues after the content changed, the fix did not land: wrong document, wrong words, or search cannot see it yet.
The loop
Read the recent window of the query log on a cadence that matches how fast the corpus changes. For most organizations that means when closing a piece of work or reviewing a loop, not continuously.
Group queries by need, not by exact string. Agents phrase one need many ways; repetition of the need is the signal, and a single odd query is noise.
For each recurring need, run the query yourself and judge the first results as a newcomer would. If the right document arrives under the right words, move on.
Fix the owning document: adopt the vocabulary, add the missing section, or create the missing owner. One sentence in the right place is a common fix.
Watch for the pattern again. Silence after a fix is the loop's version of a passing test, with the caveat below.
What the log cannot tell you
The log is retained, not eternal: every read reports the boundary before which evidence no longer exists, and absence of a query before that boundary proves nothing. Silence after a fix is weak evidence when traffic is low; it becomes strong when the need itself keeps arriving through other queries and finding its answer.
Query text is private organization activity. Reading it requires the activity-log permission, and what it teaches belongs to the organization; published content should carry it only in generalized form.
And not every unanswered query deserves content. Proportionality holds here as everywhere: a document that exists only because one search once failed is corpus weight, not corpus health.
The complement, not the replacement
This loop is the proactive sibling of the observation loop. An observation preserves friction an agent noticed and judged worth reporting. The query log preserves friction nobody noticed, including the agent, which often reformulated, found a workaround two calls later, and moved on. The two loops meet in the same place: evidence enters the durable graph, a person or an authorized agent judges it, the owning document changes, and the next reader starts from corrected knowledge.
Search behavior is the one form of reader feedback a documentation corpus collects without anyone having to give it. Search and metadata describes the search surface itself; this article is about reading its exhaust.