Search code across GitHub or scope results to a repository using GitHub code search syntax to find files, functions, or patterns.
Search code across GitHub (or scoped to one repo) using GitHub's code search syntax.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | ||
| owner | No | ||
| query | Yes | Search query, e.g. 'useEffect repo:owner/repo language:typescript' | |
| perPage | Yes |
Changes observed during successful MCP inspections.
v1.0.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It says nothing about authentication requirements, rate limits (GitHub code search is heavily throttled), pagination, or the 50-item cap on results — all things an agent needs before calling a code search endpoint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence, front-loaded with the action and resource, with the parenthetical scope qualifier in the right place. Nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an unannotated tool with no output schema and only 25% parameter coverage, the description is too thin: it omits auth/rate-limit behavior, result-cap semantics, and the meaning of half the parameters. An agent could invoke it but could not predict its behavior or cost.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 25%: just `query` is documented, while `repo`, `owner`, and `perPage` have no explanation in either schema or description. The phrase 'or scoped to one repo' gestures at the `repo` parameter but does not clarify how `owner` and `repo` interact or what `owner` alone does.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Search code across GitHub', with an explicit scope option (org-wide vs single repo). It is clearly distinguishable from siblings like github_get_file or github_list_directory, though the description never names an alternative for the case where the file path is already known.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by referencing GitHub's code search syntax, but it gives no explicit when-to-use guidance, no condition for choosing this over github_get_file, and no note about prerequisites such as authentication for code search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.