tool-protocol

name	tool-protocol
description	Find, build, or adapt automation tools following the Tool Protocol decision tree
compatibility	>=1.4

Tool Protocol

Skill metadata: version "1.1"; license MIT; tags [tools, automation, scripting, toolbox, plugins, mcp-apps]; compatibility ">=1.4"; recommended tools [codebase, editFiles, runCommands, fetch].

When a task requires automation or a repeatable utility, follow this decision tree before writing anything ad-hoc.

When to use

• User asks to "build a tool", "create a script", or "automate" something
• You need a repeatable utility and want to check if one exists
• Evaluating whether to save a script to the toolbox

Decision tree

Need a tool for task X
 │
 ├─ 1. FIND — check .copilot/tools/INDEX.md
 │     ├─ Exact match  → USE IT directly
 │     ├─ Close match  → ADAPT (fork, rename, note source in comment at top of file)
 │     └─ No match     → ↓
 │
 ├─ 1.5 BUILT-IN — check VS Code's native tool capabilities
 │     ├─ Use the exact tool names surfaced by the active runtime; identifiers differ across clients
 │     ├─ Symbol/reference lookup → find all references, implementations, callers of a symbol
 │     ├─ Problems/errors lookup  → get compile or lint errors for a file or the entire workspace
 │     ├─ Web fetch               → fetch web pages, docs, or API references
 │     ├─ Semantic search         → natural language search across the codebase
 │     ├─ Text/regex search       → fast exact-match or pattern search in workspace files
 │     ├─ Sufficient → USE built-in tool
 │     └─ Not sufficient → ↓
 │
 ├─ 1.6 PLUGIN TOOLS — check installed agent plugins for contributed tools
 │     ├─ Search Extensions view with `@agentPlugins`
 │     ├─ Inspect plugin docs for commands, skills, hooks, and MCP servers
 │     ├─ Suitable existing capability → USE plugin-contributed capability
 │     └─ No suitable capability → ↓
 │
 ├─ 2. SEARCH online (try in order)
 │     a. MCP server registry  github.com/modelcontextprotocol/servers
 │     b. GitHub search        github.com/search?type=repositories&q=<task>
 │     c. Awesome lists        awesome-cli-apps · awesome-shell · awesome-python · awesome-rust · awesome-go
 │     d. Stack registry       npmjs.com / pypi.org / crates.io / pkg.go.dev
 │     e. Official CLI docs    git · docker · gh · jq · ripgrep · sed · awk (built-ins first)
 │     ├─ Found something usable → evaluate fit, adapt as needed, note source
 │     └─ Nothing applicable → ↓
 │
 ├─ 2.5 COMPOSE — can this be assembled from 2+ existing toolbox tools via pipe or import?
 │     ├─ Yes → compose; document the pipeline; save to toolbox if reusable
 │     └─ No  → ↓
 │
 └─ 3. BUILD — write the tool from scratch
          - Follow §4 coding conventions and §3 LOC baselines
          - Single-purpose: one tool, one job; compose via pipes or imports
          - Accept arguments instead of hardcoding project-specific paths
          - Required inline header at the top of every built or saved tool:
            # purpose:  <what this tool does — one precise sentence>
            # when:     <when to invoke it | when NOT to invoke it>
            # inputs:   <argument list with types and valid values>
            # outputs:  <what it returns — type and structure; include MCP Apps output when interactive UI is beneficial>
            # risk:     safe | destructive
            # source:   <url or "original" if built from scratch>
          │
          └─ 4. EVALUATE reusability
                ├─ ≥ 2 distinct tasks in this project would benefit → SAVE to toolbox
                │   a. Place file in .copilot/tools/<kebab-name>.<ext>
                │   b. Add a row to .copilot/tools/INDEX.md (see format below)
                └─ Single-use / too project-specific → use inline only; do not save

Toolbox

.copilot/tools/ is created on first tool save (no setup step required). Contents:

Files: INDEX.md (catalogue) · *.sh · *.py · *.js/*.ts · *.mcp.json

INDEX.md row format:

Tool	Lang	What it does	When to use	Output	Risk
count-exports.sh	bash	Count exported symbols per file	API surface audits	symbol counts to stdout	safe
summarise-metrics.py	python	Parse metrics baselines and print trends	Kaizen review sessions	trend table to stdout	safe

Tool quality rules

Naming — Verb-noun kebab phrase (count-exports, sync-schema), not nouns or generic labels.

Risk tier: safe (read-only/idempotent, invoke freely) | destructive (deletes/overwrites/writes remote; must confirm with user).

Other rules: idempotent where possible; no hardcoded paths/names/secrets (accept arguments); retire unused tools with [DEPRECATED] in INDEX.md (W1); LOC ≤ 400; prefer targeted reads over raw dumps; prefer MCP Apps output for interactive workflows.

Subagent tool use

Subagents inherit this protocol. A subagent may build or adapt tools independently but must flag toolbox saves to the parent agent for confirmation.