Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Scantool - File Scanner MCP preview_directory . depth=normal"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server that hands an AI agent a codebase's structure — classes, functions, call graphs, imports, hot functions, all with exact line numbers — instead of raw file dumps. Works with Claude Code, Claude Desktop, Cursor, VS Code and any Model Context Protocol client. 20+ languages via tree-sitter — and code and documents (Markdown, HTML, CSS, SQL, config) through the same lens, which the code-only tools don't do.
What that buys, measured — not claimed:
"Where is the cache invalidated?" scantool 378 tokens / 1 call
grep 9,370 tokens / 4 calls -> 25x less
pytest skipif-caching bug scantool solved in 3 calls
grep gave up after 13,450 tokensOn real agent episodes, scantool agents answered with 88% fact coverage vs 73% for a grep-only agent — better-anchored answers, fewer wrong files. Honest scope: grep still wins plain literal lookups and top-level overviews. Scantool measures both axes and reports the losses too (experiments/benchmark/).
Zero infrastructure: no index to build, no API keys, no vector database, no model downloads. Point it at a directory and it scans on demand.
Requires uv (provides the uvx command). Install it first if you don't have it — without it, scantool will silently fail to start:
# macOS / Linux / WSL
curl -LsSf https://astral.sh/uv/install.sh | sh# Available in all your projects (recommended)
claude mcp add --scope user scantool -- uvx scantool
# Or just for the current project
claude mcp add scantool -- uvx scantoolRestart Claude Code and you're ready to go.
Add to config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"scantool": {
"command": "uvx",
"args": ["scantool"]
}
}
}Restart Claude Desktop after configuration.
Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project):
{
"mcpServers": {
"scantool": {
"command": "uvx",
"args": ["scantool"]
}
}
}Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"scantool": {
"command": "uvx",
"args": ["scantool"]
}
}
}Add to .vscode/mcp.json in your workspace:
{
"servers": {
"scantool": {
"command": "uvx",
"args": ["scantool"]
}
}
}In the Cline panel: MCP Servers icon → Configure tab → Configure MCP Servers, then add the same mcpServers entry as above. (Cline CLI reads ~/.cline/mcp.json.)
uvx not founduvx comes with uv, the Python package manager. Install it first:
# macOS / Linux / WSL
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"After installing uv, restart your terminal (or open a new one) so uvx is on your PATH. Then re-run the setup command above.
If uvx still isn't found after restarting the terminal, add it to your PATH manually:
# Linux / WSL - add to ~/.bashrc or ~/.zshrc:
export PATH="$HOME/.local/bin:$PATH"
# macOS - usually works out of the box, but if not:
export PATH="$HOME/.local/bin:$PATH"git clone https://github.com/mariusei/file-scanner-mcp.git
cd file-scanner-mcp
uv sync
# Claude Code
claude mcp add --transport stdio scantool -- uv run --directory /path/to/file-scanner-mcp scantool
# Claude Desktop
# Use command: "uv", args: ["run", "--directory", "/path/to/file-scanner-mcp", "scantool"]Add a .mcp.json file to your project root to share the config with your team:
{
"mcpServers": {
"scantool": {
"command": "uvx",
"args": ["scantool"]
}
}
}Claude Code will prompt team members for approval on first use.
Related MCP server: MCP Codebase Symbols Server
Python, JavaScript, TypeScript, Rust, Go, C/C++, Java, PHP, C#, Ruby, Zig, Swift, SQL (PostgreSQL, MySQL, SQLite), HTML, CSS, SCSS, Markdown, Plain Text, Images
Classes, methods, functions, imports
Function signatures with type annotations
Decorators and attributes
Docstrings and JSDoc comments
Precise line numbers (from-to ranges)
preview_directory: Intelligent codebase analysis with entry points, import graph, call graph, and hot functions (5-10s)
scan_file: Detailed file structure with signatures and metadata; focus= reads one named function/class/section verbatim with parent context
scan_directory: Compact directory tree with inline function/class names
search_structures: Filter by type, name pattern, decorator, or complexity
list_directories: Directory tree (folders only)
find_divergence: Audit a directory for peer divergence — functions that break a call pattern their siblings follow (peers calling X also call Y, this one doesn't); a review hint, not a verified bug; silent on a consistent codebase. The same section also appears inline in scan_diff (changed code) and preview_directory (deep)
Tree format with box-drawing characters
JSON format for programmatic use
Configurable display options
Analyzes codebase structure including entry points, import graph, call graph, and hot functions.
preview_directory(
directory=".",
depth="deep", # "quick", "normal", or "deep" (default: "deep")
max_files=10000, # Safety limit (default: 10000)
max_entries=20, # Entries per section (default: 20)
respect_gitignore=True # Honor .gitignore (default: True)
)Depth levels:
"quick": Metadata only (0.5s) - file counts, sizes, types
"normal": Architecture analysis (2-5s) - imports, entry points, clusters
"deep": Full analysis (5-10s) - includes hot functions and call graph (default)
Example output (depth="deep"):
project/
--- ENTRY POINTS ---
main.py:main() @1
backend/application.py:Flask app @15
frontend/index.ts:export default
--- CORE FILES (by centrality) ---
backend/database.py: imports 0, used by 15 files
backend/auth.py: imports 1, used by 8 files
shared/utils.py: imports 2, used by 12 files
--- ARCHITECTURE ---
Entry Points: 25 files
Core Logic: 68 files
Plugins: 15 files
Tests: 42 files
--- HOT FUNCTIONS (most called) ---
get_database() (function): called by 41, calls 1 @backend/database.py
authenticate() (function): called by 23, calls 5 @backend/auth.py
validate_input() (function): called by 15, calls 2 @shared/utils.py
Analysis: 486 files in 4.82s (layer1+layer2)Use cases:
First-time codebase exploration
Understanding multi-modality projects (frontend/backend/database)
Finding critical functions (hot spots)
Identifying entry points
scan_file(
file_path="path/to/file.py",
focus=None, # Read ONE node verbatim by name ("query",
# "DatabaseManager.query", a markdown heading)
# instead of guessing line ranges — see below
show_signatures=True, # Include function signatures with types
show_decorators=True, # Include @decorator annotations
show_docstrings=True, # Include first line of docstrings
show_complexity=False, # Show complexity metrics
condense=True, # Condensed skeletons (set False for verbatim lines)
budget=None, # Approx token cap for skeletons — least salient
# functions degrade first, output stays predictable
output_format="tree" # "tree" or "json"
)Example output:
example.py (1-57)
- file-info: 1.4KB modified: 2 hours ago
- imports: import statements (3-5)
- class: DatabaseManager (8-26)
"Manages database connections and queries."
- method: __init__ (self, connection_string: str) (11-13)
- method: connect (self) (15-17)
"Establish database connection."
- method: query (self, sql: str) -> list (24-26)
"Execute a SQL query."
return self.cursor.execute(sql).fetchall()
- function: main () (53-57)
"Main entry point."Functions additionally show their implementation as a condensed method
skeleton: pseudocode lines without line numbers where control flow with
conditions, calls and returns are kept and trivial statements fold to …
(verbatim lines always carry N | line numbers — that's how you tell them
apart). Skeletons come in two tiers: the most salient functions (by entropy,
uniqueness and centrality) get full depth, every other function gets a
shallow depth-2 outline — measured as the best fact-coverage per token.
Markers are plain ASCII because box-drawing glyphs cost 2-3 BPE tokens each.
Pass condense=False to get line-numbered excerpts (top tier only) instead.
Condensation adapts to the language: imperative languages (Python, TypeScript, Go, Rust, Java, ...) get fold-by-default skeletons, declarative ones (CSS, SQL, HTML) keep their content and drop only blanks, comments and closing punctuation, and prose/config stay verbatim — where there is nothing safe to fold, the original excerpt is shown unchanged.
After a scan or search has located a node, pass focus= to read exactly
that function/class/method/heading verbatim — instead of guessing a line
range for Read/cat/sed:
scan_file(file_path="example.py", focus="DatabaseManager.query")focus: DatabaseManager.query @24-26
example.py (3-57)
- import statements @3
- DatabaseManager @8 # Manages database connections and queries.
- __init__ (self, connection_string: str) @11
- connect (self) @15 # Establish database connection.
- disconnect (self) @19 # Close database connection.
- query (self, sql: str) -> list @24 # Execute a SQL query.
24 | def query(self, sql: str) -> list:
25 | """Execute a SQL query."""
26 | return []
- UserService @29 # Handles user-related operations.
- validate_email (email: str) -> bool @48 # Validate email format.
- main () @53 # Main entry point.The rest of the file stays as a depth-1 skeleton, so the node arrives with
its parent context. Names resolve in three tiers: exact match, qualified
path (ClassA.method, works for markdown headings too), then
case-insensitive substring; an ambiguous name returns the qualified
candidate list instead of guessing. Measured on real agent episodes
(experiments/benchmark/M2C.md): equal answer quality at 75% fewer
read tokens than cat/sed line-range guessing.
Scan content without requiring a file path. Works with remote files, APIs, or in-memory content.
scan_file_content(
content="def hello(): pass\n\nclass MyClass:\n pass",
filename="example.py", # Extension determines parser
show_signatures=True,
show_decorators=True,
show_docstrings=True,
show_complexity=False,
output_format="tree"
)Shows directory tree with inline class/function names.
scan_directory(
directory="./src",
pattern="**/*", # Glob pattern
max_files=None, # File limit
respect_gitignore=True, # Honor .gitignore
exclude_patterns=None, # Additional exclusions
output_format="tree" # "tree" or "json"
)Example output:
src/ (22 files, 15 classes, 127 functions, 89 methods)
├─ languages/
│ ├─ python.py (1-329) [11.9KB, 2 hours ago] - PythonLanguage
│ ├─ typescript.py (1-505) [18.9KB, 1 day ago] - TypeScriptLanguage
│ └─ rust.py (1-481) [17.6KB, 3 days ago] - RustLanguage
├─ scanner.py (1-232) [8.8KB, 5 mins ago] - FileScanner
└─ server.py (1-735) [27.2KB, just now] - scan_file, scan_directory, ...Pattern examples:
# Specific file types
scan_directory("./src", pattern="**/*.py")
# Multiple types
scan_directory("./src", pattern="**/*.{py,ts,js}")
# Shallow scan (1 level deep)
scan_directory(".", pattern="*/*")
# Exclude directories
scan_directory(".", exclude_patterns=["tests/**", "docs/**"])# Find test functions
search_structures(
directory="./tests",
type_filter="function",
name_pattern="^test_"
)
# Find classes ending in "Manager"
search_structures(
directory="./src",
type_filter="class",
name_pattern=".*Manager$"
)
# Find functions with @staticmethod
search_structures(
directory="./src",
has_decorator="@staticmethod"
)
# Find complex functions (>100 lines)
search_structures(
directory="./src",
type_filter="function",
min_complexity=100
)Shows directory tree without files.
list_directories(
directory=".",
max_depth=3, # Maximum depth (default: 3)
respect_gitignore=True # Honor .gitignore (default: True)
)Example output:
/Users/user/project/
├─ src/
│ ├─ components/
│ ├─ services/
│ └─ utils/
├─ tests/
│ ├─ unit/
│ └─ integration/
└─ docs/The default output format IS the API: LLM agents consume scantool output
directly and uncritically, so format drift is behavior drift in the
consumer (measured in experiments/benchmark/M2B.md). Two consequences:
Defaults are the measured optimum — parameters are escape hatches.
Every default (two-tier condensation, saliency selection, skeleton
depth, compact vs verbatim per language) is backed by measurements in
experiments/condensation/, experiments/entropy_metrics/ and
experiments/benchmark/. Override them when a specific situation
demands it, not as a style preference.
The default format is frozen by golden tests (tests/test_golden.py,
snapshots in tests/golden/). A deliberate format change requires a
deliberate snapshot update (UPDATE_GOLDEN=1 uv run pytest tests/test_golden.py); an accidental change fails CI. Environment-
dependent parts (file size/mtime, git churn, delta memory) live outside
the frozen layer. Peer divergence is a pure function of the code, so it
is frozen too (tests/golden/consensus.txt, fixture in
tests/golden/consensus_fixture/).
Extension | Language | Extracted Elements |
| Python | classes, methods, functions, imports, decorators, docstrings |
| JavaScript | classes, methods, functions, imports, JSDoc comments |
| TypeScript | classes, methods, functions, imports, type annotations, JSDoc |
| Rust | structs, enums, traits, impl blocks, functions, use statements |
| Go | types, structs, interfaces, functions, methods, imports |
| C | functions, structs, enums, includes |
| C++ | classes, functions, namespaces, templates, includes |
| Java | classes, methods, interfaces, enums, annotations, imports |
| PHP | classes, methods, functions, traits, interfaces, namespaces |
| C# | classes, methods, properties, structs, enums, namespaces |
| Ruby | modules, classes, methods, singleton methods |
| Zig | functions, structs, enums, unions, tests |
| Swift | classes, structs, enums, protocols, functions, extensions |
| SQL | tables, views, functions, procedures, indexes, columns |
| HTML | document structure, elements, attributes |
| CSS | selectors, properties, media queries |
| SCSS | selectors, mixins, variables, nesting |
| Markdown | headings (h1-h6), code blocks with hierarchy |
| Plain Text | sections, paragraphs |
| Images | format, dimensions, colors, content type |
All files include metadata (size, modified date, permissions) automatically.
Structural overview of unfamiliar codebases
File organization understanding
Navigation using precise line ranges
Identify class and function boundaries for safe splitting
Find implementations of specific patterns
Locate functions above complexity thresholds
Generate structural diffs
Find functions with specific decorators
Identify test coverage gaps
Peer divergence: spot a changed function that breaks a call pattern its siblings across the repo follow (a likely regression — adjudicate by reading)
Auto-generate table of contents with line numbers
Extract API signatures
Feed structured data to analysis tools (JSON output)
Primary exploration tool (replaces ls/grep/find workflows)
Partition large files intelligently for LLM context windows
Extract code sections with exact boundaries
Search patterns across codebases
Reduce token usage: get structure first, read content only when needed
scantool/
├── server.py # FastMCP server (stdio + HTTP entry points)
├── scanner.py # Core scanning logic using tree-sitter
├── formatter.py # Tree formatting with box-drawing characters
├── code_map.py # Architecture analysis (Layer 1 + 2)
├── call_graph.py # Hot functions, centrality analysis
├── preview.py # Quick directory preview
└── languages/ # Unified language system (one file per language)
├── base.py # BaseLanguage - all languages inherit from this
├── models.py # StructureNode, CallInfo, ImportInfo, etc.
├── python.py # PythonLanguage
├── typescript.py
├── rust.py
└── ... # 20+ languagesFor environments where stdio doesn't work, or when sharing a server across multiple clients:
# Start the HTTP server
uvx --from scantool scantool-http
# Listens on port 8080 by default (set PORT env var to change)
# Connect Claude Code to it
claude mcp add --transport http scantool http://127.0.0.1:8080/mcpNote: The HTTP server must be started separately and kept running. For most users, the stdio transport (default) is simpler and recommended.
# Run all tests
uv run pytest
# Run specific tests
uv run pytest tests/languages/
uv run pytest tests/python/
uv run pytest tests/typescript/
# Run with coverage
uv run pytest --cov=src/scantool
# Run with verbose output
uv run pytest -vSee CONTRIBUTING.md for details on adding language support.
MIT License - see LICENSE file for details.
FastMCP - MCP server framework
tree-sitter - Parsing library
uv - Python package installer
Claude Desktop enforces a 25,000 token limit on MCP tool responses. Claude Code has a configurable limit (set MAX_MCP_OUTPUT_TOKENS env var to adjust).
Built-in mitigations:
scan_directory() uses compact inline format
Respects .gitignore by default (excludes node_modules, .venv, etc.)
Shows file metadata with relative timestamps
Manual controls:
Use pattern to limit scope: "**/*.py" vs "*/*" (shallow)
Use max_files to cap number of files processed
Use exclude_patterns for additional exclusions
Scan specific subdirectories instead of entire codebase
For large codebases:
# Scan specific areas
scan_directory("./src", pattern="**/*.py")
scan_directory("./tests", pattern="**/*.py")When using Claude Code, asking to "explore the codebase" may delegate to the Explore agent which doesn't have access to MCP tools. Be explicit: "use scantool to scan the codebase" to ensure the MCP tool is used directly.
Audit a directory for peer divergence - functions that break a call pattern their siblings across the codebase follow (peers calling X also call Y, this one doesn't). A REVIEW HINT to look at, not a verified bug list. Silent on a consistent codebase. Use to hunt drift, dead/missing connectivity, or misaligned implementations - cheaper and more focused than preview_directory when divergence is all you want
| Name | Required | Description | Default |
|---|---|---|---|
| directory | Yes | ||
| max_findings | No | ||
| respect_gitignore | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, but description discloses it's a 'REVIEW HINT' not a verified bug list, and 'silent on a consistent codebase'. This gives realistic expectations. However, lacks detail on side effects or read-only nature.
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 a single paragraph, somewhat long but not excessive. Front-loads purpose but includes explanatory phrases that could be streamlined.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an audit tool with no output schema and low parameter coverage, description covers purpose and use cases but misses parameter details and return format, leaving gaps for 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 description coverage is 0%, and description does not explain parameters like max_findings or respect_gitignore. Only directory is implied. Agent cannot infer parameter meaning from description.
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 audits a directory for peer divergence, identifying functions that break call patterns. It distinguishes from sibling 'preview_directory' by emphasizing focus and efficiency.
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 describes when to use (hunt drift, dead connectivity) and contrasts with preview_directory. Does not explicitly state when not to use, but context implies alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List directory tree structure (folders only, no files) - USE THIS to see folder hierarchy
| Name | Required | Description | Default |
|---|---|---|---|
| directory | Yes | ||
| max_depth | No | ||
| respect_gitignore | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the basic operation but omits behavioral details such as whether hidden folders are included, symlink handling, performance implications, or how respect_gitignore affects output.
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 extremely concise, using a single sentence plus an emphatic instruction. Every word serves a purpose, and the key distinction (folders only) is front-loaded.
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 complexity of three parameters, no output schema, and no annotations, the description is insufficient. It does not explain the output format (e.g., tree structure as text or object), depth behavior, or gitignore functionality, leaving significant gaps for correct tool 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 description coverage is 0%, meaning no parameter descriptions. The tool description adds no information about the three parameters (directory, max_depth, respect_gitignore), leaving the agent to infer meaning solely from names and types.
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 states 'List directory tree structure (folders only, no files)' with a specific verb and resource, clearly distinguishing from sibling tools like scan_directory which likely include files. The instruction 'USE THIS to see folder hierarchy' reinforces its unique purpose.
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 a clear context ('USE THIS to see folder hierarchy') but lacks explicit guidance on when not to use it or alternatives among the eight sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deep architecture analysis - entry points, hot functions, call graph, git activity (RICH output ~3-5k tokens; for first-time orientation of an unknown codebase. For targeted questions, search_structures or scan_directory are cheaper first calls)
| Name | Required | Description | Default |
|---|---|---|---|
| depth | No | deep | |
| directory | Yes | ||
| max_files | No | ||
| max_entries | No | ||
| respect_gitignore | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It mentions the output is 'RICH output ~3-5k tokens', indicating potential heaviness, but does not explicitly state that the tool is read-only and non-destructive. This is a minor gap as it is a preview tool, but more clarity on side effects would improve transparency.
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 a single sentence that efficiently conveys purpose and usage guidance without fluff. However, it could be slightly more structured with clear sections for parameters or usage notes.
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 has 5 parameters, no schema descriptions, no output schema, and no annotations, the description is too sparse. It adequately covers purpose and usage but fails to address parameter details and return values, leaving the agent underinformed.
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 description coverage is 0%, and the description does not explain any of the 5 parameters (depth, directory, max_files, max_entries, respect_gitignore). The agent has no guidance on how to use these parameters, which is a critical omission.
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 specifies the tool's purpose: deep architecture analysis including entry points, hot functions, call graph, and git activity. It explicitly states it is for first-time orientation of an unknown codebase, distinguishing it from sibling tools like search_structures and scan_directory.
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 guidance: for first-time orientation of an unknown codebase. It also tells when not to use (for targeted questions) and suggests cheaper alternatives (search_structures, scan_directory).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Structural diff against a git ref - which functions are new/changed/removed since HEAD/main/a release, with condensed skeletons. USE THIS INSTEAD of git diff for review and 'what changed' questions
| Name | Required | Description | Default |
|---|---|---|---|
| ref | No | HEAD | |
| budget | No | ||
| directory | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It states the tool produces a structural diff of functions, but lacks details on output format, requirements (e.g., git repository), side effects, or limitations. It is vague about what 'condensed skeletons' entails.
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: two sentences, front-loading the purpose and adding a direct usage guideline. Every sentence serves a clear role with 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?
Given no output schema, no annotations, and 3 parameters (one required, two with defaults), the description is incomplete. It does not explain what 'condensed skeletons' means, how to interpret results, or prerequisites like needing a git repository. The 'budget' parameter is mysterious.
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 0% parameter descriptions, and the description adds no meaning to the three parameters (directory, ref, budget). It does not explain their roles or defaults, leaving the agent to guess or rely on defaults without context.
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 performs a structural diff against a git ref, identifying new/changed/removed functions with condensed skeletons. It explicitly distinguishes itself from git diff, making its purpose specific and 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?
The description includes an explicit directive to use this tool instead of git diff for review and 'what changed' questions, providing clear context. However, it does not compare with sibling tools like find_divergence, which could be a close alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan directory - file tree with one-line gists per file, code health and churn labels (cheap overview, good first call). Replaces Glob/ls for ALL file types
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | balanced | |
| delta | No | ||
| depth | No | ||
| pattern | No | **/* | |
| directory | Yes | ||
| max_files | No | ||
| output_format | No | tree | |
| exclude_patterns | No | ||
| respect_gitignore | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is moderately transparent, indicating it's a 'cheap overview' implying lightweight execution, and that it provides one-line gists and labels. However, with no annotations, it fails to disclose important behavioral traits such as read-only nature, permission requirements, limits on large directories, or the exact meaning of 'code health and churn'.
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 two sentences, with no extraneous content. However, it is front-loaded but sacrifices clarity on parameters and output. It is not as structured as it could be, failing to separate purpose from details.
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 no parameter descriptions in the schema, the description is grossly incomplete. It does not explain return value structure (e.g., format of tree, gists, labels) or how parameters affect behavior. The tool is non-trivial, lacking essential context for proper 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?
The input schema has 9 parameters with zero descriptions (0% coverage), and the description does not explain any parameter beyond vague references to directory scanning. An agent cannot infer the meaning or usage of parameters like mode, delta, depth, pattern, max_files, output_format, exclude_patterns, or respect_gitignore from the description 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 scans directories producing a file tree with one-line gists and code health/churn labels, and distinguishes itself as a replacement for Glob/ls across all file types. However, it does not explicitly distinguish from siblings like list_directories or scan_file, lacking specificity on output format.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage as a 'good first call' and 'replaces Glob/ls', suggesting it's a starting point for directory overviews. However, it does not provide explicit when-to-use or when-not-to-use guidance compared to sibling tools such as scan_file or scan_diff.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan ANY file (code, markdown, text, HTML, config) - structure with condensed code skeletons. USE BEFORE Read. For exploration, pass budget=1500 (or 300 for a quick look) - full depth is rarely needed on the first pass. To READ one function/class/section verbatim afterwards, pass focus='name' (or 'Class.method') instead of guessing line ranges. May append a self-levelling CONNECTIVITY note - candidate dead/orphan/drift across the whole corpus, silent when clean; candidates to look at, not verdicts
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | balanced | |
| delta | No | ||
| depth | No | ||
| focus | No | ||
| budget | No | ||
| condense | No | ||
| file_path | Yes | ||
| output_format | No | tree | |
| show_complexity | No | ||
| show_decorators | No | ||
| show_docstrings | No | ||
| show_signatures | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses that the tool may append a self-levelling CONNECTIVITY note about dead/orphan/drift code, and that budget controls depth. It does not mention error handling or resource usage, but for a scan tool, these are 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?
The description is a single dense paragraph with multiple instructions. While front-loaded with purpose, it could be more structured with bullet points or clearer separation of usage vs. behavior. Every sentence adds value, but the delivery is somewhat cramped.
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 12 parameters, no output schema, and no annotations, the description covers core behavior and key parameters but leaves many details unexplained. It is adequate for a tool meant to be used in a sequence, but not fully 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 0%, so the description must compensate. It adds meaning to budget and focus (e.g., 'budget=1500' and 'focus=name'), but does not explain other parameters like mode, delta, condense, output_format, or show_* flags. This leaves many parameters ambiguous.
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 what the tool does: scan any file type and produce structured output with condensed code skeletons. It distinguishes itself from 'Read' by being for exploration first, and mentions a special connectivity note feature. The purpose is specific and well-articulated.
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 guidance: use before reading, budget recommendations (1500 vs 300), and how to use the focus parameter for targeted reading. However, it does not explicitly compare with all sibling tools like scan_diff or scan_directory, missing some differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan file content directly - USE THIS for remote files, GitHub, APIs instead of saving to disk first
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | ||
| filename | Yes | ||
| output_format | No | tree | |
| show_complexity | No | ||
| show_decorators | No | ||
| show_docstrings | No | ||
| show_signatures | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only mentions scanning directly without disclosing behavioral details like read-only nature, network requirements, or output format. Missing essential 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?
Single sentence that front-loads the action and immediately adds usage guidance. No superfluous text; every word earns its place.
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, no output schema, and no annotations, the description is incomplete. It omits return values, behavior, and parameter details, leaving the agent underinformed for invoking the tool correctly.
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 0%, and the description does not explain any of the 7 parameters (content, filename, output_format, etc.). The agent has no guidance on parameter meaning or usage beyond the schema's structural fields.
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 scans file content directly and specifies use cases (remote files, GitHub, APIs). It differentiates from saving to disk first, but doesn't explicitly contrast with siblings like scan_file or scan_directory.
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 guidance to use this tool for remote files, GitHub, APIs instead of saving to disk first, implying an alternative workflow. Lacks explicit when-not-to-use conditions but effectively communicates primary context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search across all file types - BEST FIRST CALL for targeted questions, USE INSTEAD of Grep: content_pattern finds text WITH structural context (enclosing function/class/section) plus leads to definitions; name/type/decorator find structures
| Name | Required | Description | Default |
|---|---|---|---|
| directory | Yes | ||
| type_filter | No | ||
| name_pattern | No | ||
| has_decorator | No | ||
| output_format | No | tree | |
| min_complexity | No | ||
| content_pattern | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility. It explains that content_pattern provides structural context and leads to definitions, and that name/type/decorator find structures. This discloses key behavioral traits, though it omits details like recursion depth or authentication needs. Still, it gives sufficient insight for a search tool.
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 a single, well-structured sentence that front-loads the core purpose and packs usage guidance, parameter hints, and behavioral notes without redundancy. Every word 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 seven parameters and no annotations or output schema, the description covers the critical aspects—purpose, usage, and main parameters—but lacks explanation for min_complexity and output_format. It is nearly complete but not exhaustive, which is suitable for an 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 description coverage is 0%, so the description must compensate. It explains content_pattern, name_pattern, type_filter, and has_decorator, adding meaning beyond the empty schema. However, it does not cover directory, output_format, or min_complexity, leaving gaps. This partial coverage earns a mid-range score.
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 searches across all file types with structural context, distinguishing itself from Grep. It specifies the verb 'search' and resource 'structures' with concrete details about what it finds (enclosing functions, classes, etc.), 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 explicitly recommends it as the 'BEST FIRST CALL for targeted questions' and advises to 'USE INSTEAD of Grep,' providing clear context on when to use the tool versus an alternative. This helps an agent decide when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose: find_divergence for peer drift, list_directories for folder structure, preview_directory for deep analysis, scan_diff for git diffs, scan_directory for overview, scan_file for file skeletons, scan_file_content for remote files, and search_structures for structural search. No overlap in functionality.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., list_directories, scan_file, search_structures). While verbs vary (find, list, preview, scan, search), each verb clearly indicates the operation type, making the pattern predictable and intuitive.
With 8 tools, the set covers a comprehensive range of file scanning and codebase analysis operations—listing, scanning, searching, diffing, and deep analysis—without being bloated. Each tool serves a necessary role in the workflow.
The tool set covers the full lifecycle of codebase exploration: directory overview, file content scanning, structural search, git diff, divergence detection, and deep architecture analysis. No obvious gaps; all typical tasks are addressed.
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.
AI-powered codebase analysis — call graphs, security, dead code, complexity. 150+ tools.
Ground-truth code graph for your codebase: exact callers, callees, symbols & dependencies.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/mariusei/file-scanner-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
