diff --git a/README.md b/README.md
index cb1fdda..96eee44 100644
--- a/README.md
+++ b/README.md
@@ -184,6 +184,7 @@ See also [the llm tag](https://simonwillison.net/tags/llm/) on my blog.
 * [Tools](https://llm.datasette.io/en/stable/tools.html)
   * [How tools work](https://llm.datasette.io/en/stable/tools.html#how-tools-work)
   * [LLM’s implementation of tools](https://llm.datasette.io/en/stable/tools.html#llm-s-implementation-of-tools)
+  * [Tips for implementing tools](https://llm.datasette.io/en/stable/tools.html#tips-for-implementing-tools)
 * [Schemas](https://llm.datasette.io/en/stable/schemas.html)
   * [Schemas tutorial](https://llm.datasette.io/en/stable/schemas.html#schemas-tutorial)
     * [Getting started with dogs](https://llm.datasette.io/en/stable/schemas.html#getting-started-with-dogs)
diff --git a/docs/tools.md b/docs/tools.md
index f651704..6cad0c8 100644
--- a/docs/tools.md
+++ b/docs/tools.md
@@ -22,4 +22,12 @@ Tool functions should include a docstring that describes what the function does.
 
 The Python API can accept functions directly. The command-line interface has two ways for tools to be defined: via plugins that implement the {ref}`register_tools() plugin hook <plugin-hooks-register-tools>`, or directly on the command-line using the `--functions` argument to specify a block of Python code defining one or more functions - or a path to a Python file containing the same.
 
-You can use tools {ref}`with the LLM command-line tool <usage-tools>` or {ref}`with the Python API <python-api-tools>`.
\ No newline at end of file
+You can use tools {ref}`with the LLM command-line tool <usage-tools>` or {ref}`with the Python API <python-api-tools>`.
+
+## Tips for implementing tools
+
+Consult the {ref}`register_tools() plugin hook <plugin-hooks-register-tools>` documentation for examples of how to implement tools in plugins.
+
+If your plugin needs access to API secrets I recommend storing those using `llm keys set api-name` and then reading them using the {ref}`plugin-utilities-get-key` utility function. This avoids secrets being logged to the database as part of tool calls.
+
+<!-- Uncomment when this is true: The [llm-tools-datasette](https://github.com/simonw/llm-tools-datasette) plugin is a good example of this pattern in action. -->
\ No newline at end of file