Tool Discovery#

Where the SDK looks for installed tools on disk.

Goal#

Understand the resolution order and on-disk layout so you can control where tools are loaded from.

Resolution order#

The SDK searches for a tool in this order:

1. AGENTPM_TOOL_DIR (env var) – Highest priority override.
2. Project-local: ./.agentpm/tools – Typically created by agentpm install.
3. User-local: ~/.agentpm/tools – Shared across projects for convenience.

You can also override per call:

• Node: load(spec, { toolDirOverride: "/path/to/tools" })
• Python: load(spec, tool_dir_override="/path/to/tools")

Directory layout#

Each tool is stored under an namespace/name/version path:

.agentpm/
  tools/
    @zack/summarize/
      0.1.0/
        agent.json
        dist/...
        prompts/...
        (other packaged files…)

• The SDK reads the agent.json inside the version folder to determine how to execute the tool.
• Multiple versions can coexist under the same tool directory; the spec you pass to load() picks the version.