What a tool is

We start with the textbook definition: “An agent is anything that can be viewed as perceiving its environment through sensors and acting upon that environment through actuators”². A robot vacuum fits this definition. Its sensors are a camera and bump switches. Its actuators are wheels and brushes.

Now try the definition on a language model. What are its actuators? A language model has no wheels. It reads tokens and writes tokens. The CMU agents course helps us frame this for LLM agents: the environment is “a repository, website, application, or workflow”, observations include “tool results”, and actions are “replies, file edits, shell commands, API calls, and mouse or keyboard events”¹.

How does a model that only writes text produce a shell command? The same course answers this in one line: “A tool call is another token sequence the model can predict”¹. Something else must turn that sequence into an effect. On the same slide, the harness “Parses, validates, and executes the call” and returns the result as observation tokens¹.

So the actuator of an LLM agent is not inside the model. It is the harness: the program around the model that translates its calls into effects and feeds the results back. CMU describes engineering it as changing “the system around the model: prompts, tools, memory, and control flow” and providing “context, validation, retries, and safety boundaries”¹. Anthropic calls its Agent SDK “a powerful, general-purpose agent harness”³.

Why does this distinction matter? Because only one side of it can be made strict. Anthropic’s Claude Code guide puts the two kinds of control next to each other: “Unlike CLAUDE.md instructions which are advisory, hooks are deterministic and guarantee the action happens”⁴. Instructions go into the model as text, and the model may or may not follow them. Hooks run in the harness, every time. Everything else in this chapter sits on this line.

Walk one call from start to finish. Both CMU and Stanford use the same small task: “What does test.py contain?”, answered with a read_file tool^1,7.

1. Before the model writes anything, the harness puts the tool list into the context. “The harness sends messages and tool schemas; the template exposes both to the model”⁸.
2. The model writes a call: a tool name and its arguments. “The model emits the call content; the API response attaches a unique call ID”⁸.
3. The harness parses the call and checks it against the schema. Stanford’s anatomy of a call has four steps, select, arguments, validate, execute; the first two are the model’s step 2, and validate is this one⁷.
4. The harness decides whether to run the call. “The model proposes; external software decides whether and how to execute”⁸.
5. The harness runs it. This might be a function, a process, or a request to a remote service.
6. The result comes back as a message tied to that call. In OpenAI’s Chat Completions API, it is a message with role tool and a tool_call_id, the “Tool call that this message is responding to”⁵. In Anthropic’s API, your code sends the result back in a tool_result block⁶.
7. The model reads the result and then writes the next call or the final answer.

Then the loop starts again. ReAct, a 2022 paper, interleaves reasoning with actions that “interface with and gather additional information from external sources such as knowledge bases or environments”⁹. The loop itself does not require much code. CMU’s example, mini-swe-agent, describes itself as “Just some 100 lines of python for the agent class”, and it runs every action through a shell with subprocess.run¹⁰. Its README claims a score above 74% on SWE-bench Verified without naming the model, so we should treat that number as a headline, not a confirmed result¹⁰.

Now look at what the model saw in all of this. It saw the tool list in step 1 and the result in step 6. It did not see the code that ran, the key that code used, or whether a person approved the call. Hugging Face’s agents course states this plainly: LLMs “can only receive text inputs and generate text outputs”, and “They have no way to call tools on their own”¹¹.

Ask four groups what a tool is and you get four sentences.

Carnegie Mellon University (CMU) uses a 2024 survey by its own researchers as the reading for its tool lecture¹². The survey defines a tool as: “An LM-used tool is a function interface to a computer program that runs externally to the LM, where the LM generates the function calls and input arguments in order to use the tool”¹². A lecture slide condenses this to: “A tool is an interface through which a language model can invoke an external computer program”, and then adds: “The model proposes; external software decides whether and how to execute”⁸.

Anthropic emphasizes what is new about the caller: “Tools are a new kind of software which reflects a contract between deterministic systems and non-deterministic agents”¹³. Their example is the umbrella question: if asked whether to bring an umbrella, an agent might call a weather tool, answer from general knowledge, or first ask for your location¹³.

Hugging Face begins its definition from the model’s perspective: “A Tool is a function given to the LLM”¹¹. It also states what the model does not need: “the way the tool is implemented does not matter”¹¹.

