# Tool-banking template A copy-pasteable kit for agents (or people) that write their own tools and want to reuse them forever instead of rebuilding them every session. Two parts: 1. The `TOOL_` registry row. Fill one out every time you build something reusable. 2. The "build once, reuse forever" gotcha checklist. Run it before you save, and again before you build anything new. The whole point: one-time reasoning becomes permanent capability. The hard part of autonomous work is figuring out HOW. Bank the figuring-out, not just the result. --- ## Part 1: the registry row Save this as one entry in your shared memory (a database row, a markdown file, a wiki page, whatever your fleet reads). Use a predictable, greppable key so a future session can find it without already knowing it exists. Key convention: TOOL__ - AREA = the domain or mode that owns it (e.g. SCRAPE, PARSE, IMAGE, REPORT). - NAME = a short, specific handle for the one job it does. - Example keys: TOOL_SCRAPE_VENDOR_A, TOOL_PARSE_MONTH_ABBREV, TOOL_IMAGE_AERIAL. One tool per row. Resist the urge to build a single god-tool. A dozen small, individually documented tools beat one clever function nobody fully understands. Copy everything below this line for each tool you bank. ========================= ### TOOL__ **Title:** **Summary:** **Status:** active | deprecated | experimental **Owner / origin:** --- **Exact invocation.** The literal command, with argument order. Not "call it with the relevant parameters." A future agent should be able to copy, paste, and run. run_.py # e.g. run_vendor_a.py **Inputs.** What it consumes. Be specific about format and source. - arg1: - arg2: - arg3: **Outputs.** Precisely what it writes back. Which tables, which files, which keys. A tool that silently does I/O is a tool nobody trusts enough to reuse. - writes: - side effects: **Dependencies.** What has to be installed or available first. Pin versions if it matters. - - --- **THE GOTCHA (key insight).** The single most important field. The one-line, non-obvious thing that made this work. This is the distilled output of the original expensive reasoning. It is the part you are really banking. KEY INSIGHT: Good gotchas sound like: - The data only renders after JavaScript runs, so a plain fetch returns an empty shell. Use a headless browser and wait for the target node. - This source hides content in CSS-collapsed DOM nodes, so the visible text is incomplete. Query the DOM directly instead of reading rendered text. - This platform paginates through a non-obvious event mechanism, not query params. - This source abbreviates month names, so a naive date parser drops half the rows. - Download the file over plain HTTP. The browser's download interception fails here. --- **Changelog.** Tools are living code, not fossils. Date every change at the bottom. - YYYY-MM-DD Created. - YYYY-MM-DD --- **The code.** Paste the complete, runnable code below. Not a description of it. The actual thing, plus anything needed to run it. A tool you cannot run from this entry is a tool that will get rebuilt. ``` ``` End of registry row. ==================================================== --- ## Part 2: the "build once, reuse forever" gotcha checklist ### Before you build anything new: shop the library first Run your lookup query at the start of every session, before any expensive work. Example for a database-backed brain: ```sql SELECT file_key, title, summary FROM brain WHERE file_key LIKE 'TOOL_%' ORDER BY updated_at DESC; ``` The attached rule is blunt: if a tool exists for your task, use it. Do not rebuild. If it needs improving, improve it and log the change. That one query is the whole compounding engine. It turns a pile of scripts into a library the fleet shops before spending tokens. - [ ] I ran the lookup query before starting. - [ ] I read the summaries and confirmed no existing tool covers this. - [ ] If one is close, I extended it and updated its changelog instead of starting over. ### Decide: bank it or let it go Bank it if ANY of these are true: - [ ] Reusable across entities, sources, or runs. - [ ] Encodes a non-obvious technique (it has a real gotcha). - [ ] Re-deriving it would be expensive (it turned a multi-hour slog into a quick run). Do NOT bank it if: - [ ] It is genuinely a one-off: a throwaway transform for a single record. - [ ] It is glue specific to one task that will never recur. The test: would a future session, on a different case, want this? If yes, it is a tool. If no, it is a scratch script. When in doubt, lean toward banking, but write a summary good enough that the next session can decide in five seconds whether to open it. Watch for over-banking. A library full of hyper-specific scripts nobody calls again is just clutter you read past every session. A clean library is one the fleet trusts. ### Before you save: the entry is not done when the code works A banked tool is done when the entry records all of this: - [ ] **Exact invocation** with literal argument order. Copy-paste-and-go. - [ ] **Inputs and outputs** stated precisely, including every side effect and what tables or files it touches. - [ ] **Dependencies** listed, with versions where they matter. - [ ] **The gotcha** written as one plain sentence. If you cannot state the key insight, you probably do not understand the tool well enough to bank it yet. - [ ] **Changelog** started with a dated "Created" line. - [ ] **The complete runnable code** pasted in, not described. - [ ] **A greppable key** following the TOOL__ convention. - [ ] **A scannable summary** so the next session can triage it fast. ### Keep what vs. how separate - [ ] My quality standard says WHAT must exist and to what bar (the goal). - [ ] Each tool owns its own HOW (its method, free to improve). - [ ] I did not hardcode an implementation detail into a goal. "Every site needs an aerial image" is a goal. "Open this map, zoom to level 18, screenshot" is a how that the tool should be free to outgrow. Tools rot fastest when someone with authority freezes a how the tool has already moved past. --- ## Why this compounds The first time you touch a new source, it is slow: you are building the tools. Every pass after that is dramatically faster, because the tools already exist and the next session just shops the library and runs them. The toolbox only grows. The reasoning you paid for once keeps paying out across every future run. The system gets cheaper and faster the longer it runs, which is backwards from how most software ages, and exactly what you want.