From db4c1a021dc87915d41e84c32d561383c26a37f8 Mon Sep 17 00:00:00 2001 From: Sam Morrow Date: Wed, 20 May 2026 11:18:53 +0200 Subject: [PATCH] fix(search_code): tighten query description for accurate model guidance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The current `search_code` query description is hand-wavy and gives the model little usable guidance on GitHub code search syntax, which (per analysis in #2390 across thousands of agent sessions) leads to repeated 422 ERROR_TYPE_QUERY_PARSING_FATAL responses from agents that guess at plausible-but-invalid syntax. Re-applies the spirit of #2442 by @jluocsa, originally suggested by @danmoseley in #2390, but corrected against the actual endpoint this tool calls. Critically, this tool uses go-github's `client.Search.Code`, which hits the legacy REST `/search/code` endpoint — NOT the new code search ("Blackbird"). Verified against the live API: symbol:WithContext repo:github/github-mcp-server -> 0 /Get|Set/ repo:github/github-mcp-server -> 0 path:**/*.go func repo:github/github-mcp-server -> 0 filename:*.md repo:github/github-mcp-server -> 0 (Foo OR Bar) -path:vendor language:go -> 422 So `symbol:`, `/regex/`, path globs, filename globs, and parenthesized boolean groups — features the proposal in #2442 listed — silently return zero or fail. Documenting them would teach the model syntax that doesn't work on this endpoint. The new description focuses on what's actually supported by legacy code search and the real bugs observed in #2390: - `path:dir` is a prefix, NOT a glob (displaces `path:**/*.ts` guesses). - `filename:exact.ext` is exact, NOT a glob (displaces `filename:*.md`). - `/regex/` and `\|` inside quotes don't work — call this out so the model stops generating them. - `symbol:` doesn't work on this endpoint — call this out. - Parenthesized boolean groups 422 — call this out so the model stops wrapping `OR` chains in parens. - Adds `extension:`, `in:file`, `in:path`, `size:`, `filename:`, `user:` qualifiers that the previous text omitted. - Implicit AND, `OR`, `NOT`, and `"quoted phrase"` for exact match are documented positively. - 256-char query limit. All four examples in the new description are verified against the live GitHub API and return non-zero results. Co-authored-by: jluocsa <103165870+jluocsa@users.noreply.github.com> Co-authored-by: danmoseley <6385855+danmoseley@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 2 +- pkg/github/__toolsnaps__/search_code.snap | 2 +- pkg/github/search.go | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index e4f70b6222..526d422aa4 100644 --- a/README.md +++ b/README.md @@ -1295,7 +1295,7 @@ The following sets of tools are available: - `order`: Sort order for results (string, optional) - `page`: Page number for pagination (min 1) (number, optional) - `perPage`: Results per page for pagination (min 1, max 100) (number, optional) - - `query`: Search query using GitHub's powerful code search syntax. Examples: 'content:Skill language:Java org:github', 'NOT is:archived language:Python OR language:go', 'repo:github/github-mcp-server'. Supports exact matching, language filters, path filters, and more. (string, required) + - `query`: Search query (GitHub code search REST). Implicit AND between terms; supports `OR`, `NOT`, and `"quoted phrase"` for exact match. Qualifiers: `repo:owner/repo`, `org:`, `user:`, `language:`, `path:dir` (prefix match), `filename:exact.ext`, `extension:`, `in:file`, `in:path`, `size:`, `is:archived`, `is:fork`. Max 256 chars. Examples: `WithContext language:go org:github`; `"package main" repo:o/r`; `func extension:go path:cmd repo:o/r`; `NOT TODO language:go repo:o/r`. (string, required) - `sort`: Sort field ('indexed' only) (string, optional) - **search_repositories** - Search repositories diff --git a/pkg/github/__toolsnaps__/search_code.snap b/pkg/github/__toolsnaps__/search_code.snap index 8b5510aa61..79cbbf04e9 100644 --- a/pkg/github/__toolsnaps__/search_code.snap +++ b/pkg/github/__toolsnaps__/search_code.snap @@ -26,7 +26,7 @@ "type": "number" }, "query": { - "description": "Search query using GitHub's powerful code search syntax. Examples: 'content:Skill language:Java org:github', 'NOT is:archived language:Python OR language:go', 'repo:github/github-mcp-server'. Supports exact matching, language filters, path filters, and more.", + "description": "Search query (GitHub code search REST). Implicit AND between terms; supports `OR`, `NOT`, and `\"quoted phrase\"` for exact match. Qualifiers: `repo:owner/repo`, `org:`, `user:`, `language:`, `path:dir` (prefix match), `filename:exact.ext`, `extension:`, `in:file`, `in:path`, `size:`, `is:archived`, `is:fork`. Max 256 chars. Examples: `WithContext language:go org:github`; `\"package main\" repo:o/r`; `func extension:go path:cmd repo:o/r`; `NOT TODO language:go repo:o/r`.", "type": "string" }, "sort": { diff --git a/pkg/github/search.go b/pkg/github/search.go index a4acc44489..e360f08f88 100644 --- a/pkg/github/search.go +++ b/pkg/github/search.go @@ -200,7 +200,7 @@ func SearchCode(t translations.TranslationHelperFunc) inventory.ServerTool { Properties: map[string]*jsonschema.Schema{ "query": { Type: "string", - Description: "Search query using GitHub's powerful code search syntax. Examples: 'content:Skill language:Java org:github', 'NOT is:archived language:Python OR language:go', 'repo:github/github-mcp-server'. Supports exact matching, language filters, path filters, and more.", + Description: "Search query (GitHub code search REST). Implicit AND between terms; supports `OR`, `NOT`, and `\"quoted phrase\"` for exact match. Qualifiers: `repo:owner/repo`, `org:`, `user:`, `language:`, `path:dir` (prefix match), `filename:exact.ext`, `extension:`, `in:file`, `in:path`, `size:`, `is:archived`, `is:fork`. Max 256 chars. Examples: `WithContext language:go org:github`; `\"package main\" repo:o/r`; `func extension:go path:cmd repo:o/r`; `NOT TODO language:go repo:o/r`.", }, "sort": { Type: "string",