Raise your tool success rate

Your tool success rate is the share of tool calls (shell commands, file reads, edits, searches, MCP calls) that complete without an error.

When PromptConduit flags this

PromptConduit counts every tool call the agent makes. A call is a failure if it arrives through the PostToolUseFailure hook, or if its response is flagged as an error or as interrupted. Everything else is a success. The rate is successes divided by total calls.

The “Some tool calls are failing” warning fires when the rate is above 0% and below 85%:

• Editor extension (live session): with at least 20 tool calls, in a session with at least 3 prompts.
• Web Trends view: with at least 50 tool calls across the selected period and at least 5 prompts.

The minimum call count keeps a couple of early failures in a short session from tripping the warning.

Why it matters

A failed call is a full round-trip that produced nothing useful. The agent sends a request, waits for the tool, reads the error, and then spends another request deciding what to try next. Each of those requests resends the conversation. The error text itself also lands in context and stays there for the rest of the session.

Failures cluster. One wrong assumption, like the wrong working directory, a missing environment variable, or a non-standard test command, can fail a dozen calls before the agent figures it out. A low rate is usually a few root causes repeated, not a lot of independent bad luck.

Not every failure is a problem. A test run that fails because the bug isn’t fixed yet is the agent doing its job. The warning threshold sits well below the “good” line (95%) for that reason.

What to do

Write the environment down once. Most avoidable failures come from things the agent can’t know: how to build, how to run one test, which package manager, which directories are generated. Put them in a project CLAUDE.md:

## Commands
- Install: pnpm install (not npm)
- Test one file: pnpm vitest run path/to/file.test.ts
- Typecheck: pnpm typecheck

## Notes
- src/generated/ is codegen output; never edit it by hand.
- API tests need the dev server: run pnpm dev first.

In Claude Code, /init generates a starting CLAUDE.md from your codebase. Keep it short; Anthropic recommends under 200 lines per file.

Give exact paths and commands in the prompt. “Fix the failing test in src/auth/refresh.test.ts; run it with pnpm vitest run src/auth/refresh.test.ts” avoids a round of guessing.

Let it read before it writes. Ask the agent to open the file, or run --help on an unfamiliar CLI, before acting. A read is cheap. A wrong edit that fails to apply, or a command with the wrong flags, costs a round-trip and a recovery.

Watch for one tool failing repeatedly. If the same tool keeps failing, there’s usually a single fix, like a permission rule, a missing dependency, or a server that isn’t running. Fix the cause instead of letting the agent retry.

Don’t hard-stop mid-tool unless you need to. Pressing Esc during a tool call interrupts it, and an interrupted call is counted as a failure. See reduce interruptions.

Check MCP servers. A server that dropped its connection fails every call to its tools. In Claude Code, claude mcp list shows each server’s health, and /mcp shows status inside a session. See right-size your MCP servers.

How to check it worked

In the editor extension’s coaching tab, the Tool success cell under “How you drove the agent” shows the live session’s rate. It reads as good at 95% or more and as a warning below 85%. Success rates for individual skills and subagents appear in the Skills & subagents table, which helps you spot a single workflow causing most of the failures.

If you are signed in, promptconduit insights tools shows tool usage with success rates and promptconduit insights errors shows recurring error patterns, both with --period (24h, 7d, 30d, 90d). See /docs/editor-extension for the extension and /docs/tools for which assistants report tool failures through hooks.