From 92b0c6b99cbfac0596ed6fe88053f1dd5c88d92a Mon Sep 17 00:00:00 2001
From: Simon Willison <swillison@gmail.com>
Date: Tue, 13 May 2025 17:07:11 -0700
Subject: [PATCH] Basic tool usage docs using --functions

Refs #1022, #995, #1016
---
 docs/usage.md | 42 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/docs/usage.md b/docs/usage.md
index df3f0e3..693087e 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -120,6 +120,48 @@ cat llm/utils.py | llm -t pytest
 ```
 See {ref}`prompt templates <prompt-templates>` for more.
 
+(usage-tools)=
+### Tools
+
+Many models support the ability to call {ref}`external tools <tools>`. Tools can be provided {ref}`by plugins <plugin-hooks-register-tools>` or you can pass a `--functions CODE` option to LLM to define one or more Python functions that the model can then call.
+
+```bash
+llm --functions '
+def multiply(x: int, y: int) -> int:
+    """Multiply two numbers."""
+    return x * y
+' 'what is 34234 * 213345'
+```
+Add `--td/--tools-debug` to see full details of the tools that are being executed:
+```bash
+llm --functions '
+def multiply(x: int, y: int) -> int:
+    """Multiply two numbers."""
+    return x * y
+' 'what is 34234 * 213345' --td
+```
+Output:
+```
+Tool call: multiply({'x': 34234, 'y': 213345})
+  7303652730
+34234 multiplied by 213345 is 7,303,652,730.
+```
+Or add `--ta/--tools-approve` to approve each tool call interactively before it is executed:
+
+```bash
+llm --functions '
+def multiply(x: int, y: int) -> int:
+    """Multiply two numbers."""
+    return x * y
+' 'what is 34234 * 213345' --ta
+```
+Output:
+```
+Tool call: multiply({'x': 34234, 'y': 213345})
+Approve tool call? [y/N]:
+```
+The `--functions` option can be passed more than once, and can also point to the filename of a `.py` file containing one or more functions.
+
 (usage-extract-fenced-code)=
 ### Extracting fenced code blocks