Reflex is a local-first, offline code search engine providing sub-100ms search, symbol navigation, and dependency analysis for AI agents and CLI tools.
Search & Discovery
search_code — Full-text or symbol-only search with line numbers and code previews
search_regex — Regex-based search for complex patterns
search_ast — Structure-aware search using Tree-sitter AST queries
list_locations — Fast file+line discovery returning minimal location data (no content)
count_occurrences — Quick statistics on how many times a pattern appears and in how many files
find_references — Find a symbol's definition and all usage sites in a single atomic call
Index Management
index_project — Build or incrementally update the search index
check_index_status — Check whether the index is fresh, stale, or missing
Dependency Analysis
get_dependencies — List all imports/dependencies of a specific file
get_dependents — Reverse lookup: find all files that import a given file
get_transitive_deps — Walk the full dependency tree up to a configurable depth
find_hotspots — Identify the most-imported files (critical dependencies)
find_circular — Detect circular dependency chains
find_unused — Find files with no incoming dependencies (potential dead code)
find_islands — Identify disconnected components/subsystems in the dependency graph
analyze_summary — High-level health metrics: counts of circular deps, hotspots, unused files, and islands
Codebase Context
gather_context — Collect project structure, file type distribution, frameworks, entry points, test layout, and config files
Supports natural language code search and codebase analysis using OpenAI's models as the AI provider.
Sub-100ms local code search — CLI, scripts, and AI agents
Reflex is a local-first, full-text code search engine. Use it from the command line, pipe it into scripts, or connect it to AI coding assistants (Claude Code, Cursor, and any MCP-compatible tool) for instant symbol lookup, dependency analysis, and codebase exploration — fully offline, fully deterministic, no cloud required.
# Via NPM
npm install -g reflex-search
# Or via Cargo
cargo install reflex-search# From your project root
rfx index
# Full-text search
rfx query "extract_symbols"
# Symbol definitions only
rfx query "CacheManager" --symbols
# JSON output for scripting
rfx query "TODO" --json --limit 20Add this to your Claude Code MCP configuration (~/.claude/claude_desktop_config.json):
{
"mcpServers": {
"reflex": {
"command": "rfx",
"args": ["mcp"]
}
}
}Your AI assistant can now call search_code, find_references, get_dependencies, and more.
See Claude Code + Reflex MCP Quickstart for MCP setup, key tools, and troubleshooting.
Related MCP server: codeix
Capability | grep / ripgrep | Built-in AI search | Sourcegraph | Reflex |
Full-text search | ✅ | ✅ | ✅ | ✅ |
Symbol-aware filtering | ❌ | Partial | ✅ | ✅ |
Dependency analysis | ❌ | ❌ | Partial | ✅ |
Deterministic results | ✅ | ❌ | ✅ | ✅ |
Local-first / offline | ✅ | ❌ | ❌ | ✅ |
MCP server built-in | ❌ | — | ❌ | ✅ |
JSON output for agents | Manual | ✅ | ✅ | ✅ |
We A/B-tested an AI coding agent on real code-search tasks using Reflex (via MCP) against the same agent using its built-in search (ripgrep-backed Grep/Glob) — identical tasks, model, and repository, paired per task. The harness lives in benches/efficacy/ and is fully reproducible.
Setup: model claude-sonnet-4-6; 12 code-search tasks (find-all-usages, symbol locate, dependency/reverse-dependency, hotspot, comprehension, plus negative controls); N = 3 replicates per arm; run against the Reflex repository.
Results — Reflex ÷ built-in, so < 1.0 means Reflex uses less:
Metric | Reflex ÷ built-in | Reading |
Task success rate | 1.00 (100% vs 100%) | Equal correctness — no regression |
Total tokens (median over tasks) | ≈ 1.00 | Parity |
Find-all-usages tokens | 0.79 | Favors Reflex (CI still includes parity) |
Agent iterations / turns (mean) | 0.85 | ~15% fewer round-trips |
Cost per task (median) | 0.69 | ~31% cheaper (p < 0.01) |
Implications
No-regret replacement for built-in search. Reflex matches built-in tools on answer correctness (100% task success in both arms) at parity-or-better token usage and meaningfully lower dollar cost.
Fewer round-trips on navigation. find_references returns a symbol's definition and every call site in one call, so the agent iterates less than chaining grep + file reads.
The gap should widen with repo size. The baseline here is ripgrep — already fast on a mid-size repo. Reflex's trigram index is built to win most where linear scans are slowest: very large codebases and whole-repo "find every occurrence" tasks.
Honest caveats. This is a focused benchmark: one model, one repository, N = 3 — enough to demonstrate parity-to-better and no regression, not a large statistical claim (the token primary is formally "no significant difference," with point estimates favoring Reflex). Per-result precision/recall is not yet formally scored. Reproduce it yourself:
python3 benches/efficacy/runner.py --arms A B --repos reflex --n 3
python3 benches/efficacy/extract_metrics.py && python3 benches/efficacy/analyze.pyWhen connected via MCP, your AI assistant gets these tools:
Tool | What it does |
| Full-text or symbol search with line numbers and context |
| Fast file+line discovery (minimal tokens) |
| Quick match statistics without full content |
| Regex pattern matching across the codebase |
| Structure-aware search via Tree-sitter AST queries |
| Symbol definition + all usage sites in a single call; the primary code-navigation tool for AI agents |
| Trigger or refresh the search index |
| Check whether the index is fresh, stale, or missing; call before any search session or after git operations |
| All imports for a specific file |
| All files that import a given file (reverse lookup) |
| Transitive dependency graph up to a configurable depth |
| Most-imported files (dependency hotspots) |
| Detect circular dependency chains |
| Files with no incoming dependencies |
| Disconnected components in the dependency graph |
| High-level dependency counts and metrics |
| Codebase structure and project-type summary |
Index not found error? If an MCP tool returns "Index not found. Run 'rfx index' to build the cache first", call index_project first, then retry the failed tool.
Reflex also works as a standalone CLI for humans and shell scripts.
# Full-text search (finds every occurrence)
rfx query "extract_symbols"
# Symbol definitions only (faster, uses tree-sitter)
rfx query "extract_symbols" --symbols
# Filter by language and symbol kind
rfx query "parse" --lang rust --kind function --symbols
# Regex search
rfx query "fn.*test" --regex
# JSON output for programmatic use
rfx query "unwrap" --json --limit 10
# Pipe file paths to other tools
vim $(rfx query "TODO" --paths)Interactive TUI mode — run rfx query with no pattern to launch live search with keyboard navigation.
rfx deps src/main.rs # Show direct imports
rfx deps src/config.rs --reverse # What imports this file
rfx deps src/api.rs --depth 3 # Transitive dependencies
rfx analyze --circular # Find circular dependency chains
rfx analyze --hotspots # Most-imported files
rfx analyze --unused # Files with no incoming dependenciesrfx ask "Find all TODOs in Rust files" # Translate to rfx query and run
rfx ask "How does authentication work?" --agentic # Multi-step codebase reasoning
rfx ask # Interactive chat modeRequires an AI provider configured via rfx llm config (OpenAI, Anthropic, OpenRouter, or any OpenAI-compatible endpoint).
rfx index # Build / update the search index
rfx index status # Background indexing status
rfx watch # Auto-reindex on file changes
rfx stats # Index statistics
rfx pulse changelog # Codebase change digest
rfx pulse wiki # Per-module documentation
rfx pulse map # Architecture diagram (Mermaid / D2)
rfx serve --port 7878 # Local HTTP API serverRun rfx <command> --help for full options.
npm install -g reflex-searchcargo install reflex-searchSetup note: run rfx commands from your project root directory. Add .reflex/ to your .gitignore to exclude the search index from version control.
Full symbol extraction (functions, classes, methods, types, etc.) for 15 languages:
Systems: Rust, C, C++, Zig
Backend: Python, Go, Java, C#, PHP, Ruby, Kotlin
Frontend: TypeScript, JavaScript, Vue, Svelte
Swift is temporarily disabled (tree-sitter-swift 0.7.x grammar incompatibility).
rfx query --lang swiftemits a warning; full-text search still works.
Full-text search works on all file types regardless of parser support.
# .reflex/config.toml (project-level)
[index]
languages = [] # Empty = all supported languages
max_file_size = 10485760 # 10 MB
[search]
default_limit = 100
[performance]
parallel_threads = 0 # 0 = auto (80% of available cores)For AI provider configuration (rfx ask, rfx pulse), run rfx llm config.
Reflex uses a trigram-based inverted index with runtime symbol detection:
Indexing: extracts 3-character trigrams from all files; stores full content in memory-mapped content.bin; no tree-sitter parsing at index time
Full-text queries: intersect trigram posting lists → verify matches (instant)
Symbol queries: trigrams narrow candidates → parse only matching files with tree-sitter
.reflex/
meta.db # SQLite: file metadata, stats, config
trigrams.bin # Inverted index (memory-mapped)
content.bin # Full file contents (memory-mapped)
config.toml # Index settingsrfx serve binds to 127.0.0.1:7878 by default — loopback only, no authentication. Do not expose it to the network. See CLAUDE.md for the full threat model.
cargo build --release # Build
cargo test # Test
rfx index # Refresh index after code changesSee CONTRIBUTING.md for guidelines.
MIT — see LICENSE for details.
Fast code search for developers — works standalone, in scripts, and with AI coding agents
One-call overview of codebase dependency health. Prefer this over running find_circular + find_hotspots + find_unused + find_islands individually — returns aggregate counts so the agent can decide which specific analysis to drill into. Returns {circular_dependencies, hotspots, unused_files, islands, min_dependents}. Only static imports are considered. On "Index not found" / "stale" error, call index_project, then retry.
Example: {"circular_dependencies": 17, "hotspots": 10, "unused_files": 82, "islands": 81, "min_dependents": 2}
| Name | Required | Description | Default |
|---|---|---|---|
| min_dependents | No | Minimum number of dependents for hotspots (default: 2) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: it only considers static imports, returns aggregate counts with a specific structure, and handles errors with a retry pattern. It clearly communicates what the tool does and its limitations, exceeding the minimal requirements.
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?
The description is concise at three sentences plus an example. It front-loads the purpose and usage guidance, with every sentence providing essential information. No waste or redundancy.
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?
Given the tool's simplicity (one optional parameter, no output schema), the description is complete. It explains what the tool returns (aggregate counts), provides an example, and specifies error handling. No additional context is needed for effective use.
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 100% with one parameter (min_dependents) already described in the schema. The description does not add additional meaning beyond the schema, so it meets the baseline but does not exceed it.
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?
The description clearly identifies the tool as a 'one-call overview of codebase dependency health,' explicitly distinguishing it from sibling tools like find_circular, find_hotspots, find_unused, and find_islands by stating it should be preferred over running them individually. This provides a specific verb and resource with clear differentiation.
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 explicitly states when to use this tool ('Prefer this over running individual analyses') and provides an alternative: 'so the agent can decide which specific analysis to drill into.' It also gives explicit error recovery instructions ('On Index not found/stale error, call index_project, then retry'), offering comprehensive guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check whether the Reflex search index is fresh, stale, or missing — without running any search. Call this once at session start and before any bulk search/refactoring task; if status is stale or missing, call index_project before searching.
Returns {status: "fresh" | "stale" | "missing", reason, action_required, files_modified?}. Useful after git operations (checkout, merge, rebase, pull) that may have moved HEAD off the indexed commit; reason explains the staleness and action_required gives the fix command (always rfx index when stale).
Example fresh: {"status": "fresh"}. Example stale: {"status": "stale", "reason": "Commit changed from abc1234 to def5678", "action_required": "rfx index"}
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description fully discloses behavior: it is a read-only check, does not run a search, and returns specific fields (status, reason, action_required, files_modified). It explains that staleness relates to commit changes, giving the agent full understanding.
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?
The description is efficient: first sentence defines purpose, second gives usage guidance, third describes return type, and fourth provides examples. No redundant or irrelevant information.
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?
Given the tool's simplicity (no parameters, no output schema), the description covers all necessary aspects: purpose, usage, return values, examples. It is complete and leaves no ambiguity.
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?
No parameters exist, so schema coverage is 100% trivially. The description does not need to add parameter info, but it does add value by describing the return object structure, which compensates for the lack of output schema.
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?
The description clearly states 'Check whether the Reflex search index is fresh, stale, or missing' with a specific verb and resource. It distinguishes itself from siblings like 'index_project' (which builds the index) and search tools by emphasizing it runs no search.
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?
Explicitly says when to call: 'once at session start and before any bulk search/refactoring task'. Also tells what to do if status is stale/missing: 'call index_project before searching'. Provides concrete scenarios like git operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Count-only statistics for a pattern. Prefer this over piping grep -c / wc -l / rg --count — returns total occurrences and file count in one call without loading any content.
Use this for: "how many times is X used?"; impact checks before refactoring; validating search scope. Returns {total, files, pattern}. Supports all filters (lang, file, glob, exclude, symbols, kind).
Example: {"total": 87, "files": 12, "pattern": "CourtCase"}. On "Index not found" / "stale" error, call index_project, then retry.
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | Filter by file path substring | |
| glob | No | Include files matching patterns | |
| kind | No | Filter by symbol kind (function, class, etc.) | |
| lang | No | Filter by language | |
| force | No | Force execution of potentially expensive queries (bypasses broad query detection) | |
| exclude | No | Exclude files matching patterns | |
| pattern | Yes | Search pattern (text to find) | |
| symbols | No | Count symbol definitions only (not usages) | |
| dependencies | No | Include dependency information (imports) in results. Only extracts static imports. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the burden. It discloses behavior: returns only total and file count, never loads content, supports all listed filters, and indicates error recovery steps. No contradictions.
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?
The description is relatively concise and front-loads the core purpose. It uses bullet-style use cases and example JSON. Minor redundancy could be trimmed, but overall efficient.
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?
Given 9 parameters, no output schema, and moderate complexity, the description is thorough. It explains return format with example, error handling, and all applicable filters. No gaps identified.
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 100%, and description adds marginal value by summarizing filter parameters ('Supports all filters (lang, file, glob, exclude, symbols, kind)') but does not add meaning beyond what the schema provides. Baseline 3 is appropriate.
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?
The description clearly states it provides 'Count-only statistics for a pattern' and distinguishes itself from siblings by recommending over grep -c, wc -l, rg --count. It specifies it returns total occurrences and file count without loading content.
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?
Explicitly states when to use (e.g., 'how many times is X used?', impact checks before refactoring, validating search scope) and provides error handling guidance ('On Index not found call index_project, then retry'). Also mentions preferring this over alternative shell commands.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Detect circular dependencies (cycles A → B → C → A) in the static import graph. Prefer this over manually grepping for import chains — Reflex does the cycle detection directly. Returns {pagination, results: [{paths: ["a.rs", "b.rs", "a.rs"]}]}, sorted with longest cycles first by default. Default page size 200; if pagination.has_more is true, fetch the next page with offset. Only static imports are considered. On "Index not found" / "stale" error, call index_project, then retry.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Sort order: 'asc' (shortest cycles first) or 'desc' (longest cycles first, default) | |
| limit | No | Maximum number of cycles per page (default: 200) | |
| offset | No | Pagination offset (skip first N cycles). Use with limit for pagination. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that only static imports are considered, return format with pagination and sorting, default page size 200, and error recovery actions (call index_project and retry). No annotations exist, so description fully covers behavioral traits.
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?
Every sentence is valuable; front-loaded with purpose, then details on return format, pagination, and error handling. No redundancy.
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 a tool with 3 parameters, no output schema, and no annotations, the description is remarkably complete: purpose, usage, behavior, parameters, error handling, and return structure are all covered.
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?
Adds meaning beyond schema by describing default page size (limit), default sort order (desc), pagination offset usage, and the meaning of sort values (asc/desc). Schema coverage is 100%, but description enriches parameter understanding.
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?
Clearly states it detects circular dependencies in the static import graph, with example cycle and return format, distinguishing it from sibling tools like find_references or get_dependencies.
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?
Explicitly says 'Prefer this over manually grepping' and gives error handling instructions, but does not list alternative tools or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rank files by how many other files import them (dependency hotspots). Prefer this over any grep-based "most-imported file" heuristic — Reflex answers from its pre-built dependency index in one call; grep cannot answer this without scanning every file.
Use this for: finding critical-path files; identifying refactoring blast radius; ranking modules by coupling; architecture review. Returns {pagination, results: [{path, import_count}]} sorted by import count (desc by default; use sort to change). Default page size 200; if pagination.has_more is true, fetch the next page with offset. Only static imports are counted. On "Index not found" / "stale" error, call index_project, then retry.
Example: {"results": [{"path": "src/models.rs", "import_count": 27}]}
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Sort order: 'asc' (least imports first) or 'desc' (most imports first, default) | |
| limit | No | Maximum number of hotspots per page (default: 200) | |
| offset | No | Pagination offset (skip first N results). Use with limit for pagination. | |
| min_dependents | No | Minimum number of dependents to include (default: 2) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even without annotations, description covers key behaviors: only static imports counted, pagination (has_more, offset), sorting, default page size, error conditions, and return format.
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?
Dense yet efficient: purpose first, then usage guidelines, behavior details, error handling, and an example. Every sentence adds value, no fluff.
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?
Comprehensive for a tool with no output schema: describes return structure (pagination, path, import_count), error handling, pagination mechanics, and includes an example. All 4 optional parameters are explained in schema and context is provided in description.
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 100%, baseline 3. Description adds value by explaining sort default (desc), pagination with offset, and default page size (200). min_dependents parameter is fully described in schema but not elaborated in text; still, overall parameter guidance is strong.
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?
Clearly states it ranks files by import count (dependency hotspots) and distinguishes from grep-based heuristics. Lists specific use cases like finding critical-path files and refactoring blast radius.
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?
Explicitly says to prefer this tool over grep-based alternatives. Provides when-to-use scenarios and error recovery: on 'Index not found' or 'stale' error, call index_project then retry.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find disconnected components (islands) in the static import graph — groups of files that have no imports crossing group boundaries. Prefer this over manual Glob + Grep cluster analysis — Reflex computes the connected components directly. Returns {pagination, results: [{island_id, size, paths: [...]}]} sorted with largest islands first by default. Default page size 200; if pagination.has_more is true, fetch the next page with offset. Use min_island_size and max_island_size to filter by component size (default: 2–500 files, or 50% of total). Only static imports are considered. On "Index not found" / "stale" error, call index_project, then retry.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Sort order: 'asc' (smallest islands first) or 'desc' (largest islands first, default) | |
| limit | No | Maximum number of islands per page (default: 200) | |
| offset | No | Pagination offset (skip first N islands). Use with limit for pagination. | |
| max_island_size | No | Maximum files in an island to include (default: 500 or 50% of total files) | |
| min_island_size | No | Minimum files in an island to include (default: 2) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description fully discloses key behaviors: static imports only, default sort order, default page size (200), filtering defaults (2–500 files or 50% of total), pagination mechanism, and error recovery steps. Since no annotations are provided, the description carries the full burden and excels.
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?
The description is concise and well-structured: purpose first, then usage/advantage, then output format, then pagination details, then filtering, then error handling. Every sentence adds value without redundancy.
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?
Despite having 5 optional parameters and no output schema, the description covers all critical aspects: purpose, behavior (static imports), return format, pagination, filtering defaults, and error recovery. It is self-contained and comprehensive.
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 100% with clear parameter descriptions. The description adds semantic value by explaining default values (e.g., 'default: 2–500 files, or 50% of total'), sort behavior, and pagination usage, enhancing understanding beyond the schema alone.
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?
The description clearly states 'Find disconnected components (islands) in the static import graph' with a precise definition. It distinguishes this tool from siblings (e.g., find_circular, find_hotspots) by focusing on disconnected groups, making its purpose unmistakable.
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 advises preferring this tool over manual alternative methods and provides error-handling guidance ('call index_project, then retry'). It implicitly indicates when to use (for islands) but does not explicitly list when not to use it relative to siblings, though context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Atomic symbol definition + every usage in one call. Prefer this over the two-step Grep-based find-all-callers pattern (grep -rn X then filter to call sites by eye) and over chaining search_code(symbols=true) + search_code() — find_references returns both the definition and all call sites in a single call, complete with no follow-up searches needed.
Use this for: "find all callers of X" (the most common agent refactoring task); impact analysis before changing a function or class; rename planning; dead-code detection before deleting a function.
By default, matches inside string literals and comments are excluded (so test fixtures and doc comments don't drown out real call sites); pass include_strings: true to restore all occurrences. Returns {definition, references, total_references, pagination, status} where definition is the first symbol definition ({path, line, kind, symbol, span, preview}) or null, and references is a flat array of {path, line, preview} covering every textual occurrence including the definition site itself. Pagination applies to references only; if pagination.has_more is true, fetch the next page with offset. On "Index not found" / "stale" error, call index_project, then retry.
| Name | Required | Description | Default |
|---|---|---|---|
| glob | No | Include files matching glob patterns (e.g., ['src/**/*.rs']) | |
| kind | No | Filter definition lookup by symbol kind (function, class, struct, trait, etc.) | |
| lang | No | Filter by language (rust, typescript, python, go, etc.) | |
| mode | No | Response mode: "list" (default) returns full results with definition + references; "count" returns only {count, pattern} — faster, skips match body serialization. | |
| force | No | Force execution of potentially expensive queries (bypasses broad query detection) | |
| limit | No | Max references per page (default: 200, max: 500). The 200-result default covers most find-all tasks in a single call. Pagination applies to references only. | |
| offset | No | Pagination offset for references (skip first N). Use with limit. | |
| exclude | No | Exclude files matching glob patterns (e.g., ['target/**', 'tests/**']) | |
| pattern | Yes | Symbol name or text pattern to find references for (e.g., 'CacheManager', 'extract_symbols') | |
| include_strings | No | Include matches inside string literals and comments (default: false). By default these are excluded to focus on real call sites. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description fully discloses default behavior (excludes strings/comments), response structure, pagination details, and error handling (call index_project on stale index). This compensates for missing annotations.
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?
The description is well-structured and front-loaded with purpose, but slightly verbose. Every sentence adds value, though it could be tightened without losing clarity.
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?
Given the tool's complexity (10 parameters, no output schema), the description covers return structure, pagination, and error recovery comprehensively. It leaves little ambiguity for an AI agent.
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 100%, yet the description adds meaningful context beyond schema: e.g., default limit covers most tasks in one call, mode shortcuts, and include_strings semantics. It enhances understanding without redundancy.
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?
The description clearly states the tool's purpose: 'Atomic symbol definition + every usage in one call.' It distinguishes from sibling tools like grep-based patterns and chaining search_code, making the value proposition explicit.
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?
Explicit usage guidance is provided: 'Use this for: find all callers of X, impact analysis, rename planning, dead-code detection.' It also contrasts with alternative patterns, offering clear when-to-use recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List files that no other file imports — orphan candidates for deletion. Prefer this over manual Glob + Grep cross-referencing — Reflex answers from the static import graph in one call. Returns {pagination, results: ["src/unused.rs", "tests/old.rs", ...]}. Default page size 200; if pagination.has_more is true, fetch the next page with offset. Note: entry points (main.rs, index.ts) appear as unused by design — do not delete them. Only static imports are considered. On "Index not found" / "stale" error, call index_project, then retry.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of unused files per page (default: 200) | |
| offset | No | Pagination offset (skip first N files). Use with limit for pagination. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses that only static imports are considered, that entry points are false positives, pagination behavior (default page size 200, offset), and return structure. Fully transparent beyond schema.
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?
Single well-structured paragraph front-loaded with core purpose, followed by usage advice, output format, pagination details, important notes, and error handling. Every sentence adds value, no wasted words.
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?
Given no output schema, description includes return shape and pagination. Covers special cases (entry points), error recovery, and static import limitation. Complete for a listing tool with pagination and error states.
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 100%, but description adds meaning: explains default limit value (200) and how offset works for pagination. Also shows output format with example. Adds value beyond the schema.
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?
Clear verb ('List files that no other file imports') and resource ('orphan candidates for deletion'). Distinguishes from siblings by mentioning it uses the static import graph, avoiding manual cross-referencing.
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?
Explicitly states when to prefer this tool over alternatives ('Prefer this over manual Glob + Grep cross-referencing'), warns about entry points appearing unused, and provides error recovery steps ('On "Index not found" / "stale" error, call index_project, then retry').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One-shot codebase orientation: structure, file types, project type, frameworks, entry points, test layout, config files. Prefer this over Glob-based recon at session start — Reflex returns a single consolidated overview instead of multiple glob calls. By default (no parameters) all context types are gathered; pass individual flags (structure, framework, entry_points, etc.) for a focused slice. Use depth to control tree depth (default 2) and path to focus on a subdirectory.
Use this for: getting oriented in an unfamiliar codebase; locating entry points; confirming which frameworks/languages are in use. For finding where a specific symbol/pattern lives, use search_code or find_references instead.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Focus on specific directory path | |
| depth | No | Tree depth for structure (default: 2) | |
| framework | No | Detect frameworks and conventions | |
| structure | No | Show directory structure | |
| file_types | No | Show file type distribution | |
| test_layout | No | Show test organization pattern | |
| config_files | No | List important configuration files | |
| entry_points | No | Show entry point files | |
| project_type | No | Detect project type (CLI/library/webapp/monorepo) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries behavioral disclosure. It explains default behavior (all context types gathered), flag usage for focused slices, and depth/path control. It doesn't describe response format or side effects, but the read nature implies no mutation, and the consolidated overview is implied. Good but not exhaustive.
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?
The description is well-structured with separate sentences for purpose, usage guidance, and parameter details. It is slightly verbose but front-loads key actions and the recommendation. Could be more concise, but every sentence adds value.
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?
Given 9 optional parameters, no output schema, and 16 siblings, the description covers purpose, usage, parameter semantics, and differentiation. It lacks output format details, but the tool's simplicity (overview) makes this acceptable. The guidance is complete for selection and invocation.
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 100% and description adds significant meaning: explains each boolean flag's effect (e.g., 'Show directory structure'), clarifies defaults (depth: 2), and notes that omitting all flags gathers everything. This enriches understanding beyond the schema.
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?
The description clearly states the tool's purpose: 'One-shot codebase orientation' covering structure, file types, project type, frameworks, etc. It distinguishes from siblings by recommending over 'Glob-based recon' and contrasting with 'search_code' or 'find_references' for specific symbol lookup.
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?
Explicit 'Use this for' and 'instead' clauses provide clear when-to or when-not-to guidance. It identifies specific scenarios (unfamiliar codebase, locating entry points) and names alternative tools for different needs (search_code, find_references).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every import (dependency) of a single file. Prefer this over grep-ing for import / use / require statements — Reflex answers from its pre-built import index, which grep cannot replicate without scanning every file. Returns one object per import with path, line, type (internal/external/stdlib), and optional symbols.
Use this for: understanding file dependencies, analyzing import structure, finding what a file depends on. Path matching is fuzzy — exact paths, fragments, or bare filenames all work. Only static imports (string literals) are extracted; dynamic imports are filtered by design. On "Index not found" / "stale" error, call index_project, then retry.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | File path (supports fuzzy matching: 'Controllers/FooController.php' or just 'FooController.php') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: returns object per import with path/line/type/symbols, supports fuzzy path matching, extracts only static imports, and handles stale index errors. This is comprehensive and goes beyond basic expectations.
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?
The description is well-structured, starting with the core action, then providing guidelines, use cases, parameter details, and error handling. Every sentence adds value without redundancy, making it efficient and informative.
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?
Given the single parameter, no output schema, and no annotations, the description covers all necessary aspects: purpose, usage, behavioral details, parameter specifics, and error recovery. It is fully self-contained and leaves no critical gaps.
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?
The input schema has 100% coverage with a description for the 'path' parameter. The description adds extra context about fuzzy matching and examples (e.g., 'Controllers/FooController.php' vs 'FooController.php'), enhancing understanding beyond the schema alone.
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?
The description clearly states the tool lists every import of a single file, using a specific verb and resource. It distinguishes itself from alternatives like grep and sibling tools by emphasizing the pre-built import index, making the purpose unambiguous.
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?
Explicitly advises when to use this tool over grep, lists specific use cases (understanding dependencies, analyzing structure), and provides error recovery instructions (call index_project then retry). This gives clear guidance on when and how to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reverse dependency lookup — find every file that imports a given file. Prefer this over grep-based find-callers: Reflex answers from its pre-built reverse-import index in one call, which grep cannot replicate without scanning every file. Returns the list of importing file paths.
Use this for: impact analysis before changing a module; finding consumers of a library; detecting file importance. Path matching is fuzzy — exact paths, fragments, or bare filenames all work. Only static imports (string literals) are considered; dynamic imports are filtered by design. On "Index not found" / "stale" error, call index_project, then retry.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | File path (supports fuzzy matching: 'models/User.php' or just 'User.php') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses behavioral traits: built from pre-built reverse-import index, returns list of file paths, fuzzy matching, only static imports considered, dynamic imports filtered. Also mentions error handling and recovery.
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?
The description is brief and front-loaded with purpose. The three sentences contain no fluff: each sentence adds essential information about functionality, usage scenarios, and error recovery. Perfectly concise.
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?
With one parameter, no output schema, and no annotations, the description covers all aspects: purpose, mechanism (reverse-import index), usage guidelines, parameter behavior (fuzzy matching), limitations (static imports only), and error handling. It is self-contained and complete.
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 100% for the single 'path' parameter, with a description in the schema itself. The tool description adds clarification on fuzzy matching (exact paths, fragments, bare filenames) but does not significantly enhance beyond the schema. A score of 4 reflects effective but not exceptional additional value.
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?
The description starts with 'Reverse dependency lookup — find every file that imports a given file,' clearly stating the verb (find/reverse lookup) and resource (files importing a given file). It distinguishes from sibling tools like 'get_dependencies' and 'grep-based find-callers'.
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?
Explicitly states when to use: 'impact analysis before changing a module; finding consumers of a library; detecting file importance.' Also advises preferring over grep-based alternatives and provides recovery steps for errors: 'On Index not found / stale error, call index_project, then retry.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Walk the transitive dependency tree of a file up to depth levels (default 3). Prefer this over hand-rolling recursive grep across imports — Reflex traverses the static import graph directly, returning a map of file → depth.
Use this for: understanding the full dependency chain, analyzing deep coupling, planning refactoring blast radius. Example: depth=2 finds file → deps → deps of deps. Only static imports (string literals) are followed; dynamic imports are filtered by design. On "Index not found" / "stale" error, call index_project, then retry.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | File path (supports fuzzy matching) | |
| depth | No | Maximum depth to traverse (default: 3, max recommended: 5) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavior: only static imports are followed, dynamic imports are filtered, it returns a map of file to depth, and handles errors. This exceeds the burden for a tool without annotations.
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?
The description is well-structured with separate concerns: main action, use cases, example, constraints, and error handling. Each sentence contributes meaningful information, though it could be slightly more concise without losing clarity.
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?
Despite lacking an output schema, the description explains the return format as a map of file to depth. It covers error recovery and constraints. Some detail about the map's exact structure (e.g., depth as integer) is implied but not explicit, which is acceptable.
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 100% with descriptions for both parameters. The description adds value by specifying default depth (3), max recommended depth (5), and that path supports fuzzy matching. This goes beyond the schema's explanations.
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?
The description clearly states it walks the transitive dependency tree of a file up to a specified depth. It specifies verb 'walk', resource 'transitive dependency tree', and result 'map of file → depth'. It distinguishes from siblings by recommending this over 'hand-rolling recursive grep' and noting that it only follows static imports.
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 explicitly lists use cases: understanding dependency chains, analyzing coupling, planning refactoring. It provides an example with depth=2 and advises on error handling (call index_project on 'Index not found' and retry). It could be improved by explicitly contrasting with siblings like get_dependencies or find_references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rebuild or update the code search index. Call this whenever any Reflex search tool returns an "Index not found" or "stale" error — the retry will then succeed. Also call after large git operations (checkout, merge, rebase, pull), user file edits, or when results seem stale or missing.
Incremental by default (only changed files re-indexed). Pass force: true for a full rebuild when the index appears corrupted.
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | Force full rebuild (ignore incremental) | |
| languages | No | Languages to include (empty = all) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that the tool is incremental by default and describes the effect of `force: true`. However, it does not mention any potential side effects like blocking or unavailability during rebuild.
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?
Two succinct paragraphs: first states purpose and usage triggers, second explains incremental/force behavior. Every sentence adds value with no repetition or fluff.
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?
Covers the tool's purpose, when to use, and parameter effects. Lacks details about return values or success/failure indicators, but given the absence of an output schema, this is not a critical gap. Overall comprehensive for a maintenance tool.
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 100% and each parameter has a description. The tool description reinforces the meaning of `force` (full rebuild) but does not add new information beyond the schema. Baseline 3 is appropriate.
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?
The description clearly states 'Rebuild or update the code search index,' using a specific verb and resource. It distinguishes itself from sibling tools (which focus on searching/analysis) by being an indexing maintenance tool.
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?
Provides explicit when-to-use scenarios: when search tools return 'Index not found' or 'stale' errors, after git operations, file edits, or stale results. Also differentiates incremental vs full rebuild with the `force` parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Cheapest way to find every place a pattern occurs. Prefer this over Glob-based path hunting and over Grep when you only need file + line numbers (no previews). Returns an array of {path, line} objects — one per match, no limit.
Use this for: enumerating locations before deciding which files to Read; counting affected sites; listing all hits of a pattern without paying for previews. Supports lang, file, glob, exclude filters.
Example: pattern: "CourtCase" → [{"path": "app/Models/CourtCase.php", "line": 15}, {"path": "app/Http/Controllers/CourtController.php", "line": 42}]. On "Index not found" / "stale" error, call index_project, then retry.
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | Filter by file path substring (e.g., 'Controllers') | |
| glob | No | Include files matching patterns (e.g., ['app/**/*.php']) | |
| lang | No | Filter by language (php, rust, typescript, python, etc.) | |
| force | No | Force execution of potentially expensive queries (bypasses broad query detection) | |
| exclude | No | Exclude files matching patterns (e.g., ['vendor/**', 'tests/**']) | |
| pattern | Yes | Search pattern (text to find) | |
| dependencies | No | Include dependency information (imports) in results. Only extracts static imports. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses there is no result limit, mentions error handling ('Index not found' -> call index_project), and implies read-only operation. Doesn't describe side effects or resource usage in depth, but sufficient.
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?
Description is well-structured with purpose, usage, example, and error handling. Could be slightly more concise, but front-loads the key purpose and differentiation.
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?
Given 7 parameters and no output schema, description covers output format, error recovery, and usage context. Lacks detail on some parameters like 'dependencies', but overall sufficient for agent decision-making.
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 100%, so baseline is 3. Description adds little beyond listing supported filters and providing an example; does not explain 'force' or 'dependencies' beyond schema.
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?
The description clearly states the tool finds every place a pattern occurs, returns file+line objects, and explicitly distinguishes it from Glob and Grep. It also mentions the output format with an example.
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?
Provides explicit when-to-use scenarios (enumerating locations before reading, counting hits, listing without previews). Does not explicitly state when not to use it, but contrasts with alternatives upfront.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Structure-aware search using Tree-sitter AST patterns (S-expressions). ⚠️ SLOW: bypasses trigram optimization and scans the ENTIRE codebase (500ms-10s+). In 95% of cases, prefer search_code with symbols: true instead (10-100x faster).
Use this only when you must match code structure rather than text: "all async functions containing a match expression", "every class with a serialize method", etc. You MUST pass glob to limit scope — without it, every file in the codebase is parsed.
Example patterns — Rust: (function_item) @fn; Python: (function_definition) @fn; TypeScript: (class_declaration) @class. Refer to Tree-sitter grammar docs for each language. On "Index not found" / "stale" error, call index_project, then retry.
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | Filter by file path (substring) | |
| glob | No | Include files matching glob patterns (STRONGLY RECOMMENDED to limit scope, e.g., ['src/**/*.rs']) | |
| lang | Yes | Language (REQUIRED: rust, typescript, javascript, python, go, java, c, cpp, csharp, php, ruby, kotlin, zig) | |
| force | No | Force execution of potentially expensive queries (bypasses broad query detection) | |
| limit | No | Maximum number of results (use with offset for pagination) | |
| paths | No | Return only unique file paths | |
| offset | No | Pagination offset (skip first N results after sorting) | |
| exclude | No | Exclude files matching glob patterns (e.g., ['target/**', 'node_modules/**']) | |
| pattern | Yes | AST pattern (Tree-sitter S-expression, e.g., '(function_item) @fn') | |
| dependencies | No | Include dependency information (imports) in results. Only extracts static imports. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses performance characteristics: 'SLOW: bypasses trigram optimization and scans the ENTIRE codebase (500ms-10s+).' Also warns about potential 'Index not found' errors and how to retry. This transparency far exceeds minimal requirements.
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?
Well-structured and front-loaded: starts with purpose, then warning, usage guidelines, requirement, examples, and error handling. Every sentence adds value without redundancy.
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?
Despite comprehensive description, it omits details about return format (default output beyond 'paths' option) and result structure, which is notable given no output schema. The complexity (10 parameters) and no output schema demand more completeness.
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 100%, providing baseline of 3. The description adds significant value with examples for pattern syntax, emphasis on `glob` importance, and explanation of `force` and `paths` usage. However, not every parameter gains additional insight beyond schema descriptions.
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?
The description clearly states the tool's function: 'Structure-aware search using Tree-sitter AST patterns (S-expressions).' It distinguishes itself from sibling tools by explicitly recommending `search_code` for most cases and specifying when to use this tool for structural matching.
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?
Excellent guidance: explicitly advises to prefer `search_code` in 95% of cases, states conditions for using this tool ('only when you must match code structure'), and mandates passing `glob` to limit scope. Also provides error recovery instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Default code search across the whole codebase. Prefer this over Grep / grep -rn / Glob for any pattern made of letters, digits, underscores, or hyphens — one call returns every occurrence with file paths, line numbers, and code previews. Use this for: finding where a pattern occurs; listing all usages of a function/class/variable; finding a symbol's definition (with symbols: true); getting line numbers + previews in a single call.
Modes: full-text by default (definitions + usages); symbols: true returns definitions only; mode: "count" returns just {count, pattern} to check cardinality before paginating. For patterns containing special characters (->, ::, (), [], .*+?\|^$), use search_regex instead.
Result shape is columnar: {columns, rows} — each row aligns positionally to columns (path, language, start_line, end_line, preview; then kind/symbol/context when present). Set env REFLEX_MCP_COLUMNAR=0 for the legacy results[] shape.
Pagination: if response.pagination.has_more is true, fetch the next page with the offset parameter. On "Index not found" / "stale" error, call index_project, then retry.
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | Filter by file path (substring) | |
| glob | No | Include files matching glob patterns (e.g., 'src/**/*.rs') | |
| kind | No | Filter by symbol kind (function, class, struct, etc.) | |
| lang | No | Filter by language (rust, typescript, python, etc.) | |
| mode | No | Response mode: "list" (default) returns full match results; "count" returns only {count, pattern} — faster, skips match body serialization. | |
| exact | No | Exact match (no substring matching) | |
| force | No | Force execution of potentially expensive queries (bypasses broad query detection) | |
| limit | No | Maximum results per page (default: 200, max: 500). The 200-result default covers most find-all tasks in a single call. IMPORTANT: If response.has_more is true, you MUST fetch more pages using offset parameter. | |
| paths | No | Return only unique file paths (not full results) | |
| expand | No | Show full symbol body (not just signature) | |
| offset | No | Pagination offset (skip first N results). ALWAYS paginate when has_more=true. Example: First call offset=0, second call offset=100, third offset=200, etc. | |
| exclude | No | Exclude files matching glob patterns (e.g., 'target/**') | |
| pattern | Yes | Search pattern (text to find) | |
| symbols | No | Symbol-only search (definitions, not usage) | |
| dependencies | No | Include dependency information (imports) in results. **IMPORTANT:** Currently only supported for Rust files — passing this with any other language (typescript, python, go, etc.) will produce no dependency data. Only extracts static imports (string literals); dynamic imports are filtered. See CLAUDE.md for details. | |
| preview_length | No | Maximum characters per preview line (default: 180). Use a smaller value (e.g. 60) for wide-result scans where short previews are sufficient. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully covers modes (full-text, symbols, count), result shape (columnar vs legacy), pagination behavior, error handling (call `index_project` on stale index), and parameter-specific limitations (e.g., `dependencies` only for Rust).
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?
Well-structured with sections for summary, modes, result shape, pagination, error handling. Front-loaded with purpose. Slightly lengthy with some details (e.g., environment variable) that could be omitted but overall organized.
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?
Given 16 parameters and no output schema, the description covers all critical behaviors: modes, pagination, error handling, result format, and parameter-specific caveats. Complete for selecting and invoking the tool.
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?
Every parameter has a schema description (100% coverage). The tool description adds extra context beyond schema, e.g., for `limit`, `dependencies`, `mode`, `preview_length`, clarifying defaults, important notes, and usage tips.
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?
The description clearly states it is the default code search for the whole codebase, specifying the verb 'search' and resource 'codebase'. It distinguishes from sibling tools like `search_regex` by noting pattern constraints.
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?
Provides explicit when-to-use scenarios (finding occurrences, usages, definitions) and when-not-to-use (special characters -> use `search_regex`). Includes pagination and error handling instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Regex code search across the whole codebase. Prefer this over rg / grep -E / grep -P for pattern matching across files — one call returns every match with file paths, line numbers, and previews.
Use this for patterns with special characters or regex operators: ->with\(, ::new\(, fn (get|set)_\w+, \[(derive|test)\], \bAuth\w*Controller\b, alternation a|b, anchors ^$, wildcards .*. Escaping: must escape ( ) [ ] { } . * + ? \\ | ^ $; no escaping needed for -> :: - _ / = < >; in JSON use double backslashes (\\(, \\[).
For simple alphanumeric patterns use search_code instead — it is faster and avoids escaping overhead. For symbol definitions use search_code with symbols: true.
mode: "count" returns {count, pattern} only. List-mode result shape is columnar: {columns, rows} — each row aligns positionally to columns (path, language, start_line, end_line, preview; then kind/symbol/context when present). Set env REFLEX_MCP_COLUMNAR=0 for the legacy results[] shape. Pagination: if response.pagination.has_more is true, fetch the next page with offset. On "Index not found" / "stale" error, call index_project, then retry.
| Name | Required | Description | Default |
|---|---|---|---|
| file | No | Filter by file path | |
| glob | No | Include files matching glob patterns | |
| lang | No | Filter by language | |
| mode | No | Response mode: "list" (default) returns full match results; "count" returns only {count, pattern} — faster, skips match body serialization. | |
| force | No | Force execution of potentially expensive queries (bypasses broad query detection) | |
| limit | No | Maximum number of results (default: 200, max: 500). Use with offset for pagination. | |
| paths | No | Return only unique file paths | |
| offset | No | Pagination offset (skip first N results after sorting) | |
| exclude | No | Exclude files matching glob patterns | |
| pattern | Yes | Regex pattern | |
| dependencies | No | Include dependency information (imports) in results. Only extracts static imports. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description thoroughly explains behavior including result structure (columnar), pagination (offset, has_more), error handling (index_project), and output customization (env var). It does not explicitly state read-only, but the nature of search implies no side effects. Lacks explicit mention of idempotency.
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?
The description is efficiently organized with clear sections, immediate purpose statement, and concise guidance. While it is longer than some, the information density justifies the length; no redundant sentences.
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 a tool with no output schema and no annotations, the description is remarkably complete. It addresses purpose, when to use, parameter semantics, result format, pagination, error recovery, and configuration options. Few gaps remain.
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?
The description significantly enriches parameter semantics with concrete examples and escaping rules for the `pattern` parameter, clarifies mode behavior, pagination details, and glob filtering. It leverages the high schema coverage to provide actionable guidance rather than redundancy.
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?
The description explicitly defines the tool's function as regex code search across the entire codebase, distinguishes it from alternatives like search_code and rg/grep, and details the output format (file paths, line numbers, previews). No ambiguity.
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 provides explicit when-to-use and when-not-to-use guidance, directly naming alternatives (search_code, rg/grep) and specifying conditions (simple patterns vs regex, symbol searches). It also gives context for mode selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.6.0find_references3 fields changedInput schema / properties / include_stringsAdded value: +{
+ "description": "Include matches inside string literals and comments (default: false). By default these are excluded to focus on real call sites.",
+ "type": "boolean"
+}Input schema / properties / limit / descriptionPrevious value: -"Max references per page (default: 100). Pagination applies to references only."New value: +"Max references per page (default: 200, max: 500). The 200-result default covers most find-all tasks in a single call. Pagination applies to references only."Input schema / properties / modeAdded value: +{
+ "description": "Response mode: \"list\" (default) returns full results with definition + references; \"count\" returns only {count, pattern} — faster, skips match body serialization.",
+ "enum": [
+ "list",
+ "count"
+ ],
+ "type": "string"
+}search_code2 fields changedInput schema / properties / limit / descriptionPrevious value: -"Maximum results per page (default: 100). IMPORTANT: If response.pagination.has_more is true, you MUST fetch more pages using offset parameter."New value: +"Maximum results per page (default: 200, max: 500). The 200-result default covers most find-all tasks in a single call. IMPORTANT: If response.has_more is true, you MUST fetch more pages using offset parameter."Input schema / properties / modeAdded value: +{
+ "description": "Response mode: \"list\" (default) returns full match results; \"count\" returns only {count, pattern} — faster, skips match body serialization.",
+ "enum": [
+ "list",
+ "count"
+ ],
+ "type": "string"
+}search_regex2 fields changedInput schema / properties / limit / descriptionPrevious value: -"Maximum number of results (use with offset for pagination)"New value: +"Maximum number of results (default: 200, max: 500). Use with offset for pagination."Input schema / properties / modeAdded value: +{
+ "description": "Response mode: \"list\" (default) returns full match results; \"count\" returns only {count, pattern} — faster, skips match body serialization.",
+ "enum": [
+ "list",
+ "count"
+ ],
+ "type": "string"
+}v1.0.0analyze_summarycheck_index_statuscount_occurrencesfind_circularfind_hotspotsfind_islandsfind_referencesfind_unusedgather_contextget_dependenciesget_dependentsget_transitive_depsindex_projectlist_locationssearch_astsearch_codesearch_regexEach tool targets a distinct aspect of codebase analysis (search, dependency, structure, indexing) with clear differences. Overlaps between list_locations and search_code are well-explained, and all tools have unique purposes.
Tool names are mostly consistent with a verb_noun pattern (search_code, find_references, count_occurrences), though a few use different orders (gather_context, analyze_summary, check_index_status). Still readable and predictable.
17 tools is somewhat high for a typical server, but each serves a distinct, well-justified purpose in code analysis. The count feels appropriate for the comprehensive scope, though it borders on heavy.
The tool set covers text, regex, and AST search; dependency analysis; indexing; and project orientation. No critical gaps like missing update/delete/creation tools, but those are out of scope for analysis.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Ask a codebase what calls what: search, blast radius, paths between symbols, and diffs.
Search independent software the big engines bury: indie apps, open-source repos, and dev tools.
Search GitHub, npm, PyPI, StackOverflow, ArXiv from one MCP — built for coding agents.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/reflex-search/reflex'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
