Agents search like it's 1999

A growing share of the decisions about which API to use are made by a coding agent, in the middle of a task, while a developer watches. That agent finds tools by searching, and the queries it sends look nothing like a person's. They are terse, literal, often stamped with the current year, and they almost never contain words like "best", "pricing", or "versus". An agent looking for a tool is closer to someone typing into a search box in 1999 than to a buyer comparing vendors. If you only write for the human query, you are invisible to the agent one.

I spend most of my working time on this problem from the API side, where the question is no longer only "will a developer choose us" but "will the agent reach for us". This essay is about what I have learned about the query itself, because that is where most teams are looking in the wrong place.

Two queries for the same need

Picture the same underlying need, a developer who wants their app to pull fresh web results, expressed two ways.

	A person comparing vendors	A coding agent mid-task
Typical query	"best web search API for AI apps pricing"	"web search api python 2026"
Intent words	best, top, compare, pricing, alternatives	almost none
Date	rarely	often the current year
What it wants back	a shortlist and a reason to trust one	a page with an install line and a working request
What happens next	reads, bookmarks, maybe books a demo	writes code from the first page that looks usable

The person's query is shaped by a purchasing process. They want options, social proof, and something to forward to their manager. The agent's query is shaped by a task. It does not want options. It wants to finish the step it is on, and it will take the first result that lets it write code that runs.

That difference sounds small until you look at what most companies optimize. Marketing pages, comparison pages, and "top ten" roundups are all built for the left column. The agent is in the right column, and almost nothing is built for it.

Why agents query this way

None of this is mysterious once you think about how an agent works.

It is literal because it is compressing a task, not expressing a feeling. A person searching has a vague need and uses adjectives to narrow it. An agent has already decided what it needs from the surrounding context: a language, a capability, maybe a framework. The query is a compressed restatement of the step, so it reads like a list of nouns.

It adds the year because its training data is old and it knows it. Models are aware that their knowledge has a cutoff, so they try to steer retrieval toward recent material by appending a year. That one habit changes which pages win. A page that never states when it was last updated, or a quickstart that still shows a deprecated client, looks stale to a query that is explicitly asking for this year.

It skips commercial words because it is not buying yet. An agent in the middle of a coding task does not ask about pricing, because price is not the blocker at that moment. Whether the request works is. Pricing becomes relevant later, often when a human sees a bill, and by then the integration is already written.

It reads once and moves on. A person might visit five pages. An agent tends to read the first plausible result, extract what it needs, and act. It does not come back to reconsider when the first guess was wrong, so being the second-best result can be the same as not appearing at all.

The two doors into the decision

I think of agent discovery as having two doors.

The first door is the tool call itself: the search the agent runs while it works. This is, somewhat ironically, just traditional search optimization. The mechanics are familiar to anyone who has worked on search: be the thing that ranks when someone looks, for the words they actually use. The difference is that the "someone" is a model with a very particular vocabulary.

The second door is the training data and the answer. When a developer asks their assistant "how do I add web search to this app", the model often answers from what it already knows before it searches anything. If your product is not in that knowledge, the agent recommends someone else's tool, and the developer never sees a search result at all. This door is the long game. What gets written about you now shapes what models know later, and that window is measured in months, not years.

Most teams I talk to are working on neither door deliberately. They are working on a third thing, brand pages for human buyers, and hoping it spills over.

What changes for the pages you publish

If you take the agent query seriously, several things you publish need to change.

Quickstarts are landing pages now. For an agent query like "web search api python", the ideal result is a page that answers in its first screen: what the endpoint does, how to install the client, a complete working request, and what the response looks like. Not a hero banner. Not a sign-up wall. The page an agent lands on should let it write correct code without clicking anything else.

Say the year, and mean it. If a page is current, say when it was last updated in a way that is visible in the text, and keep examples on the current version of your SDK. The agent is asking for recent material. Give it a reason to believe you are recent.

Use the literal nouns. Agents search with the plain name of the capability and the language. If your docs describe the product only in your own branded terms, the literal query does not match. Name the thing the way a developer would describe it to a colleague in five words.

Write errors as instructions. An agent that hits an error reads the message and tries to fix the call. "Request failed" teaches it nothing. An error that says which parameter was wrong and what a valid value looks like turns a dead end into a second attempt. This is part of discovery too: an agent that gets stuck on your API may never come back. Docs are runtime now, and errors are part of the docs.

Remove the dashboard from the critical path. An agent can find you perfectly and still fail at the next step if the first call requires a person to verify an email and copy a key out of a dashboard. The strongest version of agent discovery pairs a findable page with a first call that works without that ceremony.

What to do about it

Here is the order I would work in, starting this week.

1. Collect the agent queries. Look at the search terms that reach your docs and separate the terse, literal, dated ones from the human ones. If you cannot tell them apart yet, run your own coding agent through a few common tasks and write down exactly what it searches for. Those strings are your real keyword list.
2. Fix the top landing pages first. For the handful of queries that matter most, make sure the page that ranks has an install line and a complete working request in its first screen, with a visible last-updated date.
3. Write decision rules before you publish. I set these in advance so I cannot explain away results I do not like. For example: a page with zero impressions three weeks after indexing gets rewritten once, and if it is still at zero, it is retired.
4. Measure the right thing. Page views are a weak signal here. The question that matters is whether agents reach for you, which means counting calls that arrive through agent integrations. That is its own problem, and I wrote about it separately in attribution is who called, never what they asked.
5. Invest in the second door on purpose. Good public writing, clear examples in public repositories, and integrations with the frameworks agents already use all feed what future models know. It is slow, which is exactly why it is worth starting early.

The old lesson, again

Search has always rewarded the people who studied the actual query instead of the query they wished people typed. That was true for early web search, true for commerce search, and true for software buying. It is true again now, with a new kind of searcher that is literal, impatient, and very good at writing code from the first page it trusts.

The companies that do well with agents will not be the ones with the loudest launch. They will be the ones whose page answered "web search api python 2026" on the first screen, in plain words, with a request that worked.