Agent Tool Contracts

An agent tool is an API boundary, not a prompt convenience. Every tool needs a typed input schema, a narrow execution policy, and a result object that records provenance.

The Problem

LLM agents fail badly when tools accept vague strings and return unstructured text. The model cannot distinguish stale search results from fresh ones, allowed paths from forbidden paths, or recoverable tool errors from final evidence. Worse, a prompt-injected page can ask the agent to call another tool unless the execution layer enforces policy outside the model.

The Pattern

WRONG

def run_tool(name: str, args: str) -> str:
    if name == "read_file":
        return open(args).read()
    if name == "search":
        return web_search(args)
    raise ValueError(name)