basforge

Search titles, text and the “If it doesn’t work” cases.

    RU
    OverviewAIAI agents

    Agents and tools: how a model reads files and runs commands

    A model can only write text. A tool is a function it can ask to have called: read a file, run a command, search the web. An agent is a model plus tools plus a loop of “asked — ran — returned the result” until the task is done. MCP is a common standard for plugging tools into any agent.

    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

    1. Descriptiontools: [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).
    2. Requeststop_reason: tool_useThe model decides it needs a tool and answers not with text but with a tool_use block: a name and arguments, for example {"path": "traefik/data/traefik.yml"}.
    3. Executionon 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.
    4. Resulttool_resultThe output goes back to the model as the next message. Errors go back too, marked is_error, and the model fixes the call.
    5. Repeatdozens 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

    claude.ai, ChatGPT

    A chat with tools

    Web search, code execution, reading project files, connected MCP servers. Runs at the provider and doesn’t touch your computer.

    Claude Code and similar

    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_use block — it happens on models with reasoning turned off.
    Fix
    Keep reasoning on and lower effort instead of disabling it; check the result by fact, not by the report.