| name | tool-guard |
| description | Before calling a tool, validate the arguments; after it returns, verify the output actually did what you intended before acting on it. Use on destructive or stateful tool calls (writes, deletes, deploys, API mutations, shell) and when chaining tool outputs. Cuts the tool-misuse failures that dominate agent breakage. Trigger with /tool-guard or "check this tool call", "verify the command", "did that actually work". |
| version | 0.1.0 |
| user-invocable | true |
| metadata | {"emoji":"🧰"} |
tool-guard
Tool misuse, wrong arguments, misread output, unnoticed errors, is the most common proximate cause of agent failure in production. This skill puts a pre-check before the call and a post-check after it.
Why this exists (evidence)
- Tool misuse / malformed tool calls account for roughly 31% of agent production failures (2024-2025 deployments), ahead of context drift and hallucination cascades.
- Classic failure shapes: agent "runs the tests" but misconfigures the runner and reads a pass that never executed; applies a patch that did not apply; fixes a symptom from a misread stack trace.
When to use
- Destructive / stateful calls: file writes & deletes,
git push --force, deploys, DB writes, API mutations, shell commands with side effects.
- Whenever the NEXT step depends on a previous tool's output being correct.
- Skip for trivial read-only calls where a wrong arg is harmless.
Pre-call check (before executing)
- Right tool? Is this the correct tool for the goal, or a near-miss?
- Args valid? Required fields present, correct types, paths/IDs real (not assumed). Resolve placeholders.
- Blast radius. What does this change/delete/send? If destructive or irreversible, confirm with the user (recovery-first).
- Idempotent? Will a retry double-apply? If so, guard it.
Post-call check (after it returns)
- Read the WHOLE result, including exit code / status, not just the happy line. A 0-length result or a warning is a signal.
- Did it do the thing? Verify the effect independently when it matters: file actually changed, tests actually ran (count assertions), deploy actually live, row actually written. Do not infer success from absence of an error.
- Error = stop. On error/ambiguous output, do not chain forward on a guess. Diagnose or surface it.
Verdict: PROCEED (validated + verified) / FIX (bad args -> correct and re-call) / STOP (error or unverifiable effect -> diagnose / ask).
Composes with
adversarial-verify: independent confirmation that a change works.safety-net: reversible checkpoints around edits (rollback if a guarded call goes wrong).mcp-warden: vet the tool/MCP itself before trusting its calls.
Honest limits
- Discipline + checklist, not a runtime sandbox. It reduces misuse; it does not prevent a tool that is itself broken.
- Over-applying to trivial reads wastes turns; scope to stateful/destructive/ chained calls.
