Skip to content

improve search_code query parameter description (fixes #2390)#2442

Open
jluocsa wants to merge 1 commit intogithub:mainfrom
jluocsa:improve/search-code-query-description
Open

improve search_code query parameter description (fixes #2390)#2442
jluocsa wants to merge 1 commit intogithub:mainfrom
jluocsa:improve/search-code-query-description

Conversation

@jluocsa
Copy link
Copy Markdown

@jluocsa jluocsa commented May 8, 2026

Summary

Fixes #2390.

The current query parameter description for the search_code tool gives the model very little useful guidance on GitHub code search syntax, which (per analysis across thousands of agent sessions in #2390) leads to repeated 422 ERROR_TYPE_QUERY_PARSING_FATAL responses from agents that guess at plausible-looking but invalid syntax — for example:

  • \"foo\\|bar\" instead of regex /foo|bar/
  • filename:*review*.md instead of path:*review*.md
  • path:docs OR path:.github without parentheses (surprising precedence)

This PR replaces the description with one that explicitly enumerates the qualifiers, boolean operators, regex form (slashes), and path globs, plus realistic examples covering each. The new wording is the one suggested by the issue author.

Before

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.

After

Search query using GitHub code search syntax. Qualifiers: repo:owner/repo, org:name, language:Go, path:src/.js, path:/regex/, symbol:Name, content:term, is:archived|fork. Boolean: AND, OR, NOT, parentheses. Regex: surround with slashes e.g. /sparse.index/. Glob in path: path:.ts, path:/src/**/.js. Examples: 'MyFunc language:go repo:owner/repo', 'symbol:WithContext language:go', '/GetAttributes|SetAttributes/ repo:owner/repo', '(Foo OR Bar) path:src repo:owner/repo'.

Files changed (3 files / 3 lines)

  • pkg/github/search.go — the description string
  • pkg/github/__toolsnaps__/search_code.snap — regenerated via UPDATE_TOOLSNAPS=true go test ./pkg/github -run Test_SearchCode
  • README.md — regenerated via go run ./cmd/github-mcp-server generate-docs

Validation

  • Test_SearchCode (and all subtests) pass
  • go test ./... passes for all 22 packages
  • Toolsnap diff is exactly the description string change — nothing else
  • README diff is exactly the description string change — nothing else

Note: I was unable to run script/lint locally (no golangci-lint available in my environment) or -race (no CGO toolchain). CI should validate both. Happy to iterate if it surfaces anything.

The current `query` description for `search_code` gives the model little
useful guidance on GitHub code search syntax, leading to repeated
422 ERROR_TYPE_QUERY_PARSING_FATAL responses from agents that guess at
plausible-looking but invalid syntax (e.g. regex without slashes,
`filename:` instead of `path:`, `OR` between qualifiers without parentheses).

Replace the description with one that explicitly enumerates qualifiers,
boolean operators, regex form (slashes), and path globs, plus realistic
examples covering each.

Updates the search_code toolsnap and README accordingly.

Fixes github#2390.
@jluocsa jluocsa requested a review from a team as a code owner May 8, 2026 00:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

search_code query description teaches incorrect syntax, causing repeated 422 errors

1 participant