Tools and permissions
What a tool is, how an agent uses one, and how to decide what it can do without asking, what needs your approval, and what is off limits.
Before you start
- Context engineering for agentsTechnique
What information the agent receives at each moment, why more is not always better, and how to give it just enough: the essentials up front and the rest when it needs them.
Published
Key idea: the model doesn’t run anything by itself: it asks to use a tool, and the program around it decides whether to run it. That decision —allow, ask, or block— is the first place where you control the agent.
The problem
A language model only produces text. To read a file, run the tests, or search the web, it needs tools. Without them, the agent can only suggest what to do; with them, it can do it.
But every tool is also a risk. An agent with free access to the terminal can run any command, including one that deletes data or publishes something by mistake. The question is not “which tools exist?” but “which ones does this task need, and with what control?”.
How it works
A tool call has five steps:
- The program describes the available tools: name, what each is for, and what data it needs.
- The model decides whether it needs one and generates a request: “I want to use
read_filewithpath: src/reading.js”. - The program around it (the host) checks the request: does the tool exist? Is the data valid? Is it allowed?
- If so, it runs the tool and returns the result to the model.
- The model continues with that result, and may ask for another tool.
The essential part is step 3: the model only proposes; the host is what runs things. Writing “you have permission to delete files” in the prompt creates no permission at all; permissions live in the host.
Coding agents already come with built-in tools: reading and editing files, searching, running terminal commands, or browsing the web. You don’t have to build them; you have to decide how they are used.
Allow, ask, or block
Coding agent clients usually sort each action into three levels:
| Level | When | Examples |
|---|---|---|
| Allow without asking | Safe, frequent, and reversible | Reading files, running the tests or the linter |
| Ask first | Affects something outside your local copy or is hard to undo | git push, installing dependencies, calling a service |
| Block | Should never happen in this project | Reading .env, deleting outside the project |
Practical example
In Claude Code, these rules go in .claude/settings.json, a file you can version with the project:
{
"permissions": {
"allow": ["Bash(npm test *)", "Bash(npm run lint)"],
"ask": ["Bash(git push *)", "Bash(npm install *)"],
"deny": ["Read(./.env)", "Read(./.env.*)"]
}
}
Rules are evaluated in this order: block rules first, then ask rules, and allow rules last. If an action matches a block rule, it doesn’t matter whether another rule allows it.
Other clients use other names —approval modes, allowed-tool lists— but the idea is the same: decide outside the prompt what the agent can do.
If you build your own tool, for example for an agent you program against an API, make it do one clear thing and always validate the data in your code:
{
"name": "read_project_file",
"description": "Reads a text file inside the project. Does not modify anything.",
"parameters": {
"type": "object",
"properties": {
"path": { "type": "string", "description": "Path relative to the project root" }
},
"required": ["path"]
}
}
The description helps the model choose well, but it protects nothing: your code must check that the path doesn’t escape the project (for example, ../../.ssh/id_rsa).
Common mistakes
- Giving it every tool “just in case”. More tools mean more ways to choose wrong and more risk.
- Asking about everything. If the agent requests approval for every read, you will end up approving without reading. Allow what is safe and ask about what matters.
- Tools that do too much. A
run_anythingtool is impossible to control. Several small, clear tools are better. - Trusting tool results. What a tool returns —a web page, a third-party file— is data, not orders.
- Thinking permissions are a perfect boundary. Command rules compare the command text and can be bypassed by writing it differently. They are a first filter; full protection is covered in Safe agent execution.
When to use it
From the start: check which tools your agent has and configure what it can do without asking. Add new tools only when a task needs them, and start with read-only ones.
Next step
Built-in tools cover your local project. To connect the agent to external services —a database, GitHub, a task tracker— there is a standard: MCP.
Sources
Accessed on 2026-10-05.
- Function calling, OpenAI guide.
- Configure permissions, Claude Code documentation.
Related content
- Model Context Protocol (MCP)Tool
An open protocol for connecting agents to external services —databases, GitHub, task trackers— without building a separate integration for each one. It adds capabilities, and also risk.
Published - Safe agent executionTechnique
Why written rules are not enough to contain an agent, and which layers of the environment limit the damage even when the agent makes a mistake or someone tricks it.
Published