Windsurf Cascade provides six search and discovery tools for codebase navigation: codebase_search for semantic code discovery, grep_search for exact pattern matching, find_by_name for file/directory discovery, view_code_item for viewing specific code symbols, view_file for line-range content retrieval, and list_dir for directory content inspection.
These tools form the context gathering layer that precedes file editing operations. For file editing workflows, see page 5.2.5. For the complete tool ecosystem, see page 5.2.2.
The six search and discovery tools are organized into three functional layers:
Tool Organization and Function Signatures
The search layer (codebase_search, grep_search, find_by_name) discovers code locations. The viewing layer (view_code_item, view_file, list_dir) retrieves content. Both layers feed into replace_file_content for editing operations.
Sources: Windsurf/Tools Wave 11.txt35-43 Windsurf/Tools Wave 11.txt134-155 Windsurf/Tools Wave 11.txt102-124 Windsurf/Tools Wave 11.txt314-322 Windsurf/Tools Wave 11.txt334-351 Windsurf/Tools Wave 11.txt163-169
The codebase_search tool performs semantic search across the codebase to find code snippets most relevant to a natural language query.
Sources: Windsurf/Tools Wave 11.txt36-43
| Property | Value | Implementation Detail |
|---|---|---|
| Search Type | Semantic | Interprets purpose, not literal text |
| File Limit | 500 files | Quality degrades beyond this threshold |
| Result Format | Mixed | Top items: full code (may be truncated) Other items: docstring + signature only |
| Output Filtering | Top results only | Variable count based on relevance |
| Optimal Use Case | Precise purpose queries | "How is JWT token validated?" |
| Poor Use Case | Broad queries | "General framework implementation" |
Sources: Windsurf/Tools Wave 11.txt35-43
The Query parameter performs best with specific, purpose-oriented text. System documentation states: "This performs best when the search query is more precise and relating to the function or purpose of code. Results will be poor if asking a very broad question."
Query Quality Examples
Sources: Windsurf/Tools Wave 11.txt35-43
The system enforces a quality constraint on the TargetDirectories parameter: "if you try to search over more than 500 files, the quality of the search results will be substantially worse." This is a degradation threshold, not a hard limit.
Mitigation Strategy: Restrict TargetDirectories to specific subsystems:
Sources: Windsurf/Tools Wave 11.txt35-43
The tool returns results in a hierarchical format:
view_code_item lookupsFollow-up pattern: When results show only docstrings/signatures, call view_code_item with the same path and node name to retrieve full content.
Sources: Windsurf/Tools Wave 11.txt35-43 Windsurf/Tools Wave 11.txt314-322
The grep_search tool uses ripgrep to find exact pattern matches within files, providing precise text search with regex support.
The tool uses ripgrep internally for pattern matching with results capped at 50 matches.
Sources: Windsurf/Tools Wave 11.txt134-155
| Parameter | Type | Purpose | Default Behavior |
|---|---|---|---|
Query | string | Search term or regex pattern | Required |
SearchPath | string | Directory or file to search | Required |
CaseInsensitive | boolean | Ignore case in matches | N/A |
IsRegex | boolean | Treat Query as regex (vs literal) | false recommended |
MatchPerLine | boolean | Return lines (true) or filenames (false) | N/A |
Includes | string[] | Glob patterns to filter files | Empty = all files |
The MatchPerLine parameter controls output granularity:
MatchPerLine Behavior
System documentation states: "Results are returned in JSON format and for each match you will receive the: Filename, LineNumber, LineContent" when MatchPerLine is true.
Sources: Windsurf/Tools Wave 11.txt134-155
The Includes parameter applies glob patterns to files within SearchPath. System documentation clarifies: "Glob patterns to filter files found within the 'SearchPath', if 'SearchPath' is a directory... This is NOT for specifying the primary search directory; use 'SearchPath' for that."
| Pattern | Behavior | Use Case |
|---|---|---|
['*.go'] | Include only Go files | File type filtering |
['!**/vendor/*'] | Exclude vendor directories | Directory exclusion |
['*.ts', '*.tsx'] | Include TypeScript files | Multiple extension matching |
[] (empty) | No filtering | Search all files |
The parameter is unused when SearchPath points to a single file.
Sources: Windsurf/Tools Wave 11.txt143-144
The IsRegex parameter controls Query interpretation. System documentation states: "If true, treats Query as a regular expression pattern with special characters like *, +, (, etc. having regex meaning. If false, treats Query as a literal string where all characters are matched exactly."
| IsRegex Value | Query Treatment | Character Interpretation | Recommended Use |
|---|---|---|---|
false | Literal string | All characters matched exactly | Normal text searches |
true | Regular expression | *, +, (), etc. have regex meaning | Pattern matching requirements |
System guidance: "Use false for normal text searches and true only when you specifically need regex functionality."
Sources: Windsurf/Tools Wave 11.txt145-146
Total results are capped at 50 matches. When hitting this limit:
Includes to filter by file typeSearchPath to specific directoriesQuery more specificSources: Windsurf/Tools Wave 11.txt139
The find_by_name tool uses the fd utility to search for files and directories by name using glob patterns.
The tool uses the fd utility internally with smart case sensitivity and gitignore respect by default.
Sources: Windsurf/Tools Wave 11.txt102-124
Sources: Windsurf/Tools Wave 11.txt102-124
| Feature | Behavior | Notes |
|---|---|---|
| Case Sensitivity | Smart case | Lowercase = case-insensitive, mixed = case-sensitive |
| Gitignored Files | Ignored by default | Respects .gitignore |
| Result Cap | 50 matches | Use filters to narrow scope |
| Result Fields | Type, size, mtime, relative path | Complete file metadata |
Sources: Windsurf/Tools Wave 11.txt103-106
The FullPath parameter controls pattern matching scope. System documentation states: "whether the full absolute path must match the glob pattern, default: only filename needs to match."
Matching Behavior Examples
| FullPath | Pattern | File Path | Match Result | Reason |
|---|---|---|---|---|
false | '*.py' | /foo/bar.py | ✓ Match | Filename bar.py matches |
false | 'test_*.py' | /src/test_auth.py | ✓ Match | Filename test_auth.py matches |
true | '*.py' | /foo/bar.py | ✗ No match | Full path doesn't start with * |
true | '**/*.py' | /foo/bar.py | ✓ Match | Full path matches glob |
System warning: "Take care when specifying glob patterns with this flag on, e.g when FullPath is on, pattern '.py' will not match to the file '/foo/bar.py', but pattern '**/.py' will match."
Sources: Windsurf/Tools Wave 11.txt112-113
System documentation states: "If you are searching for Extensions, there is no need to specify both Pattern AND Extensions." The parameters serve different use cases:
Parameter Selection Strategy
The Extensions parameter accepts file extensions without the leading dot. Each path must match at least one included extension when specified.
Sources: Windsurf/Tools Wave 11.txt104-105 Windsurf/Tools Wave 11.txt110-111
The view_code_item tool retrieves the full content of specific code symbols (classes, functions, methods) within a file.
The tool returns full content for up to 5 code symbols (classes, functions, methods) per call.
Sources: Windsurf/Tools Wave 11.txt314-322
The NodePaths parameter requires fully qualified symbol names. System documentation states: "You must use fully qualified code item names, such as those return by the grep_search or other tools. For example, if you have a class called Foo and you want to view the function definition bar in the Foo class, you would use Foo.bar as the NodeName."
NodePath Qualification Examples
Path format follows: package.class.FunctionName structure.
Sources: Windsurf/Tools Wave 11.txt314-322
The tool accepts up to 5 node paths in a single call, enabling efficient batch retrieval:
Example: View multiple related methods
Benefit: Reduces tool call overhead when examining related code structures.
Sources: Windsurf/Tools Wave 11.txt314-322
The tool is designed as a follow-up to codebase_search for retrieving truncated content. System documentation states: "Do not request to view a symbol if the contents have been previously shown by the codebase_search tool."
Two-Stage Retrieval Workflow:
codebase_search returns results with file paths and symbol namesview_code_item with the same File and symbol name in NodePathsThis pattern avoids redundant content retrieval when codebase_search already provides full content.
Sources: Windsurf/Tools Wave 11.txt314-322 Windsurf/Tools Wave 11.txt35-43
If a symbol is not found in the specified file, the tool returns an empty string rather than an error. This enables graceful degradation when searching for symbols that may have been moved or renamed.
Sources: Windsurf/Tools Wave 11.txt314-322
The view_file tool retrieves file contents within a specified line range, providing controlled content viewing with context summaries.
The tool returns file content for a specified line range with a maximum of 400 lines per call.
Sources: Windsurf/Tools Wave 11.txt334-351
| Constraint | Value | Behavior |
|---|---|---|
| Line Indexing | 1-indexed | First line is line 1 |
| Range Type | Inclusive | Both StartLine and EndLine included |
| Maximum View | 400 lines | Single call limit |
| Minimum View | 1 line | Can view single line |
Example: StartLine: 10, EndLine: 50 returns lines 10 through 50 (41 lines total).
Sources: Windsurf/Tools Wave 11.txt334-351
The IncludeSummaryOfOtherLines parameter controls whether context outside the requested range is provided:
Sources: Windsurf/Tools Wave 11.txt334-351
The system explicitly assigns responsibility for complete context: "When using this tool to gather information, it's your responsibility to ensure you have the COMPLETE context." System documentation mandates:
Rationale provided: "partial file views may miss critical dependencies, imports, or functionality."
This requirement prevents errors from incomplete information during editing operations.
Sources: Windsurf/Tools Wave 11.txt335-339
For large files, use iterative viewing to navigate efficiently:
Sources: Windsurf/Tools Wave 11.txt334-351
The list_dir tool lists the contents of a directory, providing metadata for each child item.
The tool returns metadata for each child in the directory: relative path, type (file/directory), size in bytes (files), or recursive child count (directories).
Sources: Windsurf/Tools Wave 11.txt163-169
System documentation states: "For each child in the directory, output will have: relative path to the directory, whether it is a directory or file, size in bytes if file, and number of children (recursive) if directory."
| Field | Data Type | Provided When | Content |
|---|---|---|---|
| Relative Path | string | Always | Path relative to DirectoryPath |
| Type | enum | Always | file or directory |
| Size | integer | Type = file | Size in bytes |
| Children Count | integer | Type = directory | Recursive count of descendants |
Output Interpretation Example:
src/auth/, Type: directory, Count: 47 → Directory contains 47 total items (recursive)README.md, Type: file, Size: 2048 → File is 2048 bytesSources: Windsurf/Tools Wave 11.txt163-169
The DirectoryPath parameter must be:
Invalid paths will result in tool errors.
Sources: Windsurf/Tools Wave 11.txt165-166
Primary scenarios:
codebase_searchIntegration with other tools:
find_by_name to understand directory hierarchyTargetDirectories for codebase_searchSearchPath before grep_searchSources: Windsurf/Tools Wave 11.txt163-169
The following table guides tool selection based on search objectives:
| Objective | Tool | Rationale |
|---|---|---|
| "Find functions that handle authentication" | codebase_search | Semantic understanding of intent |
| "Find all occurrences of 'API_KEY'" | grep_search (literal) | Exact text match |
| "Find files named 'config.*'" | find_by_name | Name-based discovery |
| "View the UserService class" | view_code_item | Symbol-level inspection |
| "See lines 50-100 of auth.py" | view_file | Specific line range |
| "What's in the /src directory?" | list_dir | Directory structure |
| "Find files matching /^test_.*.py$/" | grep_search (regex) | Pattern with regex |
| "Find all TypeScript files" | find_by_name with Extensions | File type filter |
| "Show me imports in main.py" | view_file (lines 1-50) | Known location |
| "Find validation logic in auth/" | codebase_search (narrow scope) | Semantic + scoped |
Sources: Windsurf/Tools Wave 11.txt35-351
Common multi-tool workflows for code discovery:
Sources: Windsurf/Tools Wave 11.txt35-351
Scenario: Understanding how a feature works
Sources: Windsurf/Tools Wave 11.txt35-43 Windsurf/Tools Wave 11.txt314-322 Windsurf/Tools Wave 11.txt334-351
Scenario: Finding all usages of a deprecated API
Sources: Windsurf/Tools Wave 11.txt134-155 Windsurf/Tools Wave 11.txt334-351
Scenario: Understanding project structure before refactoring
Sources: Windsurf/Tools Wave 11.txt163-169 Windsurf/Tools Wave 11.txt102-124 Windsurf/Tools Wave 11.txt334-351
Each tool enforces specific constraints affecting performance and result quality:
| Tool | Constraint Type | Limit Value | Effect | Mitigation Strategy |
|---|---|---|---|---|
codebase_search | Quality threshold | 500 files | Results degrade beyond limit | Narrow TargetDirectories to relevant subsystems |
grep_search | Result cap | 50 matches | Stops at 50 | Use Includes for file filtering |
find_by_name | Result cap | 50 matches | Stops at 50 | Increase Pattern specificity or use MaxDepth |
view_code_item | Batch size | 5 nodes/call | Single call limit | Make multiple calls for >5 symbols |
view_file | Line range | 400 lines/call | Single call limit | Use iterative viewing for large files |
list_dir | None explicit | N/A | N/A | N/A |
Sources: Windsurf/Tools Wave 11.txt35-43 Windsurf/Tools Wave 11.txt139 Windsurf/Tools Wave 11.txt105-106 Windsurf/Tools Wave 11.txt314-322 Windsurf/Tools Wave 11.txt334-351
All six search and discovery tools are read-only operations eligible for parallel execution. The system provides a parallel tool that accepts multiple tool invocations.
Parallel Execution Candidates:
codebase_search calls with different TargetDirectoriesgrep_search calls with different SearchPath valuesview_file calls for different filesview_code_item callslist_dir + find_by_name combinationsgrep_search + view_file)Parallel Tool Usage:
System constraint: "only functions tools are permitted" in tool_uses array.
For parallel execution rules across all Windsurf tools, see page 5.2.5.
Sources: Windsurf/Tools Wave 11.txt371-382
Search tools feed directly into Windsurf's file editing system:
Critical workflow requirement: The system mandates gathering complete context before editing. Partial views that miss dependencies lead to broken edits.
For detailed file editing rules and the ReplacementChunk system, see File Editing with ReplacementChunks.
Sources: Windsurf/Tools Wave 11.txt231-260 Windsurf/Tools Wave 11.txt335-339
Refresh this wiki