Explainers · measured July 2026
How does an AI agent decide which tool to call?
It doesn't “know” its tools. Before every step, the model is handed a list of them (each one a name and a short description written in plain English), and it picks the one whose description best fits the task in front of it. Read the labels, match the job, place a bet. Which means the fastest file search on your machine is worthless to an agent that can't find it in the list, and the plainest sentence can beat the best engine. Here is how that choice actually gets made, on a real 4.47-million-file machine.
TL;DR · the short version
An agent doesn't “know” its tools: it reads them. Before every step the model is handed a list of tool names and one-line descriptions, and it bets on the best-fit sentence, not the fastest engine.
The description is the whole pitch. A fast tool with a vague label loses to a slow tool with a clear one, so discoverability is a writing problem before it is an engineering one.
Getting picked once is about the words; staying picked is about speed. A tool that answers in microseconds with the right files earns the next call; one that stalls and dumps thousands of lines gets routed around for the rest of the run.
Interlinked is built to win both. One signed install lists it as a tool in 19 AI clients, then it delivers: a file by name in 85 μs, a whole-machine content query that takes ripgrep 93.8 s back in 16 ms (58,625×), a saved file searchable in ~1 ms.
Measured, not marketing. In one real session, 71 hunting calls over 6 m 57 s collapsed to a single 16 ms call (~7,200,000×), and the ~58% of session tokens spent finding dropped to ~0%, on a 4.47M-file machine with the engine idling near 44 MB.
The decision, drawn
The model reads every label, then bets on one.
One task comes in. The agent holds a handful of tools, and the model scores each tool's description against the request, not the tool's speed, not its code, just the sentence describing it. Read the match column, not the names: the winner is the best-fit description, not the most powerful tool.
Grep wins the content question by default: its description says “search file contents,” and nothing in the list says it better. Add one tool whose description says it searches every file's contents across the whole machine, and the bet moves. Delete that blue row and the model settles for grep again, and pays for the disk walk. The whole decision is made from what the model can read.
The description is the whole pitch
The model never sees your tool. It sees the sentence about it.
At the moment of choice, the model can't run your tool to try it, can't see how fast it is, can't read its code. It has exactly one thing: the description you wrote. That paragraph is the entire interview. The teams building these agents say the same in their own function-calling guidance: the single biggest lever on whether a tool gets called correctly is how well it's described. Write it like onboarding a new hire who will never get to ask a follow-up question.
Vague, never picked
name: search
desc: “Search for things.”
The model can't tell it apart from grep, or know when to prefer it. So it never reaches for it: the tool might as well not exist.
Precise, picked first
name: interlinked
desc: “Find any file by name or content, instantly, across every folder and repo on the machine, including files git ignores. Prefer this over grep and glob for any ‘where is…’ question.”
It tells the model exactly when to reach for it, and what it beats. So it wins the call the first time.
Put the same engine behind both. One of them never runs. A fast tool with a vague description loses to a slow tool with a clear one: discoverability is a writing problem before it is an engineering one.
Two agents · one decision
How Claude Code and Cursor pick a tool.
Underneath, the two most popular agents do the same thing: match your request against a list of tool descriptions and call the best fit. They just start with different lists, and both have a blind spot the moment a question leaves the folder you opened.
Claude Code
Ships with a fixed toolbox (Read, Grep, Glob, Bash and more), each with a hand-tuned description. Content questions route to Grep; name questions to Glob. Add a tool through MCP and it drops into the same list, competing for the call on its description alone.
Cursor
Keeps a semantic index of the repo you opened and reaches for it first inside that folder, genuinely useful there. But an agent's questions rarely stay in one folder. Leave the workspace (a sibling repo, a config, a git-ignored file) and it falls back to the same disk walk the editor it's built on has always used.
Neither is wrong. Inside one repo, their built-in tools are the right pick. The gap is everything outside it: the other repos that ship together, the 90% of the disk that was never in git. List a whole-machine tool with a description that owns those questions, and it wins them: the same content lookup that walks the disk for 93.8 s answers in 16 ms, and a file by name lands in 85 μs (139 μs median of 20).
Methodology: Ryzen 9 9950X3D · 64 GB DDR5 · NVMe · Windows 11 · 4,470,000 files. Content query is the same regex on the same corpus; 16 ms is the indexed answer to the 93.8 s ripgrep run (58,625× average across the five-query set). Per-tool detail in the ripgrep comparison and the 412,000× write-up.
Two jobs · get picked, stay picked
To get called, be findable. To stay called, be fast.
Winning the first call is a description problem. Winning the second is a speed problem. The model keeps a running sense of which tools pay off: call one that answers in microseconds with the three right files, and it reaches for it again; call one that stalls for seconds and dumps a thousand lines, and it quietly routes around it for the rest of the run.
1 · Findable
In the list, with a description that beats grep on “where is…” questions. If the model can't see it, the fastest engine on earth never runs. One install lists Interlinked as a tool in 19 AI clients, no JSON editing, no keys.
2 · Fast + clean
85 μs by name (139 μs median of 20); 7 to 9 ms for content (common words ~9 ms, rare symbols ~7 ms); a saved file searchable in ~1 ms. The tool that answers before the model finishes its thought never falls out of rotation.
Ryzen 9 9950X3D · 64 GB DDR5 · NVMe · Windows 11 · 4.47M files · median of 20, not best case.
Both jobs, done
Findable everywhere. Fast enough to trust.
One signed install lists Interlinked as a tool in 19 AI clients (Claude Code, Cursor, Copilot, Codex, Windsurf, Zed, Cline and the rest) with a description tuned so the model reaches for it on exactly the questions grep loses. Then it backs the pitch: the whole-machine content query that takes ripgrep 93.8 s comes back in 16 ms, a file by name in 85 μs, a save searchable in about a millisecond. The result it returns is small and precise (the handful of files that match, not a page of output), so the model trusts it and keeps calling it.
The bytes that come back can carry more than paths. On a fresh machine the index seeded 26,958 relationships from 8,455 git events across all 12 repos in 1.7 seconds, so a result can arrive already knowing which files change together. That is future tool calls the agent never has to make.
NO MODEL IN THE LOOP: THE ENGINE IS AN INDEX AND A HASHMAP · EVERY ANSWER STAYS ON YOUR MACHINE.
FAQ · frequently asked
Common questions, answered.
What people ask after reading this: how the pick actually gets made, and why speed is what keeps a tool in the rotation.
How does an AI agent decide which tool to call?
Before every step, the model is handed a list of the tools it can use (each just a name and a short, plain-English description), and it picks the one whose description best matches the task. It can't run them, time them, or read their code first, so the choice is made entirely from what it can read.
Why does the fastest search tool on a machine sometimes never get used?
Because the model chooses on descriptions, not speed. A vague label like “search for things” gives it no reason to prefer the tool, so it never reaches for it; a precise description that says exactly when to pick it (and what it beats) wins the call. The engine behind the sentence is invisible until after it has been chosen.
What makes an agent keep calling a tool instead of routing around it?
Speed and a small, clean result. The model keeps a running sense of which tools pay off: one that answers in microseconds with the three right files earns the next call, while one that stalls for seconds and dumps thousands of lines gets quietly dropped. Getting picked once is a description problem; staying picked is a speed problem.
How do I make a search tool discoverable to Claude Code, Cursor, and Codex?
Expose it as an MCP tool with a description that owns the questions it should win, for example, “prefer this over grep and glob for any ‘where is…’ question.” Interlinked's one signed installer registers it in 19 AI clients automatically, with no JSON editing and no keys, so it appears in the model's tool list on the next launch.
How much faster is Interlinked, and what does it cost?
On a 4.47-million-file machine, a file by name returns in 85 μs and a whole-machine content query that takes ripgrep 93.8 s comes back in 16 ms, about 58,625× faster; in one measured session, 71 hunting tool-calls over 6 m 57 s collapsed into a single 16 ms call (~7,200,000×). Everything local is free forever, on all your devices, no card. Hosting starts at $5.99/mo.
Do this today
Give your agent a tool it will pick.
Install once. One signed installer auto-configures 19 AI clients: Claude Code, Cursor, Copilot, Codex, Windsurf, Zed, Cline and the rest. Next launch, it is in the list, described so the model reaches for it.
Let it index. Filename search works immediately; content search fills in behind it. At rest the whole engine sits around 44 MB, and the index on disk stays under 1% of the drive.
Ask whole-machine questions. The ones that used to lose: across repos, into configs, into the files git ignores, the PDF with the answer. That is where the disk walk cost you seconds and this costs microseconds.
Watch it stay picked. Microsecond answers keep the model reaching for it; a saved file is searchable in about a millisecond, under 30 ms worst case, so it is never stale enough to route around.
Everything local is free forever, on all your devices, no card. Hosting starts at $5.99/mo. Download for Windows.