improve search_code query parameter description (fixes #2390)

[jluocsa]

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.

[SamMorrowDrums]

Closing as a duplicate of the already-landed fix in #2402. The same search_code description change was merged earlier for #2390, so this PR no longer needs to stay open.

[SamMorrowDrums]

Correction: reopening this. The earlier PR #2402 was closed without merging, so this PR is still the active implementation for #2390 rather than a duplicate of a landed fix.

[SamMorrowDrums]

Reviewing this from the perspective of being the consumer of this description (an LLM tool-caller): this is a clear, meaningful upgrade.

The current text is hand-wavy ("powerful... and more"), which forces guessing. The new version teaches things that materially change which query I'd construct:

• symbol: — I would default to content: for finding a function/type definition. Knowing symbol: exists changes the tool I reach for.
• Regex with /.../ — without this, I'd fall back to multiple OR'd queries or multiple tool calls. /GetAttributes|SetAttributes/ is exactly the right shape.
• Explicit boolean + parens — confirms (Foo OR Bar) path:src is supported rather than guessing.
• Glob in path: — disambiguates path:*.ts vs path:**/*.ts.
• Realistic combined examples — the previous examples were toy-shaped; these look like actual queries.

Token cost is ~3× longer, but search_code is a high-value, frequently-misused tool, so the trade is worth it.

Two tiny polish suggestions if you fancy a follow-up (not blocking):

1. Case inconsistency: language:Go (capital) in the qualifiers list vs language:go (lowercase) in the examples. Code search is case-insensitive on language, but the inconsistency reads as a smell.
2. is:archived|fork — the pipe is ambiguous (literal? alternation?). Splitting to two qualifiers (is:archived, is:fork) would be clearer.

Approving — thanks for the contribution! 🙏

[SamMorrowDrums]

Reopened in #2513 with you (@jluocsa) and @danmoseley credited as co-authors, plus a tighter pass that fills a few gaps and — importantly — corrects against what this tool's endpoint actually supports.

While verifying the proposed examples against the live API, I found that this tool calls go-github's client.Search.Code, which hits the legacy REST /search/code endpoint, not the new code search. So symbol:, /regex/, path globs (path:**/*.ts), filename globs (filename:*.md), and parenthesized boolean groups — features in the proposed wording — silently return 0 results or 422 on this endpoint. Teaching them would lead the model in the wrong direction.

The version in #2513 documents only what's actually supported by legacy /search/code (verified against the live API), and explicitly calls out the unsupported features so the model stops generating them. All four examples are verified to return real results.

Thanks for kicking this off — your version got us most of the way there. 🙏 Closing in favor of #2513.