## Definition **Tool use** (a.k.a. function calling) is the capability of an LLM to choose, at generation time, between producing a normal text response and invoking a named external function with structured arguments. It is the bridge from "language model" to "agent that interacts with the world." ## The Protocol The model is told, in its prompt or via a tool schema: ```jsonc { "name": "search_web", "description": "Search the web for a query and return top results.", "input_schema": { "type": "object", "properties": { "query": { "type": "string", "description": "The search query." } }, "required": ["query"] } } ``` The model can choose, mid-response, to emit a structured tool call: ```jsonc { "type": "tool_use", "name": "search_web", "input": { "query": "..." } } ``` The host runs the tool, returns the result, and the model continues with the observation in context. ## Why It Matters - **Grounds the model in real data.** Numbers, dates, APIs — look them up rather than recall. - **Enables action.** Write files, send emails, execute code, query databases. - **Mitigates [[Hallucination]].** A search result is better than a memorised fact. - **Underpins MCP.** [[Model Context Protocol]] is, at the protocol level, standardised tool use. ## Designing Good Tools Anthropic's *Writing effective tools for AI agents* gives the canonical guidance: 1. **Clear, narrow purpose.** One tool, one job. 2. **Self-explanatory names.** `search_web`, not `tool_5`. 3. **Schemas that match the model's intuition.** Use familiar parameter names and types. 4. **Useful errors.** When a call fails, the error message should help the model recover. 5. **Idempotent where possible.** Repeated calls should be safe. ## Common Tool Surfaces in Agentic CLIs | Tool | Purpose | | ---------- | ---------------------------------------- | | Read | Read file contents | | Edit/Write | Modify or create files | | Bash | Execute shell commands | | Grep/Glob | Search the filesystem | | WebSearch | Internet search | | WebFetch | Retrieve and parse a URL | | MCP tools | Arbitrary external systems via [[MCP Server]] | ## Failure Modes - **Wrong tool, wrong moment.** Model picks the right shape but the wrong tool. - **Argument hallucination.** Plausible-looking but invalid arguments. - **Tool result hallucination.** Model "imagines" a tool result rather than calling and reading. Spot it by checking the call actually ran. ## Related - [[AI Agent]] - [[ReAct Pattern]] - [[Model Context Protocol]] - [[MCP Server]] - [[Hallucination]]