Naveo

STEP 24 / 27

B6 MCP-DEBUG

DIAGNOSE · 1 CAUSE

Look at the spec. What's the most likely reason the agent never picks this tool?

TOOL SPEC

{
  "name": "do_thing",
  "description": "Does a thing.",
  "parameters": {
    "type": "object",
    "properties": {
      "thing_id": { "type": "string" },
      "metadata": { "type": "object" },
      "config": { "type": "object" },
      "options": { "type": "object" },
      "context": { "type": "object" }
    },
    "required": ["thing_id", "metadata", "config", "options", "context"]
  }
}

Context: Forge registered this tool in the ship's MCP. In the agent's
last 50 turns, it was NEVER invoked. not even in scenarios where it
clearly should have been. What's the most likely cause?

POSSIBLE CAUSES · 4

GUEST MODE

You're viewing this lesson as a guest. To save your progress, earn XP, and keep your streak, sign in when you're ready to check.

Costs 1 heart

When the agent acts like your tool doesn't exist

The symptom is always the same: the tool is registered, the handler works, but the agent never invokes it. Types of problems:

Under-invocation (low recall): should use it, doesn't.
Over-invocation (low precision): uses it when it shouldn't.
Invoked with bad arguments: breaks and gets discarded.

Your job in this step: read a schema that's being ignored and pick the most likely root cause.

The three dimensions where a tool can fail

The name. Does it communicate intent? lookup_crewmate vs find_data.
The description. Does it say when YES, when NO, what it guarantees?
The parameters. Are they minimal? Typed? Do they have descriptions?

When a tool fails in one of these, it's already a candidate to be ignored. When it fails in all three, it's practically invisible to the agent.

Look at the spec on the right and pick the most likely cause.

In production, this is the debugging of 80% of MCPs that "don't work": it's not broken code, it's poorly documented for the LLM.