call_tool is easy for models to malform (nested tool_name / wrong-slot args) and fails with no correction hint, causing retry loops

[Tanguille]

Using the optimizer's find_tool + call_tool meta-tools with an LLM agent (vmcp v0.40.1), call_tool itself works fine when it's called exactly right:

call_tool({"tool_name": "grafana-opt_search_dashboards", "parameters": {}})   → returns results

But the two-level shape — tool_name at the top, the target tool's own args nested under parameters — trips the model up constantly, and every malformation is a hard error the model then loops on. The common ones I see:

• tool_name nested inside parameters → call_tool failed: tool_name is required (from the model's point of view it did pass tool_name, just one level too deep)
• the target tool's args placed at the top level next to tool_name instead of inside parameters → the target tool then reports its own missing arg, e.g. apiVersion is required
• the model calling the meta-tool through itself → tool not found: mcp_toolhive_call_tool

Because these come back as plain errors with no correction hint, the agent tends to retry the same malformed call — I've watched it fail 3-4 times in a row on identical arguments before giving up.

Two things that would help a lot:

• Be lenient about the obvious case: if tool_name is missing at the top level but present inside parameters, hoist it (and treat the rest of parameters as the target args). Likewise if a target arg ends up next to tool_name.
• When it does reject, return a short schema-guiding message (expected {tool_name, parameters}, got ...) so the model can self-correct instead of looping.

The handler is correct as-is — this is about making the meta-tool robust to how models actually call it, which is more or less the whole point of the optimizer layer. Same ergonomics area as #4357 (dynamic find_tool description).

Version: vmcp v0.40.1.

[aponcedeleonch]

Hello @Tanguille ! Thanks for reporting this issue. Yes, that would be a good enhancement to have and it makes sense. Just to be sure I get what you're proposing correctly. The proposal would be that, if the model invoked call_tool with something like the following it gets accepted:

{
  "parameters": {
    "tool_name": "grafana-opt_search_dashboards"
  }
}

That, and a clearer error message for the model to correct itself in case the request is still malformed.

Actually, I would be more than happy to review a PR with something like that in case you're interested in contributing. If not, will prioritize this internally and try to get to it ASAP.

[Tanguille]

Hey @aponcedeleonch

Happy to send a PR for it. I'll aim to hoist a nested tool_name out of parameters when present, plus improve the error message to guide the model toward the correct shape if it's still malformed. Will follow up here once it's up.

[Tanguille]

Opened #6150 for this.

It turned into two changes rather than one. While wiring up the leniency I noticed that authorization reads tool_name from the top level only, so a nested payload misses that lookup and falls through the pass-through branch with no policy check at all. Not exploitable on main today, since the optimizer rejects the call a moment later for the same reason, but accepting the nested form would have made it reachable.

Both now resolve the target through one shared helper, so authorization and dispatch can't disagree about which tool a request names.

Also included the clearer error message. It lists the parameter keys it received, keys only and no values, so a nesting mistake is distinguishable from a genuinely empty call in the logs. That was the part that made this hard to diagnose on my end.

Happy to split the authz commit into its own PR if you'd rather review them separately.