Tools, Actions & Environments

A tool is a function the model is allowed to ask for.

Strip away the mystique: a tool is an ordinary function in your codebase plus a description the model can read. The model never gets to run it. The model emits a request to run it; your harness decides whether and how to honor that request. A tool has exactly three parts:

• A name the model uses to refer to it (search_orders).
• A schema: the inputs it accepts, typed, so the model knows what arguments to produce ({order_id: string}).
• A description in natural language: what it does, when to use it, what it returns, and critically what it must not be used for.

# What the model is shown (the contract):
{
  "name": "issue_refund",
  "description": "Refund a paid order. Use ONLY after verifying the"
                 " order exists and was not already refunded. Max $200;"
                 " above that, escalate to a human instead.",
  "input_schema": { "order_id": "string", "amount_usd": "number" }
}

# What the harness actually runs when the model asks for it:
def issue_refund(order_id, amount_usd):
    if amount_usd > 200:           # enforce the limit in CODE,
        raise RefundTooLarge()    # not just in the description
    return payments.refund(order_id, amount_usd)

The single most important habit is in that last comment. The description tells the model the rule; the function enforces the rule. The model will sometimes ignore the description — it is a suggestion to a probabilistic system. The code is not a suggestion. Never rely on the model respecting a constraint that you could enforce in the tool itself.

The two kinds of action, and why the distinction is everything.

Every tool an agent can call falls into one of two categories, and almost every agent safety question reduces to which one you're dealing with:

• Read actions (sensors). They observe the environment without changing it: search_web, read_file, query_database (a SELECT), get_weather. The worst case of a wrong read action is a wasted turn and a misleading observation. Recoverable.
• Write actions (actuators). They change the environment: send_email, delete_file, execute_trade, deploy. The worst case of a wrong write action is a real-world consequence that already happened. Often not cheaply recoverable.

This maps directly onto the autonomy ladder from the previous entry: read actions can usually run at high autonomy because they're reversible; write actions are exactly the ones that should sit behind approval gates or hard code limits. A practical design rule that falls out: give an agent the smallest set of write tools the task genuinely requires, and prefer narrow tools over broad ones. refund_order(id) is far safer than run_sql(query) — the second can do anything, including things you never intended, and you cannot enforce policy on a tool whose capability is "arbitrary."

Tool descriptions are prompt engineering — usually the highest-leverage kind.

Newcomers spend hours tuning the system prompt and ignore the tool descriptions. This is backwards. The tool description is the model's only information about when and how to use a capability, and it's read at the exact moment the decision is made. A vague description produces a misbehaving agent no system prompt can fully fix.

Concretely, the difference between these two descriptions of the same function is the difference between a reliable agent and a flaky one:

WEAK:  "Searches the knowledge base."
       → Model calls it with vague queries, on the wrong
         turns, and over-trusts whatever comes back.

STRONG: "Full-text search over the product help-center
         articles ONLY (not pricing, not account data).
         Use when the user asks how a feature works. Pass
         a focused query of 2-6 keywords, not a sentence.
         Returns up to 5 article snippets ranked by
         relevance; snippets may be partial — open the
         full article before quoting policy."
       → Model knows scope, trigger, input shape, and
         the failure mode of the result.

The strong version encodes scope (what it does not cover), trigger (when to reach for it), input shape (what good arguments look like), and result caveats (don't over-trust a snippet). Every one of those is a behavior you would otherwise be chasing as a "model bug." It usually isn't a model bug; it's an underspecified tool.

The environment: where agents actually become dangerous.

The environment is everything the tools reach: the filesystem, the database, the customer's account, the public internet, a robot's surroundings. It is easy to obsess over the model and forget that the model only ever proposes — the environment is where consequences are real. Three properties of an environment determine how risky an otherwise-identical agent is:

• Reversibility. Can a wrong action be cheaply undone? A git working tree is highly reversible (you can reset). A sent email, a charged card, a deleted production table, a physical movement: not. The same agent is safe in a sandbox and dangerous in production solely because of the environment's reversibility.
• Observability. Does a tool result tell the agent the truth about what happened? If deploy() returns "ok" but the deploy actually half-failed, the agent's next decision is built on a lie. Agents are only as good as their observations; a noisy or deceptive environment breaks the loop's feedback.
• Adversariality. Can content the agent reads contain instructions aimed at the agent? An agent that browses the web or reads user-submitted tickets is reading text an attacker may have written. This is prompt injection, and it exists because the agent's "observations" and its "instructions" are the same channel — text in the context window. (The safety section treats this in depth; the conceptual point belongs here: an agent's environment is also an attack surface.)