| name | tool-debugging-limits |
| description | Tool/MCP debugging escalation protocol — when a tool isn't working, stop fast, notify {{PARENT_1}}, and move on. Prevents context destruction and token waste. Use when agent says "tool not found", "MCP not available", "Playwright not working", "command failed", "trying to install", "debugging tool", or any repeated tool failure pattern. |
Tool Debugging Limits Skill
When a tool, MCP server, or environment dependency isn't working, agents MUST follow this escalation protocol. Never burn context trying to fix tool issues inline.
The Rule (from {{PARENT_1}}, 2026-05-12)
"You should never have to run a bunch of PowerShell scripts to get something to work. If it doesn't work, we gotta move on. It eats away at my productivity and your token use."
Protocol
Step 1: Try the Tool (2-3 Attempts Max)
- Attempt the tool/MCP call normally
- If it fails, try ONE reasonable alternative (different syntax, different args)
- If it fails again, try ONE more time with a basic sanity check
- That's it. 3 attempts maximum.
Step 2: Notify {{PARENT_1}}
Send a Telegram (chat_id: {{TELEGRAM_PARENT_1}}, with speak parameter) explaining:
- What tool/MCP you were trying to use
- What you were trying to accomplish
- That it's not available/working
- That you're moving on
Example: "Hey, Playwright MCP isn't available in this session. I was trying to visually verify the blueprint sticky sidebar. Moving on to the next task — this might be a gap you need to fix."
Step 3: Move On
- Continue with other work immediately
- Do NOT keep trying different approaches to make the tool work
- Do NOT install packages, run setup scripts, or try to bootstrap the tool yourself
Step 4 (Optional): Delegate Debugging
If the tool issue is worth investigating:
- Launch a separate throwaway agent (
task tool, agent_type: "task") to debug
- The throwaway agent can burn its own context without affecting your working state
- Your primary agent stays clean and productive
What Counts as "Tool Not Working"
| Situation | Action |
|---|
MCP tool not found in tool_search_tool_regex | Notify {{PARENT_1}}, move on |
| Tool returns errors on 2-3 tries | Notify {{PARENT_1}}, move on |
| Tool requires install/setup not already done | Notify {{PARENT_1}}, move on |
| Tool works but gives unexpected results | Try 2-3 variations, then notify |
| Tool available but slow/timing out | Try once more with longer timeout, then notify |
Anti-Patterns (NEVER Do These)
- ❌ Running 5+ PowerShell commands trying to find/install/fix a tool
- ❌ Trying to run tools directly via shell when MCP isn't available (e.g., Playwright via PowerShell instead of MCP)
- ❌ Debugging tool issues inside a working agent with valuable context
- ❌ Silently spinning on a broken tool without telling {{PARENT_1}}
- ❌ Installing npm packages, pip packages, or other dependencies to make a tool work
- ❌ Searching for tool binaries across the filesystem
- ❌ Trying multiple different tool names hoping one works
Correct Patterns
- ✅ Try tool 2-3 times → doesn't work → Telegram {{PARENT_1}} → move on
- ✅ Delegate tool debugging to a throwaway agent if investigation is needed
- ✅ Use alternative approaches that DON'T require the broken tool (e.g., if Playwright isn't available, describe what needs visual verification and ask {{PARENT_1}} to check)
- ✅ Create a task for {{PARENT_1}} to fix the tool gap:
add_task(title="Fix [tool] availability", surface="human", priority="high")
Scope
ALL agents, ALL tool types. This applies to:
- MCP servers (Playwright, Exa, Perplexity, {{EMPLOYER_PARENT}} MCP, etc.)
- CLI tools (gh, git, npm, etc.)
- Extensions (action-tracker, cron-scheduler, etc.)
- Any external dependency an agent tries to use
Playwright-Specific Rules
Playwright is a common failure point. Specific rules:
- Always use Playwright via MCP tools — never try to run Playwright directly via PowerShell/Node scripts
- If Playwright MCP isn't available, tell {{PARENT_1}} — it's a session-level gap he needs to fix
- For visual verification without Playwright: describe what to check and ask {{PARENT_1}} to look at the preview URL