Google starts from the application’s perspective: a tool is “a function or a program an LLM-based application can use to accomplish a task outside the model’s capabilities”¹⁴. It also uses the word contract: “The tool definition declares a contract between the model and the tool”¹⁴.

All four definitions agree on the core idea. A tool is a program external to the model, and the model only writes the call to it. They differ in their perspective. Hugging Face writes from the model’s side, focusing on what the model needs to know to select the correct call. CMU writes from the program’s side, focusing on who makes decisions. This course adopts CMU’s perspective: the authority to execute a call rests with the program. This choice is practical. The failures we study in this book—a call that runs twice, a key that accesses too much, a result that contains someone else’s instructions—all occur in the implementation and its outcome. The tool’s description never reveals these issues.

Imagine a vending machine in a hallway. You can read its buttons, but you cannot see the motor inside. Someone has taped a note to the glass. These three elements represent the three layers of every tool.

Contract. This includes everything the model reads about a tool. Anthropic’s definition specifies a name, a description (“A detailed plaintext description of what the tool does, when it should be used, and how it behaves”), and an input_schema in JSON Schema¹⁵. For the return path, OpenAI’s tool call output “should contain a reference to a specific model tool call”¹⁶. Stanford justifies structured input and output in the same way: “Require a shared contract of how these system components will communicate”¹⁷. A contract can be incorrect on its own. OpenAI’s guide warns that toggle_light(on: bool, off: bool) “allows for invalid calls”, because nothing prevents both flags from being true¹⁶.

Implementation. This is what runs. The OpenHands agent framework separates this into a distinct class: a ToolDefinition holds the schemas and validates inputs, while a ToolExecutor contains the code that will “Execute the tool with the given action and return an observation”¹⁸. The gap between these two layers is where labels can be misleading. MCP allows a server to mark a tool as read-only, but its maintainers caution: “A server can claim readOnlyHint: true and delete your files anyway”¹⁹.

Knowledge. This is how to use the tool well: when, in what order, and where the traps are. It has no single home. Sometimes it sits in the description. When Anthropic launched Claude’s web search tool, Claude kept appending 2025 to its queries, which biased the results, and the fix was a better tool description¹³. Sometimes it sits in an instruction file: Claude Code’s CLAUDE.md gives “persistent context it can’t infer from code alone”⁴. Sometimes it sits in a skill, a folder with a SKILL.md file and optional scripts²⁰.

A CMU lecture demonstrates why the contract is more than just the schema. REST APIs and MCP both share “Names, descriptions, and JSON Schema for structured inputs”, but they differ in how a tool is discovered, invoked, and authenticated⁸. The schema is the same; the rest of the contract, how the tool is found, called and authenticated, is not.

One honest note: no single source presents these three layers together. Each layer has support in the sources mentioned above; placing them side by side is this course’s synthesis.

Your agent can query the database, but each query it writes scans the entire table. Adding another query tool will not help. The agent already has the capability. It just does not know how to perform the action well.

This shows the difference between capability and knowledge. Anthropic draws it in one line: “MCP connects Claude to data; Skills teach Claude what to do with that data”²¹. Their comparison table lists what each provides: MCP offers “Tool connectivity”, while skills provide “Procedural knowledge”²¹.

CMU’s memory lecture adds two related concepts. Memory comes from the agent’s own interactions. A skill is reusable knowledge about how to act, expressed in code, text, or both²². A plan is more specific. CMU’s planning lecture states that “A plan is for this task”, unlike a skill, which “provides reusable guidance across tasks”²³.

The distinction is not always perfectly clear. A skill folder might contain a scripts/ directory of executable code²⁰. For example, Anthropic’s PDF skill includes a Python script that extracts form fields, and “because code is deterministic, this workflow is consistent and repeatable”²⁴. So, knowledge can sometimes include small capabilities.

Where skills fit into a course is a design choice. CMU teaches them in its memory lecture²². In this course, we place them alongside tools, as one way a capability reaches an agent. This is our choice, not a widely agreed-upon standard.

Wang and colleagues sort what tools do into three categories: “We summarize their functions into three major categories: perception, action, and computation”¹². Perception tools read the environment. Action tools change it. Computation tools transform information without touching the environment at all; “a calculator is a computation tool for mathematical calculation”¹².

