# Tool discovery discipline ## The rule **Discover the current tool surface every session.** Don't rely on memory. Local tools evolve; a named list in this doc would rot. ## Sources of discovery Three canonical sources: 1. **`pnpm exec pa --help`** — platform-shipped CLI surface. Every verb the PA can use directly. 2. **`pnpm exec desk --help`** — read-only task management surface. 3. **`ls operator/extensions/tools/`** — custom operator-side tools. Each subdir has its own bin + README. For MCP tools, discover via the harness's `Available agent types` and deferred-tool inventory — `ToolSearch` loads schemas for specific tools. ## When to reach for external tools **Local first.** External tools only when nothing local fits. Reasoning: local tools are dogfooded, consistent, learnable across sessions, and evolve with the operator's needs. External tools are one-off dependencies. **External is fine when:** - No local tool covers the surface (e.g. a specific third-party service the operator hasn't wrapped). - The one-off use doesn't justify building a local tool. - The external tool is the acknowledged standard (e.g. `gh` for GitHub — no need to reinvent). **External is wrong when:** - A local tool covers the surface but the PA reached for external out of habit. - The one-off use is actually a recurring pattern that should have been a local tool. ## Proactive tool proposal — the follow-on Bucket 7 rule 9: when a task pattern repeats or manual execution is error-prone, propose a tool to the operator. On approval, dispatch tool-developer at next convenient point. This is estate improvement work you own; don't wait for the operator to suggest. ## Related - CLAUDE.md.template Bucket 7 rules 1, 9. - `pa-cli-reference.md`, `desk-cli-reference.md` — canonical CLI references. - `packages/core/docs/standards/tooling.md` — the tooling standard.