Claude Code Custom Tool Mods: Give Claude New Tools

Claude Code custom tool mods give Claude new tools to call during a turn, such as a project-specific search, a lookup in your issue tracker, or a calculator for something your codebase cares about. The tool is written in JavaScript inside the mod and runs in Claude Code, so there is no separate server process to start.

How do Claude Code custom tool mods add a tool?#

A mod calls $.tool.register(...) with a name and a description that Claude reads, plus the input it accepts. When Claude decides to use the tool, the call passes through the tool.call event like any built-in tool, and the mod answers it by returning { result }. $.tool.list() shows what is available and $.tool.call() lets a mod invoke a tool itself.

Two other events matter here. tool.describe fires when a tool's description is first sent to Claude; a mod can rewrite the text or mark the tool as deferred so it does not take up context until needed. agent.offer and $.agent.register do the same job for subagent types. The API reference documents the $.tool and $.agent methods.

What should you check before installing one?#

A tool mod shows Adds commands/tools. The rest of its badges tell you what the tool can reach. A tool that queries a web API shows Network; one that searches files shows Reads files; one that runs a linter shows Runs commands. Because Claude decides when to call the tool, those capabilities can be used in any turn, not only when you ask, so review them as if Claude had direct access.

Check how errors are reported too. A good tool returns a clear error message as its result instead of throwing, so Claude can recover.

Tool mods versus MCP servers#

MCP servers are the standard way to give Claude tools, and they work across many clients. A tool mod is narrower: it only works in Claude Code, but it needs no install step beyond the plugin, starts with the session, and can share state with the rest of the mod, for example a status line that shows how often the tool was used.