search_code query description teaches incorrect syntax, causing repeated 422 errors

[danmoseley]

This came out of an analysis of github MCP server errors encountered in my past sessions across 5000 sessions.

What the agent did

In multiple sessions the agent called search_code with queries that look reasonable but are rejected with 422 ERROR_TYPE_QUERY_PARSING_FATAL. Examples from real sessions:

{"query": "repo:dotnet/runtime \"GetAttributes\\|SetAttributes\" path:System.IO.FileSystem/tests"}
{"query": "repo:dotnet/roslyn \"ProjectName\\|GeneratedFileName\\|FilePath\" language:csharp file:TestState"}
{"query": "repo:dotnet/runtime (review OR agent OR copilot OR AI) path:docs OR path:.github"}
{"query": "repo:dotnet/runtime (filename:AGENTS.md OR filename:*review*.md OR filename:*copilot*.md)"}
{"query": "--statisticalTest parameter Mann-Whitney repo:dotnet/BenchmarkDotNet"}

What went wrong

Each reflects the agent guessing at syntax that looks plausible but is wrong:

• \"foo\\|bar\" — used \| for regex OR inside a quoted string; correct form is /foo|bar/
• path:docs OR path:.github — OR between qualifier instances without parentheses has surprising precedence
• filename:*review*.md — filename: is not a valid qualifier; correct is path:*review*.md
• --statisticalTest ... — treated the tool like a shell command

Why it happens

The current query parameter description is:

"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."

This gives the model almost no useful guidance on syntax. It doesn't mention regex (slashes), path globs, symbol:, or how boolean operators interact with qualifiers. The example NOT is:archived language:Python OR language:go has ambiguous precedence and is likely misread by the model.

Suggested description

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'.

This gives clear and accurate information about the actual syntax without being too verbose. It explicitly names it "GitHub code search syntax" which may help the model connect it to the the documentation page of that title that it has already been trained on.