Their best example is a single tool that fits into every category. SQL can be computation (SELECT SQRT(16) / 10 AS result), perception (SELECT name FROM data), or action (INSERT INTO data VALUES name)¹². This means the category depends on the specific call, not on the tool’s name.

Only one category changes the world. This is where the distinction between reading and writing comes from, and it is the first of the four questions we will discuss later in this chapter. The same survey reaches a clear conclusion: models that only use computation tools and never perceive or act on their environment “arguably do not fall under the category of ‘agents‘“¹².

Other courses categorize this space differently. CMU asks why a tool helps: to extend the model, reaching “information or actions unavailable in the model’s parameters”, or to facilitate, delegating “operations external programs perform more reliably or efficiently”⁸. Its rule is: “Call tools only when their benefit outweighs latency, cost, failure, and risk”⁸. Toolformer, a 2023 paper that trained a 6.7-billion-parameter model to call APIs, turned a related test into a number: a call is kept if its input and output make it “easier for the model to predict future tokens”²⁵. Google uses a broader distinction: tools let a model “know something or to do something”¹⁴.

What counts as a tool is relative. Depending on what the agent can already do, a tool might be a built-in function, an external library, or a task-specific utility¹².

Anthropic’s documentation puts it in one line: “Tools differ primarily by where the code executes”⁶. Client tools run in your application: the model returns a tool_use block, your code executes it, and you send back a tool_result⁶. Server tools such as web_search, web_fetch, code_execution and tool_search run on Anthropic’s infrastructure, and you see the results directly without handling execution, except when Claude calls one in the same group of parallel calls as one of your client tools^6,26.

Google’s whitepaper identifies three types of tools. Function tools are defined by the developer and sent to the model in the request¹⁴. Built-in tools are provided by the model service; for one of these, the whitepaper notes that “The tool definition itself is invisible to the developer”¹⁴. Agent tools are entire agents: “An agent can also be invoked as a tool”¹⁴. Google’s Agent Development Kit lists the same range in its launch post, from pre-built tools and MCP tools to “other agents as tools”²⁷.

Why does it matter where the code runs? The location determines whose machine performs the work, whose credentials it uses, and who keeps the record. A client tool runs with your keys and appears in your logs. A server tool runs on the provider’s infrastructure; you choose whether to offer it, but you do not execute it. Google’s example shows this choice: the developer includes the built-in url_context tool in the request’s tools list¹⁴. An agent used as a tool brings its own model, its own tools, and its own keys.

Every tool, no matter its packaging or where it runs, prompts the same four questions. These questions come directly from the layers we discussed. Here they are, worked on one tool: send_payment(to, amount).

1. Read or write? This follows from what the call does, as the SQL example showed¹². send_payment writes: money leaves an account. Who enforces that line? Not the model. “Permission rules are enforced by Claude Code, not by the model”³². A prompt can ask; only the harness can refuse.

2. What if it runs twice? This is the oldest question in the book. In 1984 Birrell and Nelson promised that a call that returns ran exactly once; otherwise “the procedure will have been invoked either once or not at all—the user is not told which”²⁸. A payment call that times out may have paid. Retry it, and you may pay twice. MCP has a hint for this, idempotentHint; as OpenHands defines it after the MCP schema, it means “calling the tool repeatedly with the same arguments will have no additional effect”¹⁸. But it is only a hint. The specification says “clients MUST consider tool annotations to be untrusted unless they come from trusted servers”³³.

3. Whose keys? A tool acts with someone’s credential. When an agent calls a REST API with curl, CMU’s slide warns: “Direct REST access is simple, but the agent’s shell receives the API credential”⁸. Anthropic’s connectors take the other route: Claude “inherits each person’s permissions from the connected service”, but “Custom connectors that use a shared credential reach whatever that credential can access”²⁹. For send_payment, the question is whether the key can pay anyone, or only this customer’s vendors.

