Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 39 ยท Tools and Function Calling

Executing Tool Calls Safely

Run model-requested tools without regret: allowlists, argument validation, permission levels, human approval, timeouts, output limits and dry runs in Python.

When a model asks for a tool call, you are about to run code on its behalf, based on text that may be mistaken, manipulated by a web page the agent read, or simply wrong. Executing tools is where an agent can do real damage: delete files, send emails, spend money. Safe execution is therefore not an add-on. It is the dispatcher's main job. This lesson builds one, layer by layer.

The safety layers

flowchart TD
  C["Tool call from model"] --> A{"Tool in allowlist?"}
  A -- no --> R1["Reject"]
  A -- yes --> V{"Arguments valid?"}
  V -- no --> R2["Reject with message"]
  V -- yes --> P{"Permission level"}
  P -- "read-only" --> X["Execute with timeout"]
  P -- "changes data" --> H{"Human approves?"}
  H -- no --> R3["Reject"]
  H -- yes --> X
  X --> L["Limit and sanitize output"]
  L --> O["Return observation"]

Every call passes through the same checkpoints before and after execution.

  1. Allowlist. Only registered tools run. Never look up a tool by building a name from model text with getattr or eval.
  2. Validation. Check arguments against the schema (see tool schemas), plus domain rules such as "path must stay inside the workspace".
  3. Permission level. Classify tools: read-only, reversible write, irreversible or costly. The higher the level, the more control.
  4. Approval. Irreversible actions wait for a human yes.
  5. Timeout and limits. A tool must not hang the agent or flood its context.
  6. Output handling. Truncate, label and strip secrets from results.

A tool registry with metadata

Instead of a bare dictionary, store each tool with its function and its risk level, so the dispatcher can enforce policy uniformly.

Python A dispatcher with permission levels

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The dangerous call never reached the function. The model's request was treated as a request, never as an order. In a real system approve would show the action and its arguments to a person, or check a policy.

Guard arguments, not just names

A file tool with a valid name can still be misused if the path escapes the area it is meant to use. Always normalize and check paths, URLs and identifiers.

Python Keep file paths inside a workspace

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

On a real filesystem use Path.resolve() so symbolic links are followed before the check. Other classic arguments to guard: URLs (block internal addresses to avoid server-side request forgery), SQL (use parameterized queries, read-only database users), and shell commands (avoid them; if unavoidable, use a fixed list of commands).

Timeouts and output limits

A tool that hangs freezes the whole agent. A tool that returns 50 MB floods the context. Both are prevented in the dispatcher, not in each tool.

Python
# Read-only: timeout with a worker thread or process (threads cannot be killed,
# so for untrusted code prefer a subprocess or a container)
from concurrent.futures import ThreadPoolExecutor, TimeoutError as FutureTimeout

def run_with_timeout(fn, kwargs, seconds=10):
    with ThreadPoolExecutor(max_workers=1) as pool:
        future = pool.submit(fn, **kwargs)
        try:
            return future.result(timeout=seconds)
        except FutureTimeout:
            return f"ERROR: tool timed out after {seconds}s"

def limit_output(text, max_chars=2000):
    if len(text) <= max_chars:
        return text
    return text[:max_chars] + f"\n[truncated: {len(text) - max_chars} more characters]"

Dry runs and undo

A powerful pattern for write tools is a dry run: the tool computes and returns what it would do, the human or a checker looks at it, and only then does the real call happen. Another is undo: prefer actions that can be reversed (move to trash instead of delete; create a draft instead of sending).

Python Dry run first, commit second

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Principle of least privilege

Give the agent the smallest set of tools and permissions that do the job. A support agent that only reads orders cannot refund them, whatever text it is tricked into producing. Use separate credentials for the agent, scoped narrowly and easy to revoke, and never expose your own keys. Remember that text the agent reads (web pages, emails, documents) is untrusted input that can contain instructions aimed at the model, so safety must rest on code-level limits, not on the model "knowing better".

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why look up tools in an explicit registry instead of calling globals()[name] or eval?

    Building function names from model text would let it reach any function in the program.
  2. 2. What should happen with an irreversible tool call such as deleting data?

    High-impact actions deserve an extra checkpoint outside the model's control.
  3. 3. What does a dry run provide?

    Reviewing the preview lets a person or a check approve before anything changes.
  4. 4. Why is least privilege important for agents?

    What an agent cannot do cannot go wrong, however it is prompted or tricked.

Summary

  • Treat tool calls as requests. Check allowlist, arguments, permission level and approval.
  • Guard arguments such as paths, URLs and SQL, not just tool names.
  • Enforce timeouts and output limits centrally in the dispatcher.
  • Prefer dry runs and reversible actions; require approval for irreversible ones.
  • Apply least privilege and assume anything the agent reads may be hostile.

Next: Tool Errors, Retries and Fallbacks