Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Tool

Pattern

A reusable solution you can apply to your work.

Understand This First

Context

At the agentic level, a tool is a callable capability exposed to an agent. Tools are what transform a language model from a text generator into something that can interact with the real world: reading files, writing code, running commands, searching the web, querying databases, or calling APIs.

Without tools, an agent is a chatbot: it can discuss code but not touch it. With tools, it becomes a collaborator that can inspect, modify, test, and iterate. The set of tools available to an agent defines the boundary of what it can do.

Problem

How do you give a model the ability to take actions in the real world while keeping those actions safe, predictable, and useful?

A model generates text. But fixing a bug requires reading a file, understanding the error, editing the code, and running a test. Each of those steps requires a capability the model doesn’t inherently have. Tools provide those capabilities, but each tool also introduces a surface for mistakes, misuse, or unintended consequences.

Forces

  • Capability: more tools make the agent more capable, but also increase the chance of unintended actions.
  • Complexity: each tool adds to the model’s decision space, potentially confusing it about which tool to use when.
  • Safety: some tools (file deletion, shell commands, network requests) can cause real damage if misused.
  • Discoverability: the agent must know what tools are available and what they do, all within its finite context window.

Solution

Design tools as focused, well-described capabilities that do one thing clearly. A good tool has:

A clear name that communicates its purpose. read_file is better than fs_op. run_tests is better than execute.

A precise description that tells the model when and how to use it. The model selects tools based on their descriptions, so clarity here directly affects quality of use.

Bounded scope. A tool that reads a file is safer and more predictable than a tool that executes arbitrary shell commands. When you must expose powerful tools, pair them with approval policies that require human confirmation for dangerous operations.

Structured input and output. Tools that accept and return structured data (JSON, typed parameters) are easier for models to use correctly than tools that require free-form text parsing.

The harness manages the inventory of available tools and mediates between the model’s tool-call requests and the actual execution. Some tools are built into the harness (file read/write, shell access). Others are provided by external MCP servers that extend the agent’s capabilities dynamically.

Tip

When an agent has access to too many tools, it can spend time deliberating about which one to use or choose poorly. If you notice an agent picking the wrong tool for a task, consider whether the tool set is too broad. A focused set of well-described tools outperforms a sprawling catalog of vaguely described ones.

How It Plays Out

An agent is asked to fix a failing test. It uses a read_file tool to examine the test and the code under test, identifies the mismatch, uses a write_file tool to apply the fix, and uses a run_tests tool to verify the fix works. Each tool invocation is a discrete, reviewable step. The human can see exactly what the agent read, what it changed, and what it tested.

A team exposes a custom tool that queries their internal documentation wiki. When the agent encounters an unfamiliar internal API, it searches the wiki rather than guessing (and hallucinating). The tool is simple (it takes a search query and returns matching pages) but it eliminates an entire category of AI smells by grounding the agent in real documentation.

Example Prompt

“Add a tool to the MCP server that queries our Postgres database for order history. It should accept a customer_id and date range, return JSON, and never allow write operations. Write tests that verify it rejects SQL injection attempts.”

Consequences

Tools make agents practically useful. They transform theoretical capability into real productivity. Well-designed tools produce predictable, reviewable agent behavior.

The cost is the design and maintenance of the tool layer. Each tool must be implemented, documented, and kept working as the environment changes. Tools that are too permissive create safety risks. Tools that are too restrictive frustrate the agent and the user. Finding the right level of capability for each tool, and the right approval policy for each, is an ongoing calibration.

  • Enables: Agent — tools are what make an agent more than a chatbot.
  • Depends on: Harness (Agentic) — the harness manages tool access and execution.
  • Refined by: MCP (Model Context Protocol) — MCP standardizes how tools are discovered and invoked.
  • Uses: Approval Policy — dangerous tools require human approval before execution.
  • Related: Tool Poisoning – tools are the mechanism exploited by poisoning attacks.