“Tool call failed” is not a debugging story

Model Context Protocol made tool integration a configuration problem rather than a bespoke one, which is a genuine improvement. It also introduced a debugging surface that is invisible from inside the agent: several distinct network and protocol failures that all reach your model as the same three words.

Five failures wearing one error message

The reason this matters more for agents than for ordinary API clients is what happens next. A conventional client surfaces the error. A model reacts to it: retries with different arguments, apologises to the user, invents a plausible answer, or calls a different tool entirely. By the time you read the transcript, the evidence has been written over by the agent's recovery attempt.

Debug outside the loop, in this order

1. Reachable? Connect with no tool call at all. Wrong region is the most common cause here, and it is not always the region you expect. Some services want a compute region like us-central1, others a multi-region like us. Getting this wrong looks identical to the service being down.
2. Authorised? A syntactically valid token with the wrong audience or a missing scope fails in a way that reads like a server problem.
3. Advertised? List what the server actually offers. Half of "the tool doesn't work" turns out to be a tool the server never advertised under that name.
4. Schema valid? Read the input schema and call it with known-good arguments by hand. If that works and the agent's call does not, the bug is in the model's argument construction, a different problem with a different fix.
5. Tool ran? Only now are you debugging your own code.

Generating a form from the tool's JSON Schema is worth the small effort here: it makes step four a fill-in-the-blanks exercise rather than hand-writing JSON against a spec you are reading in another tab.

The catalogue lies more often than you would expect

We swept the full published Google MCP server list (71 servers) by calling every one rather than trusting the documentation. Two entries in the smaller catalogue we started from were wrong: aiplatform.googleapis.com/mcp 404s, because Vertex exposes one server per toolset rather than one aggregate endpoint; and AlloyDB was marked regional-only despite having a working global endpoint. Region handling is not uniform either. Chronicle wants a multi-region while most services want a compute region.

The transferable lesson is the method, not the specific corrections: re-verify by sweeping, not by re-reading. A documented endpoint that returns 404 will cost you an afternoon of debugging your own code first, because the documentation is the last thing anyone suspects.

The security trap in every MCP debug console

This deserves its own section because it is easy to build accidentally, and we did.

Worth knowing about the residual risk too, since no honest write-up ends at "fixed": a host resolved and then connected to separately leaves a DNS-rebinding window. Closing it properly needs a pinned-IP transport. Tools that claim this class of problem is fully solved by a hostname allowlist have not thought about it hard enough.

Once it works, keep it visible

A working MCP integration is not the end of the story. Tool latency is frequently the real critical path in an agent that feels slow, and a tool that fails intermittently shows up as an agent that is "sometimes wrong" rather than as an infrastructure problem, which is exactly the misdiagnosis that burns weeks. Tool timing and error attribution belong in your observability view, with the caveat that one failing tool marks several spans as errors and naive counting will triple it.