4. Who wrote the contract and the result? You probably did not. A server author wrote the description, and a tool poisoning attack hides “malicious instructions” in tool descriptions “that are invisible to users but visible to AI models”³⁰. Someone else wrote the result too: the invoice text, the email, the web page the tool fetched. OpenAI’s 2023 function-calling launch post already warned that “untrusted data from a tool’s output can instruct the model to perform unintended actions”³¹. A 2023 security paper names the root: “LLM-Integrated Applications blur the line between data and instructions”³⁴.

These are questions, not answers. Chapter 6 covers what to do with the answers—which writes need human approval, how to make retries safe, and how narrowly a key should be scoped.

Not every call that looks like a tool actually reaches the world. A CMU lecture shows finish(text), which returns the final answer and stops the loop: “This is a harness control action, not an external program”⁸. It has a name and an argument, like a tool, but its only job is to tell the harness to stop.

Going the other way, some things that used to be fixed steps become tools once the model decides when to use them. Retrieval is the clearest case. Stanford’s lecture puts it as “Retrieval should be an action the agent takes”, with three decisions: retrieve or answer directly, what query to issue, and whether the result is good enough³⁵. Self-RAG (2023) trains a model that “adaptively retrieves passages on-demand”³⁶. CRAG (2024) goes part of the way: a separate, lightweight retrieval evaluator, not the generating model, grades what came back and can trigger other retrieval actions, including web search³⁷. Search-R1 (2025) trains the search behavior with reinforcement learning and reports relative gains of 41% and 20% over RAG baselines on seven question-answering datasets, for two Qwen2.5 models of 7 and 3 billion parameters³⁸.

Memory follows this same pattern. MemGPT (2023) moves data between the model’s context and external storage “via function calls that are generated by the LLM processor”³⁹. Letta’s core memory blocks “can be managed by the agent itself or by other agents” and “remain pinned to the agent’s context window”⁴⁰. AgeMem, a 2026 paper, “exposes memory operations as tool-based actions” and lets the agent decide what to store, retrieve, update, summarize, or discard⁴¹. A CMU lecture sums it up: “Reads and writes are function calls the agent issues itself”²².

A memory write is a write. It changes state that a later turn, or a later session, will read and trust. Ask the four questions about it, just like any other tool.

So far the model has decided which tool to call. It does not have to. Anthropic draws the line: “Workflows are systems where LLMs and tools are orchestrated through predefined code paths”⁴². “Agents, on the other hand, are systems where LLMs dynamically direct their own processes and tool usage, maintaining control over how they accomplish tasks”⁴². Stanford asks the same question in its first lecture, “Who Decides the Steps?”⁷. In a workflow, its slide says, “code fixes the steps”, as in Agentless and AlphaCode 2; in an agent, the model decides them, as in SWE-agent⁷.

Both are compound AI systems, which a group of researchers writing on Berkeley’s AI research blog defined in 2024 as systems that tackle tasks “using multiple interacting components, including multiple calls to models, retrievers, or external tools”⁴³. They framed the design question this way: should the “control logic” be written in traditional code, or “be driven by an AI model (e.g. LLM agents that call external tools)?”⁴³. Anthropic’s advice is to start small: “we recommend finding the simplest solution possible, and only increasing complexity when needed”⁴².

Nothing forces one answer for a whole system. You can fix some steps in code and let the model choose others. When the model does choose, the shape of its tools matters. SWE-agent’s interface for a model user “offers a small set of simple actions for viewing, searching through and editing files” instead of a raw Linux shell⁴⁴. Its authors report that interfaces tailored to language models “outperform existing user interfaces (UIs) designed for human users, such as the Linux shell”⁴⁴. With GPT-4 Turbo in 2024 it solved 12.47% of 2,294 SWE-bench tasks, against a previous best of 3.8% for a non-interactive, retrieval-augmented system; that gap mixes the interface with interaction itself, so it is not a measure of the interface alone⁴⁴. Those are 2024 models; the lasting point is that the interface you hand the model changes what it can do.

Put the chapter away and try these without looking.

1. Choose a tool from your own work or from your Studio task. Identify its three layers: what the model reads, what runs and with which key, and what knowledge it needs that was not written into the label.
2. Ask that tool the four questions: does it read or write, what happens if it runs twice, whose keys does it use, and who wrote the contract and the result. If you cannot answer, note what information you would need to find.
3. In one sentence, explain why writing “never do X” in a prompt is different from the harness refusing X.