Add MCP Tool

Scaffold a new tool handler that conforms to the project's handler signature (func (h *Handlers) HandleXxx(ctx, req, args XxxArgs)) and safety conventions.

Arguments

Parse $ARGUMENTS:

• $1 — snake_case tool name (required). Must start with talos_ (e.g. talos_drain_node).
• $2 — category, one of mutating | read (default read).

Derive {{ToolName}} = PascalCase of $1 with the talos_ prefix stripped (e.g. talos_drain_node → DrainNode).

If any required argument is missing, ask the user once for the missing value, then proceed non-interactively.

Key Steps

1. Validate name. Reject if $1 does not match ^talos_[a-z][a-z0-9_]*$.
2. Collision check. Use Glob to confirm internal/tools/<name>.go does not

exist. If it does, stop and report — do not overwrite.

1. Generate handler. Render references/handler-template.go.tmpl with

{{ToolName}}, {{tool_name}}, {{category}} substituted. Write to internal/tools/<name>.go.

1. Apply safety defaults. For mutating, inline confirm bool and

nodes []string on {{ToolName}}Args; set dry_run / preserve / graceful defaults from references/safety-defaults.md.

1. Register the tool. Grep for mcp.AddTool in internal/tools/ to

locate the registration site. Add the new entry in alphabetical order:

   mcp.AddTool(server, &mcp.Tool{Name: "{{tool_name}}"}, h.Handle{{ToolName}})

1. Generate test stub. Write internal/tools/<name>_test.go with one

happy-path test and (for mutating) a guards-enforcement test.

1. Format. Run gofmt -w internal/tools/<name>.go internal/tools/<name>_test.go.
2. Update inventory. Edit the tool-inventory tables in AGENTS.md and

README.md. Preserve alphabetical order.

Output

On success, print:

Created:   internal/tools/<name>.go
           internal/tools/<name>_test.go
Modified:  <registration-file>
           AGENTS.md  (tool inventory)
           README.md  (tool inventory)
Next:      make check
           invoke staff-reviewer  →  .claude/reviews/<change-id>/review.md
           commit  →  feat(tools): add <tool_name> handler [review:<change-id>]

On abort (name invalid, collision, template missing): print the reason and exit without writes.

References

• references/handler-template.go.tmpl — handler + args struct template patterned on internal/tools/lifecycle.go.
• references/safety-defaults.md — per-category default values (mirror of repo-root CLAUDE.md § Safety).