MCP search rejects common names for the query text (query, search_term)

Problem

The search tool takes the query text in a parameter called search. Callers often send it under a more common name instead, most often query or search_term, and the call fails validation:

Arguments sent Error
{"scope": "work_items", "search_term": "rate limit"} Validation error: search_term is invalid, search is missing
{"query": "rate limit"} Validation error: query is invalid, scope is missing
{"search_type": "blobs", "query": "rate limit"} Validation error: search_type is invalid, query is invalid, search is missing

Callers usually recover on the next call, at the cost of a failed request and a retry. This happens regularly in production, not only in a single client.

#595159 (closed) adds an enum to scope, which helps callers send a valid scope. It doesn't cover the query text parameter.

Steps to reproduce

  1. Call search with {"scope": "work_items", "query": "rate limit", "project_id": "gitlab-org/gitlab"}.
  2. The call fails with Validation error: query is invalid, search is missing.
  3. The same call with "search" instead of "query" succeeds.

Proposal

  1. Accept query and search_term as aliases for search, when the caller didn't also send search. Don't advertise the aliases in the schema.
  2. Make the validation error say which parameter holds the query text and that scope is required, instead of only naming the rejected keys.
  3. Consider leading the tool description with the two required parameters and one short example call.

Open questions for engineering

Out of scope

Edited by 🤖 GitLab Bot 🤖