The client shows a green dot. The tool icon is in the list. Your agent's config file has the server registered. Every signal says "connected" — and the agent still can't do the thing you added the tool for. It either ignores the tool entirely, or calls it and gets back something wrong.
This isn't a connection bug most of the time. It's a category error: connection and capability are two different problems, and fixing the first one doesn't touch the second.
What "connected" actually means
An MCP server being connected means the agent can call its functions — the handshake succeeded, the tool schema is registered, the RPC will go through. That's it. It says nothing about whether the agent knows when to call it, how to sequence multiple calls, or what a wrong result looks like so it can catch one.
That gap is where most "my MCP tool doesn't work" reports actually live. The agent has a phone line to the tool and no idea what to say into it.
Three ways people give an agent a tool, and what each one actually buys you
1. MCP server (a routing/connection layer). This grants access. Composio's Tool Router, for instance, issues a per-session MCP URL you register — the agent can now call the tool's functions directly. What it does not give the agent: a procedure. No sequencing, no "check this before you do that," no defined failure modes. An agent with a live connection and no playbook doesn't fail loudly — it produces confident, plausible-looking, wrong calls. That's the failure mode that reads as "the tool doesn't work" when actually the tool works fine and the agent is guessing.
2. A procedure file the agent reads (Markdown instructions, a SKILL.md-style file). This is the piece that's usually missing. It doesn't need infrastructure — it's a document: when to use the tool, the exact call pattern including error handling, what results indicate the call actually succeeded versus silently returned garbage, and what to avoid. An agent reading a procedure alongside a live connection is a different animal than one improvising against raw API access.
3. A custom MCP server you write yourself. For tools that don't have one yet. Same rule applies once it exists — the server is the access, not the instructions for using it well.
The fix, concretely
If your agent has a connected tool and is either ignoring it or misusing it, don't start by re-checking the connection. Check whether the agent has anything telling it when to reach for the tool and what a correct call looks like. Nine times out of ten, the "broken integration" is a working connection with zero procedure behind it — and the fix is a text file, not a debugging session against the MCP server.
Verify with evidence, not a green dot
The other habit worth adopting: don't trust "shows as connected" as proof the integration works. Make the agent actually run a real call and show you the result before you consider setup done. A server that connects at handshake time can still fail on the first real invocation — auth scoped wrong, a schema mismatch, a rate limit you haven't hit yet. "It connected" and "it works" are different claims, and only one of them is worth trusting.
Full breakdown of the three paths, with more on the verification step: https://agentkitworks.com/answers/how-to-add-tools-to-claude-code
Top comments (0)