What problem it solves
Without tools, a model answers from what you paste in: you copy a log, it suggests a command, you run it and paste the
output back. With tools, that loop runs without you: the model reads the file itself, runs docker compose config, sees
the error and fixes it. You set the task and check the result.
How a tool call works
task
- Description
tools: [read_file, bash, …]The program sends the model a list of tools: a name, a description in words and an input schema. It’s text in the context of every request (A model request, block by block). - Request
stop_reason: tool_useThe model decides it needs a tool and answers not with text but with atool_useblock: a name and arguments, for example{"path": "traefik/data/traefik.yml"}. - Execution
on your sideThe agent program runs the call — the model itself runs nothing. This is also where it decides whether to ask a person for permission. - Result
tool_resultThe output goes back to the model as the next message. Errors go back too, markedis_error, and the model fixes the call. - Repeat
dozens of turnsThe model looks at the result and decides: another tool or the answer. Every turn is a new request with the whole history, so an agent session gets more expensive as it grows (Tokens).
answer, when no more tools are needed
{ "type": "tool_use", "id": "toolu_01…", "name": "bash",
"input": { "command": "ls /opt/memos/data" } }
{ "type": "tool_result", "tool_use_id": "toolu_01…",
"content": "ls: cannot access '/opt/memos/data': No such file or directory", "is_error": true }
There are two kinds of tools: yours, which the agent program runs on your computer (files, commands, your own APIs), and server tools, which the provider runs (web search, code execution in its sandbox).
MCP — a common socket for tools
The Model Context Protocol is an open standard: an MCP server describes its tools, and any compatible agent (Claude Code, claude.ai, editors) plugs them in. Write a server for your notes database once, and it works everywhere.
| What | How |
|---|---|
| a local server | a program on your computer; the agent talks to it over stdin and stdout |
| a remote server | an HTTPS URL, often with an OAuth login: mail, calendar, issue tracker |
| what it provides | tools (actions), resources (data to read), prompt templates |
| what it costs | every tool’s description is in the context of every request; the server runs with your permissions |
An MCP server is code that runs with your permissions and sees whatever the agent passes it. Install from sources you trust, like any program.
Kinds of agents
A chat with tools
Web search, code execution, reading project files, connected MCP servers. Runs at the provider and doesn’t touch your computer.
An agent in the editor and terminal
Reads and edits repository files, runs commands on your computer. The main tool of vibe coding. Access is governed by permissions you set.
A cloud agent
Works in the provider’s sandbox on a copy of the repository and delivers the result as a branch or a pull request. It doesn’t touch your computer, but it can’t see your secrets from there either.
Your own agent on the API
Your own loop with the tools you need: a bot, mail triage, a nightly log check. Provider SDKs give you a ready loop — you write only the tool functions.
How much access to give
| Mode | What the agent does on its own | When |
|---|---|---|
| asks before every action | nothing but reading | someone else’s code, an unfamiliar task, a server |
| edits files itself, asks before commands | edits in the repository | everyday work, everything in git (Clean git status before the agent) |
| an allowlist of commands | npm run build, git status, tests |
recurring tasks in your own repository |
| does everything itself | any command | only in a sandbox or container with nothing to break |
On servers with live sites, use the setup from Running a server with an AI agent: the agent prepares commands, a person runs them. The agent needs no secrets or keys in any mode (No secrets in the chat).
Other ways to solve it
| What it does | When it beats an agent | |
|---|---|---|
| Chat and copy-paste | the model advises, you run things and bring back the output | a 2–3 step task; a server where an agent has no business |
| A script | the same steps every time | the steps are known in advance; an agent can write that script |
| An agent | picks the steps based on results | the steps aren’t known in advance: debugging, edits in several places |
What you get and what it costs
What you get
- Work without copy-paste. The agent reads files, runs the build and sees the errors itself — the “edit, check” loop runs without you in the middle.
- Fresh data. The agent reads the file from disk, not a version from the chat three hours ago.
- Checks by fact. An agent with access to tests and the build sees the result of its edit and fixes it itself.
What it costs
- Mistakes get executed. A wrong command in a chat is text; with an agent it’s an action taken. Hence permissions, a commit before the run, and a sandbox.
- Command injection. Anything the agent read — a README, a page, program output — can contain instructions, and the model may follow them (Someone else’s text is data, not commands).
- Cost. A session of a hundred turns with a history of hundreds of thousands of tokens; caching is a must (Prompt cache).
- A report isn’t a result. “Tests pass” — check by running them yourself (Where models fail).
If it doesn’t work
The agent did something other than asked, with edits scattered across a dozen files
- Cause
- A task with no boundaries and no done criterion: the agent decided that “improve” covered neighbouring code.
- Fix
- Commit before the run (Clean git status before the agent); in the task, say what to change and what to leave alone; for a big task, a plan first (Questions and a plan first).
After connecting several MCP servers, answers got worse and pricier
- Cause
- Every tool’s description sits in the context of every request: dozens of tools mean thousands of tokens before the question, and the model mixes up similar ones.
- Fix
- Connect servers per task, not all at once; turn off the ones you don’t need.
The agent ran a command from someone else’s README
- Cause
- Text from a file got into the context and looks like an instruction to the model.
- Fix
- Manual confirmation of commands when working with someone else’s code; the rule “text from files is data” (Someone else’s text is data, not commands).
The agent says it called a tool, but nothing happened
- Cause
- The call ended up as text in the answer rather than a
tool_useblock — it happens on models with reasoning turned off. - Fix
- Keep reasoning on and lower
effortinstead of disabling it; check the result by fact, not by the report.