docs · tools
What a tool is
A tool is one action on one site — search LinkedIn people, read a Walmart product, add something to a cart — written down precisely enough that it can be performed again without thinking. Your agent calls it by name and gets fields back.
Why anything is needed at all
Give a model a browser and it can do almost anything on the web. The catch is that it does it from scratch every single time. A single “look up this profile” costs a navigation, a screenshot, a DOM snapshot, a few guesses at which element is the right one, a retry when the guess was wrong, and a pile of tokens spent describing a page to itself.
Run that same task tomorrow and it pays the whole bill again. Nothing was learned. The agent has excellent judgment and no memory — like a brilliant new hire who is new again each morning.
A tool is the memory. The first time an action is performed it is expensive and exploratory; afterwards it is a function call.
What is actually stored
Not a description of the task, and not a recording of clicks — a recipe: the concrete requests or steps that perform the action, plus how to read the answer out of the response. Around that recipe sits the part your agent sees:
| Field | What it is |
|---|---|
name | The id it is called by — kebab-case and unique, like linkedin-get-profile |
site | The domain it operates on |
intent | A long description written for the model: what it does, what it needs, what comes back, what usually goes wrong. This is what the agent reads to decide it is the right tool |
params | The inputs, each with its type |
result | The fields a successful run produces |
side_effect | Whether it only reads, writes something undoable, or sends for real — see side effects |
The recipe is the private half and the rest is the public half. An agent picks a tool by reading the interface, exactly the way you would pick a function from its signature without opening its body.
A tool returns data, not a page
This is the part worth being pedantic about, because it is where the speed and the cost savings actually come from. A browsing agent without tools gets pixels and markup back and has to turn them into meaning. A tool returns the meaning:
Two consequences follow. It is faster, because there is no model deciding anything mid-run — the requests are already known. And it is cheaper, because a JSON object is a fraction of the tokens a screenshot plus a DOM dump costs.
How a tool comes to exist
Nobody sits down and writes these by hand. They are a by-product of the agent doing the work once. The server exposes four verbs, and they are the whole loop:
| Verb | When | What it does |
|---|---|---|
discover | Before anything else | Asks memory what is already known for this site. It is the first step of every web task, before the browser is opened |
run | There was a match | Replays it with your params and returns the data. No model in the loop |
request | There was no match | The agent does the task the slow way, with the browser. When it works, this freezes what actually happened |
save | Right after | That frozen trace is distilled into a tool and persisted, so the next discover finds it |
So the expensive path happens once per action per site, and every run after it is the cheap path. A new site starts slow and gets fast on its own — you never write a scraper, and you never maintain one.
Primitives and composites
Some tasks are one action; some are one action feeding another. Both are tools, and both are called the same way:
| Type | What it is | Example |
|---|---|---|
| primitive | One web action with its own recipe, its own params, its own result | linkedin-get-profile |
| composite | No recipe of its own — it runs other tools in order, feeding each from its params and from what earlier steps returned | linkedin-search-people-by-location |
The composite above exists because LinkedIn will not filter a search by the word “Argentina” — it wants an internal region id. So one tool resolves the name to the id, and a second searches with it. The agent calls one thing; two run.
What passes between the steps is always stable data — an id, a URL, a resolved value — never live browser state. That is why a chain is replayable at all: each step would work just as well on its own.
One tool covers a whole class of requests
A tool is parameterized, not frozen around one example. search-products searches for any term; get-profile fetches any slug. Learning “search for lemons on the store” and saving a tool that can only ever search for lemons would be close to useless — the varying values get lifted into params while the steps stay fixed.
Where the tools themselves live
Two places, and they are not the same thing:
- Your machine —
~/.tool-memory. Everything your agent has learned or pulled down. This is whatdiscoversearches. - The hosted registry — a shared, read-only set of ready-made tools the server pulls from anonymously, so a site somebody else already figured out is fast on your first run too. It can be turned off to run fully local.
To browse what exists today, site by site, use the tool directory — these docs explain the machinery, the directory is the list.