diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 108341ed8e..25595b95b6 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -186,6 +186,14 @@ When adding query parameters to ETAPI endpoints (`apps/server/src/etapi/`), main
 
 **Auth note**: ETAPI uses basic auth with tokens. Internal API endpoints trust the frontend.
 
+### Adding New LLM Tools
+Tools are defined using `defineTools()` in `apps/server/src/services/llm/tools/` and automatically registered for both the LLM chat and MCP server.
+
+1. Add the tool definition in the appropriate module (`note_tools.ts`, `attribute_tools.ts`, `hierarchy_tools.ts`) or create a new module
+2. Each tool needs: `description`, `inputSchema` (Zod), `execute` function, and optionally `mutates: true` for write operations or `needsContext: true` for tools that need the current note context
+3. If creating a new module, wrap tools in `defineTools({...})` and add the registry to `allToolRegistries` in `tools/index.ts`
+4. Add a client-side friendly name in `apps/client/src/translations/en/translation.json` under `llm.tools.<tool_name>` — use **imperative tense** (e.g. "Search notes", "Create note", "Get attributes"), not present continuous
+
 ### Database Migrations
 - Add scripts in `apps/server/src/migrations/YYMMDD_HHMM__description.sql`
 - Update schema in `apps/server/src/assets/db/schema.sql`
diff --git a/CLAUDE.md b/CLAUDE.md
index 71a82f39f7..b0573cea0c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -151,6 +151,14 @@ Trilium provides powerful user scripting capabilities:
 - Create new package in `packages/` following existing plugin structure
 - Register in `packages/ckeditor5/src/plugins.ts`
 
+### Adding New LLM Tools
+Tools are defined using `defineTools()` in `apps/server/src/services/llm/tools/` and automatically registered for both the LLM chat and MCP server.
+
+1. Add the tool definition in the appropriate module (`note_tools.ts`, `attribute_tools.ts`, `hierarchy_tools.ts`) or create a new module
+2. Each tool needs: `description`, `inputSchema` (Zod), `execute` function, and optionally `mutates: true` for write operations or `needsContext: true` for tools that need the current note context
+3. If creating a new module, wrap tools in `defineTools({...})` and add the registry to `allToolRegistries` in `tools/index.ts`
+4. Add a client-side friendly name in `apps/client/src/translations/en/translation.json` under `llm.tools.<tool_name>` — use **imperative tense** (e.g. "Search notes", "Create note", "Get attributes"), not present continuous
+
 ### Database Migrations
 - Add migration scripts in `apps/server/src/migrations/`
 - Update schema in `apps/server/src/assets/db/schema.sql`