<!--IssueSummary start--> <details> <summary> Everyone can contribute. [Help move this issue forward](https://handbook.gitlab.com/handbook/marketing/developer-relations/contributor-success/community-contributors-workflows/#contributor-links) while earning points, leveling up and collecting rewards. </summary> - [Close this issue](https://contributors.gitlab.com/manage-issue?action=close&projectId=278964&issueIid=607880) </details> <!--IssueSummary end--> ## Problem The `search` MCP tool tells agents that `order_by` accepts **`created_at` only** (`app/services/mcp/tools/search/search_service.rb:69-75`). The search backend accepts **eight** values. Separately, neither `order_by` nor `sort` is a declared Grape param on the search endpoints, so neither is validated at all. **Defect 1 — the advertised contract is wrong and costs functionality.** `Search::SortOptions::SORT_MAPPINGS` (`lib/search/sort_options.rb`) accepts `created_at`, `updated_at`, `popularity`, `milestone_due`, `weight`, `health_status`, `closed_at` and `due_date`, each paired with `sort: asc | desc`. `sort` also accepts sixteen compound forms when `order_by` is omitted (`created_asc`, `updated_desc`, `weight_desc`, …); bare `asc`/`desc` are valid *only* alongside `order_by`. An agent reading the schema will never try `order_by: updated_at` even though it works, so the tool advertises about one-eighth of its own sorting capability. This was not a deliberate decision to give agents a reduced sorting surface. Agents should be able to use what the backend supports, so the fix widens the advertised set to match `SORT_MAPPINGS` rather than narrowing the backend. **Defect 2 — the params are undeclared, so nothing can validate them.** `GET /api/:version/search` declares 12 params; `order_by` and `sort` are not among them. They still reach the backend because `search_params` (`lib/api/search.rb:70-78`) reads raw `params[key]` rather than `declared(params)`, iterating `SearchHelpers.search_param_keys` which does include both. Being undeclared means Grape cannot validate them (a `values:` constraint requires a declaration), they are missing from API documentation, and `ApiTool#input_schema` cannot surface them — which is why the aggregated tool hand-writes its own schema, and how the incorrect description came to exist independently of the API. `SortOptions.sort_and_direction` does `SORT_MAPPINGS.fetch([order_by, sort], :unknown)`, so an invalid value silently falls back to default ordering instead of erroring. ## Impact - Agents are told seven of eight sort options do not exist, so they cannot use them. - `order_by=updated_at` (valid) and `order_by=nonsense` (invalid) both return `200` with no distinguishing signal, so an agent cannot tell a working request from a silently ignored one. <details> <summary>Evidence — verified live on GDK <code>19.3.0-pre</code> (<code>e4e40522166</code>)</summary> Two issues were created with deliberately inverted timestamps, so `created_at` and `updated_at` orderings disagree: | issue | `created_at` | `updated_at` | |---|---|---| | `older` | 2026-07-29 | 2026-08-03 | | `newer` | 2026-08-02 | 2026-07-29 | Requests to `GET /search?scope=issues&search=sortprobe`: | params | status | returned order | |---|---|---| | `order_by=created_at&sort=desc` | 200 | newer, older | | `order_by=created_at&sort=asc` | 200 | older, newer | | `order_by=updated_at&sort=desc` | 200 | **older, newer** | | `order_by=updated_at&sort=asc` | 200 | **newer, older** | | `order_by=nonsense&sort=desc` | **200** | newer, older (silent fallback) | | `sort=weight_desc` (no `order_by`) | **200** | newer, older | | `state=bogus` *(control)* | **400** | `state does not have a valid value` | The `updated_at` rows invert relative to the `created_at` rows, proving `order_by: updated_at` is honoured end-to-end — so the `created_at`-only description is factually wrong, not merely conservative. The `state=bogus` control returning `400` matters: it shows the endpoint *does* reject invalid values for declared params carrying `values:`. The `200` on `order_by=nonsense` is therefore a genuine absence of validation, not an artifact of the test setup. Also confirmed: `SCOPE_ONLY_SORT` restricts `popularity_asc`/`popularity_desc` to the `issues` and `work_items` scopes, and `search_type` is likewise forwarded while undeclared. </details> ## Fix 1. **Declare `order_by` and `sort` in `lib/api/search.rb`** with `values:` sourced from `SORT_MAPPINGS`, alongside the existing `state` and `scope` declarations. This fixes validation, API documentation and schema derivation in one change, which is why it belongs at the API layer rather than in the tool. 2. **Use a flat `values:` list including `popularity`.** `SCOPE_ONLY_SORT` continues to own the scope restriction where it already lives, so `popularity` passes param validation regardless of scope and the existing scope behaviour is unchanged. Cross-param validation is deliberately not added here. 3. **Derive the MCP tool's `order_by`/`sort` descriptions from `SORT_MAPPINGS`** rather than restating values in prose, so the description cannot drift from the mapping again. Note in the `sort` description that bare `asc`/`desc` require `order_by`. 4. **Treat the stricter validation as a bug fix, with no deprecation period.** Callers passing an out-of-range value currently get `200` plus default ordering — they are relying on unspecified behaviour, and a `400` is both more correct and more debuggable. Call this out in the changelog: invalid `order_by`/`sort` values on the search endpoints are now rejected. Adding an `enum` to the MCP tool schema *instead* of declaring the params would be the wrong shape — it would put the allowed-values list in a second place, enforce it only for MCP callers, and leave `/search`, `/groups/:id/search` and `/projects/:id/search` unvalidated. ## Scope and non-goals **In scope:** declaring `order_by`/`sort` with `values:`, and correcting the tool descriptions. **Non-goals:** redesigning the sort API; reconciling the two naming styles (`created_at` + `asc` versus `created_asc`); the `search_type` declaration gap; deriving `enum` from `values:` generally (#607881). ## Verification steps 1. `order_by` and `sort` appear in `grep -n 'values:' lib/api/search.rb` alongside `state` and `scope`. 2. `GET /search?scope=issues&search=x&order_by=nonsense` returns `400`. 3. `GET /search?scope=issues&search=x&order_by=updated_at&sort=desc` returns `200` and orders by updated-at descending. 4. `GET /search?scope=issues&search=x&sort=weight_desc` (no `order_by`) returns `200`. 5. `order_by=popularity` passes param validation for any scope; `SCOPE_ONLY_SORT` behaviour for non-`issues` scopes is unchanged. 6. The tool's `order_by` description lists all eight `SORT_MAPPINGS` values and is generated from the constant. 7. All three endpoints (`/search`, `/groups/:id/search`, `/projects/:id/search`) behave consistently. 8. `spec/requests/api/search_spec.rb` still passes. ## Related - #607881 — derive `enum` from Grape `values:` in `ApiTool#input_schema`, to prevent this class of drift