MCP validation errors should name unknown parameters and list the accepted ones

Problem

When an agent sends a parameter a tool doesn't declare, the validation error doesn't say the parameter is unknown or what the tool accepts. For example, search called with query returns Validation error: query is invalid, search is missing. The agent has to guess again or reread the schema, and each guess costs a failed call.

  • In the GitLab MCP server dogfooding experiment (gitlab-org#23821), the agent recovered from a wrong parameter name or scope after a validation error in 14 sessions (23 episodes). Unclear validation errors that it couldn't easily recover from showed up in another 5 sessions.
  • https://gitlab.com/gitlab-org/gitlab/-/work_items/630772 shows the same shape in production: id sent to tools that declare project_id, and the reverse, at about 13,300 failed calls a week across 34 tools.

Aliases (gitlab-org#23939, #632547, #632461) fix names we've already seen. A clearer error also helps with names nobody has tried yet, and with tools added later.

Proposal

When validation fails because of an undeclared parameter, return an error that:

  1. Says the parameter is unknown, for example: Unknown parameter 'query'. Accepted parameters: search, scope, project_id, group_id, ...
  2. Names any required parameter that's missing.
  3. Optionally suggests the closest accepted name when one is a likely match (did you mean 'search'?).

Apply it in shared validation so every tool gets it, not tool by tool.

Open questions for engineering

  • Where this belongs given the different validation paths described in https://gitlab.com/gitlab-org/gitlab/-/work_items/630772.
  • Whether to list every accepted parameter or only the required ones, to keep errors short for tools with long schemas.
  • Whether the closest-name suggestion is worth it, or the accepted list is enough.

How we'll know it worked

The share of validation errors followed by a second validation error on the same tool, measured from tool-call events before and after release. [Baseline TBD]