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
- Call
searchwith{"scope": "work_items", "query": "rate limit", "project_id": "gitlab-org/gitlab"}. - The call fails with
Validation error: query is invalid, search is missing. - The same call with
"search"instead of"query"succeeds.
Proposal
- Accept
queryandsearch_termas aliases forsearch, when the caller didn't also sendsearch. Don't advertise the aliases in the schema. - Make the validation error say which parameter holds the query text and that
scopeis required, instead of only naming the rejected keys. - Consider leading the tool description with the two required parameters and one short example call.
Open questions for engineering
- Whether the aliases belong in the shared argument normalization proposed in https://gitlab.com/gitlab-org/gitlab/-/work_items/630772, or in the
searchtool itself. - Whether
search_typeshould alias toscope, or whether the clearer error is enough.
Out of scope
- The
scopeenum: #595159 (closed). - Other tools' parameter names.
Edited by 🤖 GitLab Bot 🤖