quick-search

Overview Schema Source Related Servers Discussions Admin

search_repo_context

Search a repository by keywords to rank likely relevant files and return bounded snippets around the strongest matches, letting you narrow a large codebase before deeper inspection.

Instructions

Search a repository with explicit keywords, rank likely relevant files without reading full files, and return bounded snippets around the strongest clustered matches. The tool prefers source files over docs when scores are similar, boosts likely function, class, struct, module, or method definition hits, merges overlapping match windows, and enforces hard budgets on returned files, snippets, and total lines. Optional subtree and glob filters can narrow the search space before ranking. Matching defaults to substring mode, with optional word and identifier-aware modes for stricter code search. Keyword expansion is bounded and returned transparently in the output. Prefer specific keywords over very general ones; ranking gives substantially more weight to matches on the original input keywords than to expansion-only matches. Preferred agent workflow: call the tool in compact mode first, then expand the cached result by query_id in full mode only if you need richer metadata; enable diagnostics only for debugging or tuning. Use it to narrow a large repo before deeper inspection. It returns structured output with summary counts, ranked files, snippets, and usage guidance. Pass an absolute directory path for reliable agent behavior. Relative directory values such as '.' only work when the MCP client exposes roots, so they are not portable across clients. The result is bounded and does not necessarily include every file that could be relevant for context. Only do further searches across the repository if this context is insufficient.

Input Schema

TableJSON Schema

Name	Required	Default
`subpath`	No
`keywords`	No
`query_id`	No
`directory`	No
`max_files`	No
`match_mode`	No	substring
`lines_after`	No
`output_mode`	No	compact
`lines_before`	No
`max_snippets`	No
`max_total_lines`	No
`paths_exclude_glob`	No
`paths_include_glob`	No
`include_diagnostics`	No
`prefer_source_files`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 20, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure, and it delivers: it discloses ranking preferences (source files over docs, definition boosts), merging of overlapping match windows, hard budgets on files/snippets/lines, bounded keyword expansion with transparent output, substring default with word/identifier modes, and the non-exhaustive nature of results. It also warns about relative directory portability. This is rich, honest behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but information-dense, and every sentence earns its place by adding behavioral or usage detail. It is front-loaded with the core mechanism, then filters, matching modes, workflow, and portability caveats. It could be tightened slightly (e.g., 'The result is bounded...' repeats the boundedness already stated), but the structure is logical and the length is justified by the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (15 parameters, no annotations, no schema descriptions), the description is remarkably complete. It covers the search mechanism, ranking behavior, output structure, parameter semantics, workflow, portability caveats, and limitations. The output schema exists, so return values need not be detailed. Nothing critical for an agent to select and invoke this tool correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, and it does substantially: it explains the meaning and purpose of keywords, subtree/glob filters, match modes, output modes, query_id expansion, diagnostics, and directory path requirements. It doesn't enumerate every parameter (e.g., max_files, lines_before/after, max_snippets, max_total_lines are only implied by 'hard budgets'), but it gives enough semantic context for an agent to infer their roles. A 4 is appropriate given the heavy compensation for 0% schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb ('Search a repository'), a clear resource ('repository'), and a distinctive mechanism ('rank likely relevant files without reading full files, return bounded snippets around strongest clustered matches'). It also names the sibling tool (search_focused_context) and differentiates by describing this tool's ranking and bounded-snippet behavior. This is a strong, specific statement of what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance: 'Use it to narrow a large repo before deeper inspection' and 'Only do further searches across the repository if this context is insufficient.' It also provides a preferred agent workflow (compact mode first, then full mode via query_id, diagnostics only for debugging) and warns against very general keywords. This is exemplary usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server