Free to read · no account needed

9 min · plugins

Debug broken tool calls

Goal: Debug MCP/plugin tool failures with a calm checklist—stop and keep the receipt before mash-retry.

Best for: when the model says the tool failed, timed out, or returned empty.

MCP (Model Context Protocol) is a common way apps expose tools to models. When a tool call breaks, read the error like a receipt: which tool, which argument, which message.

Beginners: copy the error text into a new chat and ask for a plain-language explanation—then fix one thing.

Broken tool calls are usually permissions, names, or stale servers—not “fix MCP/plugin tool failures with a calm checklist” Shrink the ask; read the error; retry one change at a time.

Why beginners skip this

Switching models when a tool call fails feels tidy—the real cause is permissions, schema, or path. Read the log first.

Step 1 — Capture the receipt

Stop when the tool name mismatches: list available tools, pick the closest read-only search—never invent a name.

Explain this tool error in plain words for a beginner.
Error:
[paste]
Say: what failed · likely cause (auth, args, network, permission) · first fix to try.
Example

Filled prompt

Tool call failed: "permission denied: calendar.write". I only wanted to list events. Write a debug checklist (6 steps) and a safer retry prompt that requests read-only list for next 7 days.

What good output looks like

  • Read/draft preferred over write for “fix MCP/plugin tool failures with a calm checklist”
  • Ask-every-time on leave-the-system tools
  • Kill-switch owner named
  • Pass/fail: dry-run only today

Step 2 — Binary-search the cause

Paste the full error (redacted) and ask how to fix; mashing retry leaves duplicate side effects.

Design a 4-step binary-search plan for this failure (one change per step).
Context: [paste]
Example

Filled prompt

Error: tool timeout 30s on drive.search; yesterday we widened write scope.
Run 6-step checklist once. Log error, hypothesis, one next test. No spam retry.

What good output looks like

  • Ask-every-time on leave-the-system tools
  • Kill-switch owner named
  • Pass/fail: dry-run only today
  • Read/draft preferred over write for “fix MCP/plugin tool failures with a calm checklist”

Step 3 — Fix instructions, not just the moment

If wrong args keep happening, put the correct call example into skill/agent instructions—do not only patch this session.

From this successful call, write a tiny “how to call this tool” example for our skill docs.
Success log: [paste]
Example

Filled prompt

Successful list(folder=AI-Sandbox) → docs example with correct args.
Context: live job for mcp-debug-broken-tool-calls — “fix MCP/plugin tool failures with a calm checklist” Keep never-invent / draft-only.

What good output looks like

  • Walks checklist once, top to bottom
  • Ties timeout to a scope or size hypothesis
  • One next test only—no spam retry
  • Log line with error text quoted

Save this card

Card: On tool failure: stop, keep the receipt, change one variable—no mash-retry. Keep this beside the tool; read before you start.

Before you start

Open the MCP connect screen. Prefer official/verified. For “fix MCP/plugin tool failures with a calm checklist instead o,” plan read-first scopes and ask-every-time on writes Guide: mcp-debug-broken-tool-calls Keep the live artifact visible the whole time. If you only have a blank box, stop and fetch the real job first

How to use this week

This week for one real failed call write three lines: request, response, which of permission/schema/path was wrong; fix, then retry.

Close the week by quoting aloud the refuse line you actually used once. If you cannot, rerun Practice now and date the pass/fail (Asia/Shanghai).

One variable retry

Change scope or tool name—not both—then retry once. Spam creates duplicates.

Ship the practice

Close the tab only after Practice now is done on a real artifact.

Do not bookmark-only

Finish Practice now, then tick this guide on your path. Titles unread are not skills.

Close the loop

Write one line: next time I switch models on failure with no log, I refuse.

Read the error twice

Copy the exact error string into your log before you retry. “Permission denied” and “unknown tool” need different next moves—guessing wastes the retry budget.

Red flag

Mash-retry on tool-name errors; changing three variables at once—stop, list tools, change one.

Pitfalls

PitfallFix
Retry spamOne change per try
Ignoring auth expiryReconnect first
Broadening permissions to “make it work”Fix args/path first
Example

Filled prompt

Temptation: skip the habit for mcp-debug-broken-tool-calls to save five minutes.
Job still: fix MCP/plugin tool failures with a calm
Smallest correct pass: Done visible · checkable artifact · Unknowns [?].
Boundaries: draft only; no silent send; no invented metrics.
Return: artifact + refuse-line said aloud.

What good output looks like

  • Names the shortcut refused (specific to mcp-debug-broken-tool-calls)
  • Still delivers checkable output for “fix MCP/plugin tool failures with a calm”
  • Unknowns labeled; draft-only
  • Pass/fail: refuse-line dated (mcp-debug-broken-tool-calls #4)

Practice now

Clock the fail: timestamp Asia/Shanghai on first fail (Asia/Shanghai).

Minimal repro tool: smallest args that still fail (Asia/Shanghai).

Arg-diff drill: compare last good args vs failing args in a two-column note (Asia/Shanghai).

Error-quote drill: paste exact error string into Save before theorizing (Asia/Shanghai).

MCP-debug drill: capture one failing tool call (name + args + error); fix env before blaming the model (Asia/Shanghai).

Thin-spot drill: rewrite the Save card with real nouns from your work (repo, doc, inbox). Generic placeholders fail the drill.

Tonight for one real failure log input, permission, and error in three lines; reproduce before changing args.

Reality check: after Practice now, write one sentence you will refuse next time—and keep it on the Save card dated Asia/Shanghai.

Today card (copy) — mcp-debug-broken-tool-calls: 1. Artifact I will produce: ___ 2. Pass/fail check: ___ 3. Refuse-line if tempted to skip verify/send: ___ (date: Asia/Shanghai) 4. One never-do from this guide: ___

Extra pass: do the card on a real file today—reading alone does not count.

Buffer line: name the artifact path you used (Asia/Shanghai).

One sentence takeaway

Fail three lines: request, response, which item wrong; fix, then retry.

Next

Permissions · Failure modes

← Back to home · Learn · Tools · Compare · Start