This MCP server provides AST-aware, token-efficient code reading, writing, and analysis across TypeScript, JavaScript, Python, PHP, Dart, and Ruby β with zero native dependencies (Tree-sitter WASM) and production-ready reliability.
π Read & Understand
get_semantic_repo_map β Compressed architectural repo overview (75β87% token reduction)
read_file_surgical β Extract a specific function, class, or method by name
read_file_lines β Read specific line ranges or lines around a pattern
parse_file β List all symbols with line numbers
batch_read β Read multiple symbols from multiple files in one round-trip
explain_symbol β Get a symbol's signature, location, and all callers
π Search & Analyze
search_code_pattern β Regex search with fuzzy matching and pagination
search_symbols β AST-based symbol search by name with type filtering
analyze_impact β Find all files that depend on a given file before refactoring
βοΈ Write & Refactor (all two-phase: preview diff β confirm)
write_file_surgical β Replace a symbol's body without touching the rest of the file
insert_symbol β Insert code before, after, or inside a symbol
remove_symbol β Delete a symbol with automatic dependency checking
rename_symbol β Rename a symbol across the entire repo (AST in definition + regex in dependents)
ast_transform β Declarative transformations: wrap_with_try_catch, add_parameter, add_decorator, change_return_type, extract_variable
π Ruby Intelligence
get_gemfile_context, find_metaprogramming, get_rails_routes
π§ Admin & Recovery
rollback_file β Revert to any of the last 5 auto-saved backups
get_server_stats / get_cache_stats / clear_cache β Health and cache management
configure_file_watcher β Auto-invalidate cache on file changes
get_session_stats / clear_session_cache / list_pending_operations β Per-session state and crash recovery
get_rate_limit_status β Check token budget before expensive operations
Key highlights: two-phase confirmation for all writes, session-isolated state (no leakage between agents), SQLite-persisted crash recovery, multi-process safe filesystem locking, and persistent parse cache with <100ms hits.
Provides code context and surgical editing tools for AI agents within Amazon Q.
Provides code context and surgical editing tools for AI agents within GitHub Copilot.
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., "@mcp-code-context extract the function 'login' from user.js"
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 with Tree-sitter WASM parsers for 100% AST accuracy. Zero native dependencies. Production-ready with persistent caching, structured logging, fuzzy search, multi-process safety, and session-scoped state.
Install: npm install -g mcp-code-context
Configure: Add to claude_desktop_config.json:
{
"mcpServers": {
"code-context": {
"command": "npx",
"args": ["-y", "mcp-code-context"]
}
}
}Enjoy: Use symbols like @code-context to map repos or edit code surgically.
No build tools required - Works on Windows/Mac/Linux without Visual Studio, Python, or node-gyp.
Works with Claude Desktop, Cursor, Windsurf, GitHub Copilot, Amazon Q, and any Model Context Protocol compatible client.
π For AI Agents: See INSTRUCTIONS.md for essential usage patterns and best practices.
Related MCP server: Semantic Cache MCP
This tool was born out of necessity in Caracas, Venezuela π»πͺ, where economic limitations made every API token count. When you're choosing between groceries and Claude API credits, you learn to optimize fast.
What started as a personal script to compress context windows became a full MCP server when I realized others faced the same problem: LLM APIs are expensive, and most tools waste tokens on boilerplate.
If this tool saves you money or time, consider supporting its development. Every contribution helps keep this project maintained and free for everyone.
LLMs working with code face two bottlenecks:
Reading: Sending raw source files wastes the context window on function bodies and boilerplate. A 500-line file might contain only 30 lines of structural information the LLM needs.
Writing: Rewriting entire files to change one function is error-prone, token-expensive, and risks corrupting unrelated code.
mcp-code-context provides 25 tools β covering reading, writing, AST transformation, search, and session management β all operating at the symbol level (functions, classes, methods). Tools support a className scope to correctly isolate identical symbol names in the same file (e.g. Flutter build() methods). Read tools extract structural skeletons. Write tools splice changes into the exact AST location.
File | Original | Compressed | Reduction |
PHP class (426 lines) | 426 | 60 | 85.9% |
Dart repository (230 lines) | 230 | 30 | 87.0% |
PHP config (68 lines) | 68 | 15 | 77.9% |
Real-world results:
TypeScript project: 73% reduction in tokens sent to LLM
PHP application: 82% reduction
Dart codebase: 79% reduction
Built to be robust and precise. Both read and write engines are tested against real-world, complex codebases (including nested generic types in Dart, complex interfaces in PHP, and multi-file rename operations) with a 100% test pass rate across all languages and operations.
Feature | v3.6.x | v3.9.1 | Benefit |
Multi-process safety | β | β | No file corruption |
Persistent cache | β | β | <100ms cache hits |
Session-scoped state | β | β | No state leakage between clients |
Crash recovery | β | β | Pending operations survive restart |
Expanded ReDoS protection | 6 patterns | 15+ patterns | Better security |
Auto-persist before eviction | β | β | Cache data preserved |
Feature | Description |
π | Routes inside |
πΊοΈ Repo map: Gems + Concerns |
|
π§ | Supports |
Feature | Description |
π | Parses Gemfile and returns implicit gem behaviors (devise adds |
π | Scans Ruby files for |
πΊοΈ | Parses |
π Concern resolution in |
|
Feature | Description |
π Session-scoped state | Each MCP client gets isolated locks, confirmation store, rate limiter (no state leakage) |
πΎ Crash recovery | SQLite-backed pending operations store - survive restarts |
π Expanded ReDoS protection | 15+ patterns (was 6) - better protection against regex DoS |
β‘ Auto-persist before eviction | CacheManager now persists before LRU eviction |
π Higher file limits | MAX_FILES_REPO_MAP = 2000 (was 500) |
π§ͺ Multi-client tests | New integration tests for concurrent MCP clients |
π New tools: | Session-aware operations |
π Ruby full support | Complete |
ποΈ ActiveRecord Virtual Schema | Parses |
Feature | Description |
β‘ Persistent Cache | WASM SQLite cache β <100ms hits, 10Γ faster on repeated reads |
π Structured Logging | pino JSON logging to stderr (MCP-safe, never pollutes stdio) |
ποΈ File Watcher | chokidar auto-invalidates cache on file changes |
π Fuzzy Search | fuse.js finds |
π Pagination | Search defaults to 10 results with |
π Multi-process Safe | Filesystem locks via |
πΎ OS Temp Backups | Backups in |
π§ͺ 74 Tests | Unit + integration + performance + stress tests |
π― Token Savings | 50-80% reduction: compact diffs, no Phase 2 repeat, auto-optimize output |
π³ AST-based compression β Real Tree-sitter WASM parsers for TypeScript/JavaScript/Python/PHP/Dart. Zero regex-based parsing.
π¬ Surgical symbol extraction β Extract a single function, class, or method from a file by name. Use className to scope disambiguation (e.g., getting multiple build() methods in Dart).
π₯ Impact analysis β Discover all files that depend on a given file before refactoring. Supports ES imports, CommonJS require(), Python imports, PHP use/require_once/include, and Dart imports.
π Smart file walking β Respects .gitignore and .repomixignore rules. Automatically excludes node_modules, dist, vendor, .git, etc.
π Multi-format output β XML (optimized for LLM consumption) or Markdown (human-readable).
βοΈ Surgical symbol replacement β Replace a function, method, or class body without touching the rest of the file. Narrow down the target using the className parameter.
β Precise code insertion β Insert new code before/after a symbol, or inside a class at the start/end.
π Repository-wide rename β Rename a symbol in its definition AND all files that import it, atomically.
ποΈ Safe symbol removal β Delete code with automatic dependency checking to prevent breakage.
π Mandatory dry-run flow β Write tools return a preview diff and a confirmationToken by default. Changes are only applied after explicit confirmation.
πΎ Robust rolling backups β Automatically keeps the last 5 versions of modified files in the OS temp directory.
βͺ Surgical rollback β Revert files to any of the 5 previous states using the rollback_file tool.
οΏ½οΏ½οΏ½οΏ½ Fuzzy symbol matching β When a symbol is not found, the server provides structured suggestions based on Levenshtein distance.
π Private symbol support β Full support for _ and __ prefixed symbols in Dart and Python.
Language | Read (Compress + Extract) | Write (Replace + Insert + Rename + Remove) | Import Analysis |
TypeScript / JavaScript | β AST (Tree-sitter WASM) | β AST (Tree-sitter WASM) | β |
PHP | β AST (Tree-sitter WASM) | β AST + line-splice | β |
Dart | β AST (Tree-sitter WASM) | β AST + line-splice | β |
Python | β AST (Tree-sitter WASM) | β Indentation-aware | β |
Ruby | β AST (Tree-sitter WASM) + ActiveRecord Virtual Schema | β AST byte-offset splice | β |
Others (JSON, YAML, CSS, etc.) | Passthrough / truncation | β | β |
rename_symbol ToolAll languages: The definition file is renamed using AST (Tree-sitter) β safe and precise. β
Cross-file rename (dependent files): Updated using regex word-boundaries for all languages, including TypeScript, JavaScript, and PHP.
Risk: Regex may match strings, comments, or unrelated identifiers sharing the same name
Dart and Python: Higher risk β import syntax (import 'package:...', from module import name) is less reliably matched by the current regex patterns
Recommendation: Always review the generated diff carefully before confirming
Alternative: Use write_file_surgical to rename within a single file safely
get_semantic_repo_map ToolMax files: Limited to 2000 files to prevent timeouts (increased from 500 in v3.9.1)
Performance: Synchronous I/O may take 10-30 seconds on large repositories
Recommendation: Use @folder syntax to target specific directories
Validation: No automatic syntax checking after edits. Always review diffs carefully before confirming.
Backups: 5-version rolling backup system. Use rollback_file if something goes wrong.
Large files: Files >10MB are skipped for safety.
Phase 2 tokens: Confirmation tokens expire after 5 minutes.
# Global installation (recommended)
npm install -g mcp-code-context
# Or use directly with npx (no installation)
npx -y mcp-code-contextNote: Unlike v2.x, this version uses web-tree-sitter (WASM) instead of native bindings. No Visual Studio, Python, or node-gyp required!
Important: v3.9.1 introduces session-scoped state for each MCP client connection. This prevents state leakage when multiple agents (Amazon Q, Kiro, Cursor, etc.) use the same server instance.
Before (v3.6.x) | After (v3.9.1) |
Global | Session-scoped |
Global | Session-scoped confirmation store + SQLite persistence |
Global | Per-session token bucket |
No crash recovery | SQLite-backed pending operations store |
β No state leakage: Each agent gets isolated locks, confirmation store, and rate limiter
β Crash recovery: Pending operations survive server restarts
β Multi-agent safe: Amazon Q and Kiro can run simultaneously without conflicts
No additional configuration needed. Session isolation is automatic. Just configure your MCP server normally:
{
"mcpServers": {
"mcp-code-context": {
"command": "npx",
"args": ["-y", "mcp-code-context"]
}
}
}get_gemfile_context β Parse Gemfile, get implicit gem behaviors (devise, sidekiq, pundit, etc.)
find_metaprogramming β Scan for define_method, method_missing, class_eval, concerns, has_many :through
get_rails_routes β Parse config/routes.rb into structured route map with namespace support
get_session_stats β Get stats for current session only
clear_session_cache β Clear cache for current session only
list_pending_operations β List pending operations for recovery
Add to your claude_desktop_config.json:
{
"mcpServers": {
"mcp-code-context": {
"command": "npx",
"args": ["-y", "mcp-code-context"]
}
}
}Add to your Cursor MCP settings (.cursor/mcp.json):
{
"mcpServers": {
"mcp-code-context": {
"command": "npx",
"args": ["-y", "mcp-code-context"]
}
}
}Add to your Windsurf MCP config:
{
"mcpServers": {
"mcp-code-context": {
"command": "npx",
"args": ["-y", "mcp-code-context"]
}
}
}Add to your Amazon Q MCP config:
{
"mcpServers": {
"mcp-code-context": {
"command": "npx",
"args": ["-y", "mcp-code-context"]
}
}
}Add to your Kiro MCP config (.kiro/settings/mcp.json):
{
"mcpServers": {
"mcp-code-context": {
"command": "npx",
"args": ["-y", "mcp-code-context"]
}
}
}Add to your Antigravity MCP config (.antigravity/mcp.json):
{
"mcpServers": {
"mcp-code-context": {
"command": "npx",
"args": ["-y", "mcp-code-context"]
}
}
}Any MCP-compatible client can use this server. The transport is stdio (JSON-RPC over stdin/stdout). Point your client to npx -y mcp-code-context.
Tool | Key Params | Description |
|
| Compressed XML/Markdown repo overview with AST symbols |
|
| Extract one symbol or full file |
|
| All files that depend on this file |
|
| Read a line range or pattern context |
|
| Regex search across files (ripgrep-fast) |
|
| All symbols with line numbers (cheap index) |
|
| AST symbol search by name, not text |
|
| Signature + location + callers in one call |
|
| N symbols from N files in 1 round-trip |
| β | Token balance + |
All write tools require two calls:
Phase 1 β Call normally β returns diff + confirmationToken
Phase 2 β Call again with confirm: true + confirmationToken β applies changes
newContent/code are not required in Phase 2 β the server stores them from Phase 1.
Tool | Key Params | Description |
|
| Replace a symbol with new code |
|
| Insert code before/after/inside a symbol |
|
| Remove a symbol (with dependency check) |
|
| Rename across entire repo (AST + regex) |
|
| Declarative transforms: |
Tool | Key Params | Description |
|
| Restore file from rolling backup (up to 5 versions) |
|
| Delete all backups for this project |
| β | Telemetry, audit stats, rate limiter state |
|
| Cache entries, size, hit rate |
|
| Invalidate cache for this project |
|
| Auto-invalidate cache on file changes |
|
| Watcher state + watched paths |
| β | Per-session: pending ops, locks, tokens |
|
| Clear cache for current session only |
| β | List pending Phase 1 tokens (crash recovery) |
Understand β get_semantic_repo_map to see the architecture
Read β read_file_surgical with symbol name for specific implementations
Assess β analyze_impact before modifying shared files
Edit (Preview) β Call write tools to generate a diff and confirmationToken
Confirm β Call the same write tool with the token and confirm: true to apply
Recovery β Use rollback_file if something goes wrong after confirmation
This tool was born in Caracas, Venezuela π»πͺ, where economic limitations mean every API token counts. What started as a personal script to save money on Claude API became a full MCP server when I realized others faced the same problem.
Current Reality:
β° ~10 hours/week of maintenance
π΅ ~$20/month in costs (npm, testing, domain)
π 100% free and open source (always will be)
If this tool saves you time or money, consider supporting its development.
Ko-fi (PayPal + Cards, 0% fees)
ko-fi.com/achatainga
PayPal (Direct)
paypal.me/achatainga
Binance (USDT) (Crypto, lowest fees)
TRC20/ERC20: 0xa68d53f7853ce0175eb96aaad4a30c068ca96444
Binance Pay ID: 367669339
Recommended: TRC20 for lower gas fees
β $5 - A coffee (1 hour of development)
π $25 - A pizza (testing a new language)
π $100 - Rocket fuel (major feature development)
Ko-fi Membership
ko-fi.com/achatainga/tiers
Monthly tiers:
$5/month - Supporter (name in SPONSORS.md)
$25/month - Contributor (priority support, early access)
$100/month - Sponsor (feature requests, 1-on-1 consultation)
Need custom MCP tools or AI integrations?
πΌ Available for: Freelance contracts
π Location: Caracas, Venezuela (Remote)
π» Skills: TypeScript, Node.js, MCP, AI/LLM integrations
π΅ Rate: $50-75/hour
π§ Contact: a.chataing.a@gmail.com
π Details: HIRE_ME.md
I believe in radical transparency:
Current Status:
π° Donations received: $0
πΈ Expenses: $20/month (npm, testing)
β° Time invested: ~10 hours/week
π¦ Downloads: 10,000+/month
(Updated monthly)
Thank you to these amazing supporters:
(No sponsors yet - be the first!)
See full list: SPONSORS.md
Can't donate? No problem! You can still help:
β Star the repo on GitHub
π Report bugs or suggest features
π Improve documentation
π£οΈ Share with others who might benefit
π¬ Join discussions and help other users
Every contribution matters, financial or not.
# Build
npm run build
# Run tests
npm test
# Development (build + start)
npm run devTransport: stdio (JSON-RPC over stdin/stdout)
Runtime: Node.js >= 18
Protocol: Model Context Protocol
AST Engines: web-tree-sitter@0.25.1 (WASM) for TypeScript/JS/Python/PHP/Dart
Language Grammars: tree-sitter-wasms@0.1.13 (ABI v15)
Cache: sql.js@1.14.1 (WASM SQLite, zero native deps)
Logging: pino@10.3.1 (JSON to stderr, MCP-safe)
File Watcher: chokidar@5.0.0 (auto cache invalidation)
Fuzzy Search: fuse.js@7.3.0 (typo-tolerant matching)
File Locking: proper-lockfile@4.1.2 (multi-process safe, OS temp)
Diff: diff-match-patch@1.0.5 (Myers algorithm, O(n+dΒ²))
Ignore Engine: ignore npm package (full .gitignore spec support)
Safety Features: Mandatory two-phase confirmation, rolling 5-version backups, fuzzy matching, dependency checking, surgical restoration, ReDoS protection via worker_threads, session-scoped state.
Portability: 100% WASM - no native dependencies, works on all platforms
Tests: 83 passing (unit + integration + performance + stress)
Component | Change | Benefit |
State management | Session-scoped instead of global | No state leakage between clients |
Pending operations | SQLite-backed | Survive server restarts |
ReDoS patterns | 6 β 15+ | Better security |
Cache eviction | Auto-persist before close | Cache data preserved |
File limits | MAX_FILES = 2000 (was 500) | Better support for large projects |
Tests | Added multi-client concurrency tests | Production readiness verified |
See CONTRIBUTING.md for guidelines.
See SECURITY.md for security policies and reporting vulnerabilities.
See TROUBLESHOOTING.md for common issues and solutions.
Because MCP uses stdout for protocol communication, all logs are safely routed to stderr. You can view them in your client's log files:
Claude Desktop (macOS): ~/Library/Logs/Claude/mcp-server-mcp-code-context.log
Claude Desktop (Windows): %APPDATA%\Claude\logs\mcp-server-mcp-code-context.log
Cursor: Output panel β Select mcp-code-context from the dropdown
Amazon Q: Check stderr output in the MCP server configuration
Kiro: Check logs in the MCP server view
Antigravity: Check logs in the MCP server view
Environment Variables (optional):
{
"mcpServers": {
"mcp-code-context": {
"command": "npx",
"args": ["-y", "mcp-code-context"],
"env": {
"NODE_ENV": "development",
"LOG_LEVEL": "debug"
}
}
}
}Supported LOG_LEVEL values: fatal, error, warn, info, debug, trace (default: info).
See CHANGELOG.md for version history.
Built with β€οΈ from Caracas, Venezuela π»πͺ
Find all files that depend on a given file
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Absolute path to file | |
| projectRoot | Yes | Project root for security boundary | |
| rootDir | No | Repository root (optional, defaults to projectRoot) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility but only states the high-level function. It omits details like whether the tool performs recursive analysis, is read-only, or has performance implications.
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 at one sentence, but it sacrifices necessary detail. It is not verbose, but it is under-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?
There is no output schema, and the description fails to explain what the return value is. The tool's scope (e.g., whether it handles all dependency types) is vague.
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 100%, so the baseline is 3. The description does not add new meaning beyond what the schema already provides for filePath, projectRoot, and rootDir.
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 ('find all files that depend on a given file'), but it does not differentiate from sibling tools like search_code_pattern or search_symbols.
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?
No guidance is provided on when to use this tool versus alternatives like search_code_pattern or list_pending_operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply a declarative AST transformation to a symbol. Supports: add_parameter, wrap_with_try_catch, add_decorator, change_return_type, extract_variable. Uses two-phase write (Phase 1: preview diff, Phase 2: confirm with token).
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Absolute path to file | |
| projectRoot | Yes | Project root (REQUIRED) | |
| symbolName | Yes | Target symbol to transform | |
| className | No | Class name (optional, for scoping) | |
| transform | Yes | Transform specification | |
| confirm | No | Set true to apply a pending operation (Phase 2) | |
| confirmationToken | No | Token from Phase 1 dry-run (Phase 2 only) | |
| diffFormat | No | Diff verbosity (default: unified) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It discloses the two-phase write behavior and the need for a confirmation token, which is important for a mutation tool. However, it does not mention permissions, potential side effects, or reversibility.
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 (two sentences) with no extraneous information. The first sentence states purpose and capabilities, the second explains the two-phase process.
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?
The description explains the key two-phase process and lists supported transforms, which covers the essential behavioral aspects. However, it does not describe the output or return value (e.g., diff content, token structure), and no output schema exists.
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 100%, so the baseline is 3. The description adds the list of supported transform kinds and the two-phase workflow, but does not add new semantic detail beyond what the schema provides for individual parameters.
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 applies a declarative AST transformation to a symbol and lists specific supported transform kinds. It distinguishes itself from sibling tools like rename_symbol or remove_symbol by focusing on AST-level transformations.
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 mentions the two-phase write pattern (Phase 1 preview, Phase 2 confirm), providing clear guidance on how to use the tool. However, it does not explicitly state when not to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read multiple symbols from multiple files in one call. Reduces N round-trips to 1.
| Name | Required | Description | Default |
|---|---|---|---|
| reads | Yes | List of symbols to read | |
| projectRoot | Yes | Project root for security boundary |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden. It implies read-only but omits details on error handling, batch size limits, or behavior when some symbols fail.
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 two sentences, zero waste, front-loaded with purpose and benefit.
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?
No output schema, and description does not specify return format or error handling. For a batch tool, this is a gap, but the basic purpose is clear.
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 good inline descriptions. The tool description adds no additional meaning beyond the schema, so 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 the verb 'read', the resource 'multiple symbols from multiple files', and the benefit of reducing round-trips. It effectively distinguishes from sibling tools that likely perform single reads.
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 use for batch reads but lacks explicit when-to-use, when-not-to-use, or alternative tools. Context is clear, but no guidance on exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove all backup files for a project
| Name | Required | Description | Default |
|---|---|---|---|
| projectRoot | Yes | Project root directory |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose behavioral traits such as irreversibility, safety, or side effects of deleting backup files. The agent is left uninformed about risks.
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 with no redundancy. However, it could be slightly more precise without adding significant length.
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 deletion tool, the description omits crucial context like irreversibility, scope of deletion, or impact on the project. The minimal description is insufficient for safe 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?
The schema covers 100% of parameters with a description for 'projectRoot'. The tool's description adds no additional meaning beyond what the schema provides, meeting the baseline.
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 uses a specific verb ('Remove') and resource ('backup files') to clearly state the tool's action. It distinguishes itself from sibling tools by focusing on backup files, which is not covered by other removal tools.
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?
No guidance on when to use this tool versus alternatives, no prerequisites or conditions mentioned. The description lacks explicit context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Clear all cached parse results for a project
| Name | Required | Description | Default |
|---|---|---|---|
| projectRoot | Yes | Project root directory |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description shoulders the burden of behavioral disclosure. It states the tool clears cached data, but does not mention if the operation is reversible, how it affects concurrent operations, or any side effects like performance impact. A clear destructive operation should at least note irreversibility.
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 with no redundant information. It is appropriately sized and front-loaded with the core purpose.
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 parameter, no output schema), the description is moderately complete. It identifies the action and resource but lacks context about consequences, failure modes, or best practices, which would be helpful for an agent to invoke 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?
The input schema provides a full description of the single required parameter (projectRoot). The description adds no additional meaning beyond what is already in the schema, so it meets the baseline for high schema coverage.
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 action (clear) and the resource (cached parse results) with a specific scope (for a project). It distinguishes from sibling tools like clear_session_cache and get_cache_stats by mentioning 'all cached parse results' and 'for a project'.
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?
No guidelines are provided about when to use this tool versus alternatives such as clear_session_cache or other cache management tools. The description does not include any prerequisites, caveats, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Clear cache for current session only
| Name | Required | Description | Default |
|---|---|---|---|
| projectRoot | No | Optional project root |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description only states the basic operation. It does not disclose side effects, permissions, or whether the cache clearing is destructive, but for a simple cache operation, this is adequate.
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, clear sentence with no wasted words. It is front-loaded and directly conveys the tool's purpose.
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) and the context from sibling tools, the description adequately covers the core functionality for an AI agent, though it could mention when to prefer this over similar tools.
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 does not explain the single parameter 'projectRoot'; the schema already provides the description 'Optional project root', so the description adds no extra 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 clearly states the action ('Clear') and the specific resource ('cache for current session only'), distinguishing it from the sibling 'clear_cache' which likely targets global or all-session cache.
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 for session-specific cache clearing, but does not explicitly state when not to use it or mention alternatives like 'clear_cache' or 'clean_backups'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start/stop file watcher for auto-cache invalidation
| Name | Required | Description | Default |
|---|---|---|---|
| projectRoot | Yes | Project root directory | |
| action | Yes | Action to perform | |
| debounceMs | No | Debounce delay in ms (default: 500) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. While it states 'start/stop', it does not disclose side effects like state changes, whether the watcher is persistent, or any prerequisites.
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 concise sentence that front-loads the action and purpose, leaving 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?
With 3 parameters and no output schema, the description is minimal. It explains the action but lacks details on return value or what happens after start/stop. Adequate but not 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 descriptions for all parameters. The description adds no extra meaning beyond the schema, so 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 the action ('start/stop'), the resource ('file watcher'), and the purpose ('auto-cache invalidation'). It distinguishes from siblings like 'get_file_watcher_status' and 'clear_cache'.
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?
No explicit guidance on when to use this tool versus alternatives such as 'get_file_watcher_status' for checking status or 'clear_cache' for manual invalidation. Usage is implied but not clarified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get signature, location, and callers of a symbol in one call. More efficient than read_file_surgical + analyze_impact separately.
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Absolute path to file | |
| projectRoot | Yes | Project root (REQUIRED) | |
| symbolName | Yes | Symbol to explain | |
| className | No | Class name (optional, for scoping) | |
| rootDir | No | Root dir for caller search (optional, defaults to projectRoot) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, description should disclose behavioral traits. It states it gets data but does not mention side effects, permissions, or rate limits. It implies a read operation but lacks explicit safety guarantees.
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 efficiently conveys purpose and efficiency advantage. 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?
Tool has 5 parameters and returns multiple pieces of info. Description explains what it returns but lacks details on return format. For a combined operation, more context on output structure would be helpful.
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 all 5 parameters. The description adds a useful default value for rootDir (defaults to projectRoot), which is not in the schema. Mostly redundant but one extra detail.
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?
Description clearly states it gets signature, location, and callers of a symbol in one call. It distinguishes from sibling tools like read_file_surgical and analyze_impact by highlighting 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?
Description mentions it's more efficient than combining read_file_surgical and analyze_impact, implying use when all three pieces of info are needed. However, it does not explicitly state 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.
Get cache statistics (entries, size, hit rate)
| Name | Required | Description | Default |
|---|---|---|---|
| projectRoot | Yes | Project root directory |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description indicates a read operation but does not explicitly state it is non-destructive or disclose any side effects, auth requirements, or behavior when cache is empty.
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?
Extremely concise, one short sentence. No wasted words, but could benefit from slight expansion on usage context.
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 simple stat retrieval tool with one parameter and no output schema, the description provides basic information. However, it lacks differentiation from sibling tools and does not explain the output format beyond listing fields.
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?
Single parameter 'projectRoot' with schema providing its description. The tool description adds no additional meaning beyond the schema, so baseline score of 3 applies.
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 'Get' with specific resource 'cache statistics' and mentions three specific metrics: entries, size, hit rate. Distinguishes from siblings like 'clear_cache' and 'get_server_stats'.
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?
No guidance on when to use this tool versus alternatives like 'get_server_stats' or 'get_session_stats'. No context on prerequisites or scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get file watcher status for a project
| Name | Required | Description | Default |
|---|---|---|---|
| projectRoot | Yes | Project root directory |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It only states 'Get' implying a read operation, but does not disclose potential side effects, permission requirements, rate limits, or what the status encompasses. The description is insufficient for a tool with no 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 a single sentence with no extraneous content, achieving conciseness. However, it could be slightly more structured or include additional details without becoming verbose. It earns a score of 4 for efficiency.
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 parameter, no output schema, no annotations), the description is minimal and lacks essential details about the return value or possible statuses. It does not provide enough context for an agent to understand what to expect from 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?
The input schema covers 100% of parameters with descriptions, providing adequate documentation at the schema level. The description adds no further meaning beyond the schema, so a baseline score of 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 the verb 'Get' and the resource 'file watcher status' for a project. It distinguishes from the sibling 'configure_file_watcher' which configures rather than retrieves. However, 'status' is somewhat vague and could be more specific about what aspects of the watcher status are returned.
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?
No guidance is provided on when to use this tool versus alternatives like 'configure_file_watcher'. There is no mention of prerequisites, context, or situations where this tool is appropriate or not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current rate limiter token balance and operation costs. Use before expensive operations to check available budget.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It clearly indicates a read-only status check with no side effects, which is adequate. However, it could elaborate on the meaning of 'operation costs' or the 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?
Two sentences: the first defines purpose, the second provides usage guidance. Every sentence earns its place with no redundancy 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?
Given the tool's simplicity (no parameters, no output schema), the description covers purpose and usage. It could be slightly more comprehensive about what exactly is returned, but it is sufficient for the tool's scope.
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 no parameters, and schema coverage is 100%. Baseline for zero parameters is 4. The description adds no parameter details because none exist, which 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 the tool gets the current rate limiter token balance and operation costs. The verb 'Get' and resource are specific, and it is distinct from all sibling tools which are file and analysis operations.
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 guidance: 'Use before expensive operations to check available budget.' This tells the agent when to use the tool and implies context for when it is beneficial.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a compressed architectural overview of an entire repository
| Name | Required | Description | Default |
|---|---|---|---|
| directoryPath | Yes | Absolute path to repository root | |
| projectRoot | Yes | Project root for security boundary | |
| format | No | Output format (default: xml) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully disclose behavioral traits. It does not mention whether the tool is read-only, required permissions, or limitations of the generated map.
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 the core purpose, but could be structured with bullet points or additional context without becoming verbose.
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 lack of output schema and annotations, the description is incomplete. It does not explain what the output contains, how it is structured, or how to interpret the result, which is crucial for a tool generating a complex overview.
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. The description adds no additional meaning beyond what the schema already provides for each parameter.
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 action ('Generate') and the deliverable ('compressed architectural overview of an entire repository'), making the tool's purpose immediately obvious and distinct from sibling tools.
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?
No guidance on when to use this tool versus alternatives like 'explain_symbol' or 'search_code_pattern'. Lacks context about prerequisites or scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get server telemetry, audit statistics, and health metrics
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It only indicates a read operation ('Get'), but fails to mention potential costs, permission requirements, response size, or whether it is safe to call frequently. More context is needed.
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, efficient sentence that lists the three types of data retrieved. Every word serves a purpose, and there is 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?
Given no parameters and no output schema, the description is the only contextual information. It specifies what is returned but lacks details on the output format, update frequency, or whether the data is cumulative. For a simple stat tool, it is adequate but not 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?
There are no parameters, so the schema is fully covered. The description does not need to add parameter details. With zero parameters, a baseline score of 4 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 retrieves server telemetry, audit statistics, and health metrics. It uses a specific verb ('Get') and resource types, and these are distinct from sibling tools like 'get_cache_stats' or 'get_session_stats', which focus on other data.
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 offers no guidance on when to use this tool versus alternatives, nor does it mention any preconditions or exclusions. With many sibling tools that also retrieve stats (e.g., get_cache_stats, get_session_stats), explicit usage context is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get statistics for the current MCP client session
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states 'statistics', but does not disclose whether the operation is read-only, what side effects may occur, or any required permissions. The nature of the returned data is unspecified.
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, efficient sentence that conveys the essential purpose without any extraneous content. It is front-loaded and direct, earning 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 the absence of annotations and output schema, the description is too minimal. It does not specify what statistics are included, how they can be used, or any limitations. For a tool with no parameters, more detail about the output would be expected for 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?
The input schema has no parameters (schema description coverage 100%). The description adds value by clarifying the scope ('for the current MCP client session'), which is not evident from the schema. For 0-parameter tools, the baseline is 4, and the description adequately explains 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 explicitly states 'Get statistics for the current MCP client session', clearly identifying the verb (get) and the resource (statistics for session). It differentiates from sibling tools like get_cache_stats and get_server_stats by specifying 'session'.
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 no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions. Without contextual hints, an agent cannot determine if this tool is appropriate for a given query.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Insert code at a specific location. Phase 1: returns diff + token. Phase 2: confirm with token to apply.
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Absolute path to file | |
| projectRoot | Yes | Project root (REQUIRED) | |
| code | No | Code to insert (Phase 1 only ΞΓΓΆ omit in Phase 2, server uses stored content) | |
| anchorSymbol | No | Symbol to position relative to | |
| position | No | Where to insert | |
| className | No | Class name (optional) | |
| confirm | No | Set true to apply a pending operation (Phase 2) | |
| confirmationToken | No | Token from Phase 1 dry-run (Phase 2 only) | |
| diffFormat | No | Diff verbosity in Phase 1 output (default: unified). Use none to skip diff and save tokens. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the two-phase process (dry-run then apply), diff generation, and token confirmation. However, it does not mention potential side effects, permissions, or error handling for token mismatches.
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 sentences, front-loaded with purpose, and efficiently structured. 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 the two-phase complexity and 9 parameters without output schema, the description covers the workflow well. It could mention that Phase 1 does not apply changes and clarify return value structure, but it is largely 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 description coverage is 100%, so baseline is 3. The description adds workflow context (Phase 1 vs Phase 2) but does not add meaning beyond the schema's parameter descriptions. The process explanation is helpful but not required for 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?
The description clearly states 'Insert code at a specific location' and outlines a two-phase workflow, distinguishing it from sibling tools like remove_symbol or rename_symbol. The purpose is specific and actionable.
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 for inserting code at a location but does not explicitly state when to use this tool versus alternatives like write_file_surgical or ast_transform. No when-not or exclusion criteria are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List pending operations for crash recovery
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It states the tool lists operations but does not disclose whether it is read-only (likely safe), side effects, rate limits, or permissions needed. Minimal disclosure beyond the basic action.
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 concise sentence that is front-loaded with the action and resource. It earns its place, though it could potentially include more structured details like return type without sacrificing conciseness.
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 parameters, no annotations, and no output schema, the description is minimally adequate. It explains the tool's purpose but lacks context about what 'pending operations' encompasses, return format, or any behavioral nuances. Adequate for a very simple tool but incomplete for richer understanding.
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 tool has zero parameters, and schema coverage is 100% trivially. According to guidelines, 0 parameters warrants a baseline of 4. The description adds no parameter info, but none is needed.
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 'List pending operations for crash recovery' clearly states the action (list) and resource (pending operations for crash recovery). It provides a specific purpose but does not explicitly distinguish it from sibling tools like 'clean_backups' or 'rollback_file'.
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?
No guidance is given on when to use this tool versus alternatives such as 'get_server_stats' or 'clear_cache'. The description implies usage for crash recovery context but lacks explicit when-not or alternative suggestions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Parse a file using Tree-sitter and extract symbols
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Absolute path to file | |
| projectRoot | Yes | Project root (REQUIRED) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose behavioral traits such as read-only nature, side effects, or limitations.
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, clear and to the point. Could be slightly more informative but avoids 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?
With 2 parameters, no output schema, and no annotations, the description is minimally adequate but lacks details on output format or language support.
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 100%, so baseline 3 applies. Description adds no extra meaning 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 parses a file with Tree-sitter and extracts symbols, which differentiates it from siblings like ast_transform or explain_symbol.
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?
No guidance on when to use this tool vs alternatives, nor any prerequisites or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read specific line ranges from a file
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Absolute path to file | |
| projectRoot | Yes | Project root for security boundary | |
| startLine | No | Starting line number (1-indexed) | |
| endLine | No | Ending line number (1-indexed) | |
| aroundPattern | No | Search pattern to find and return surrounding lines | |
| contextLines | No | Number of lines before/after pattern (default: 5) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It only states the purpose but does not describe performance with large files, error handling, security implications (only hinted by projectRoot param), or whether the tool modifies state. As a read operation, it likely does not mutate data, but this is not stated.
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, clear phrase with no extraneous words. It is front-loaded and efficient, though it could include more information without becoming verbose.
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 6 parameters and no output schema, the description is incomplete. It does not explain return values, behavior when lines are out of range, how aroundPattern interacts with startLine/endLine, or error scenarios. An agent would need more context to use it 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 descriptions cover 100% of parameters, so the baseline is 3. The description adds minimal extra meaning beyond the schema; it summarizes that the tool reads line ranges, but the schema already specifies startLine, endLine, aroundPattern, etc. No additional semantic context is provided.
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 'Read specific line ranges from a file' clearly states the action (read) and the resource (line ranges from a file). It is specific enough to distinguish from sibling tools like batch_read or read_file_surgical, though it does not explicitly call out differences.
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?
No guidance is provided on when to use this tool versus alternatives. There is no mention of conditions, exclusions, or context that would help an agent decide between this and similar tools like read_file_surgical or parse_file.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a file or extract a specific named symbol
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Absolute path to file | |
| projectRoot | Yes | Project root (REQUIRED) | |
| symbolName | No | Symbol name to extract (optional) | |
| className | No | Class name for scoping (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states a high-level function without any details about side effects, read-only guarantees, error behavior, or performance implications. For a surgical tool that extracts symbols, more transparency about what happens if the symbol is missing or how scoping with className works is needed.
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, front-loaded sentence that conveys the two primary use cases. It is appropriately concise without redundancy. However, a second sentence explaining when to use the optional parameters could improve structure without much bloat.
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 4 parameters, no output schema, and many siblings, the description is insufficient. It does not explain return format, error handling (e.g., file not found, symbol not found), or the interaction between parameters. The agent may not know how to properly invoke it for specific scenarios.
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?
All four parameters have schema descriptions (100% coverage), so baseline is 3. The description adds value by linking symbolName and className to 'extract a specific named symbol', providing context that the schema alone does not. However, it doesn't clarify the relationship between symbolName and className or whether extracting a symbol returns the entire symbol definition.
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 two distinct actions: reading a file and extracting a named symbol. This distinguishes it from siblings like read_file_lines (reads lines) and search_symbols (searches for symbols). However, it could be more explicit about the 'surgical' nature (e.g., extracting a symbol from a file) and how it differs from reading the whole file.
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 no guidance on when to use this tool vs. alternatives like read_file_lines, search_symbols, or parse_file. It doesn't explain when the optional symbolName parameter should be used instead of reading the whole file, or when className is needed. This leaves the agent unsure about selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a symbol from file. Phase 1: returns diff + token. Phase 2: confirm with token to apply.
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Absolute path to file | |
| projectRoot | Yes | Project root (REQUIRED) | |
| symbolName | Yes | Symbol to remove | |
| className | No | Class name (optional) | |
| force | No | Skip dependency check | |
| confirm | No | Set true to apply a pending operation | |
| confirmationToken | No | Token from Phase 1 dry-run |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the two-phase commitment (dry-run then confirm), which is a critical behavioral trait. However, it lacks details on the 'force' parameter's effect on dependency checks, potential side effects, or what happens to file backups. No annotations are provided, so the description bears the full burden.
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: two sentences that communicate the core purpose and the distinctive two-phase workflow. No wasted words, and the most critical information 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 (7 parameters, no output schema), the description is insufficient. It does not explain the return format (what does 'diff' look like?), error conditions, or the outcome of Phase 2. An agent would be left uncertain about how to interpret responses or handle failures.
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?
All parameters have descriptions in the schema (100% coverage), so the basic semantics are covered by the schema. The description adds context for the two-phase process (confirm and confirmationToken) but does not enrich understanding of other parameters like filePath, projectRoot, or force beyond what the schema states.
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 action ('Remove a symbol from file') and introduces the two-phase process, which is a key behavioral trait that distinguishes it from other tools like rename_symbol or insert_symbol. The verb and resource are 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 provides no guidance on when to use this tool versus its siblings (e.g., rename_symbol, ast_transform). It does not mention prerequisites, suitability conditions, or when the two-phase commitment is particularly useful or necessary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rename a symbol across the entire repository. Phase 1: returns diff + token. Phase 2: confirm with token to apply.
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | File where symbol is defined | |
| projectRoot | Yes | Project root (REQUIRED) | |
| oldName | Yes | Current name | |
| newName | Yes | New name | |
| rootDir | No | Repository root (optional) | |
| confirm | No | Set true to apply a pending operation | |
| confirmationToken | No | Token from Phase 1 dry-run |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the two-phase destructive behavior and the need for a confirmation token, which is critical for an AI agent to understand the operation's impact.
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 concise sentences, front-loaded with purpose. No wasted words; every sentence contributes meaning.
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 adequately covers the two-phase workflow and key parameters. However, it could detail the return format or safety considerations.
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 the description adds value by explaining the phased context for 'confirm' and 'confirmationToken' parameters, going beyond the schema's basic 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 verb 'rename' and the resource 'symbol across the entire repository,' effectively distinguishing it from sibling tools like insert_symbol or remove_symbol.
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 explains the two-phase process (dry-run then confirm), providing clear usage context, though it does not explicitly mention when not to use the tool or suggest alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Revert a file to its backup state
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Absolute path to file | |
| projectRoot | Yes | Project root (REQUIRED) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It implies overwriting a file with its backup, but does not specify if the operation is destructive, what happens if no backup exists, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence, highly concise. However, it may be too brief, missing important details while still being 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 the simplicity and no output schema, the description could mention what the tool returns (e.g., success/failure) or clarify that it overwrites the file. It feels slightly incomplete but not severely lacking.
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 descriptions for both parameters. The tool description adds no additional meaning beyond what the schema already provides.
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 action ('Revert') and resource ('a file to its backup state'). It is specific enough to understand the core function, but does not differentiate from similar siblings like 'clean_backups' or 'write_file_surgical'.
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?
No guidance is provided on when to use this tool versus alternatives (e.g., when a backup exists, or when not to use it). The description lacks context about prerequisites or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for code patterns across multiple files
| Name | Required | Description | Default |
|---|---|---|---|
| rootDir | Yes | Repository root directory | |
| projectRoot | Yes | Project root for security boundary | |
| pattern | Yes | Regular expression pattern to search | |
| fileExtensions | No | Extensions to search | |
| excludeDirs | No | Directories to exclude | |
| maxResults | No | Maximum matches to return (default: 10) | |
| startIndex | No | Start index for pagination (default: 0) | |
| fuzzyMatch | No | Enable fuzzy matching (default: false) | |
| fuzzyThreshold | No | Fuzzy match threshold 0-1 (default: 0.4) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits. It does not mention return format, side effects (e.g., file scanning), performance implications, or security boundaries (though rootDir and projectRoot are in schema). The minimal description fails to inform the agent about key behaviors.
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 very concise: one sentence. While it is not verbose, it could benefit from a brief sentence about use case or typical scenarios. Nonetheless, it avoids unnecessary 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?
Given the high parameter count (9), no output schema, and no annotations, the description is insufficiently complete. It does not explain pagination (startIndex, maxResults), fuzzy matching behavior, or how results are returned. Critical context for an agent to use the tool effectively is missing.
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 the schema already documents all parameters. The description adds no extra meaning or context for parameters like fuzzyMatch or excludeDirs. Baseline score of 3 is appropriate as description adds no value 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 searches for code patterns across multiple files. However, it does not differentiate from sibling tools like search_symbols, which might also search for patterns. A more precise definition of 'code patterns' (e.g., regex) would improve clarity.
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?
No usage guidance is provided. There is no mention of when to use this tool versus alternatives such as search_symbols or analyze_impact. The description lacks context for appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search symbols by name across the repo using AST (not text search). Finds classes, functions, methods by approximate name.
| Name | Required | Description | Default |
|---|---|---|---|
| rootDir | Yes | Directory to search in | |
| projectRoot | Yes | Project root for security boundary | |
| query | Yes | Symbol name or partial name to search | |
| fuzzy | No | Enable fuzzy name matching (default: false) | |
| types | No | Filter by symbol types: class_declaration, function_declaration, method_definition, etc. | |
| fileExtensions | No | Extensions to search (default: all supported) | |
| excludeDirs | No | Directories to exclude | |
| maxResults | No | Maximum results (default: 20) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden for behavioral disclosure. It reveals the use of AST and approximate name matching but does not mention performance characteristics, rate limits, or whether the tool is read-only (implied but not stated). The description adds moderate value but leaves gaps.
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 highly concise, consisting of two clear sentences with no redundant information. Every phrase earns its place by conveying essential distinctions (AST vs text search) and scope (classes, functions, methods).
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 8 parameters, no output schema, and no annotations, the description is brief. It does not explain the return format, pagination, or error behavior. While the tool is a search, more context about results would improve 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?
All 8 parameters are fully described in the input schema (100% coverage), so the description adds limited semantic value beyond 'approximate name' relating to the fuzzy parameter. The baseline of 3 is appropriate as the description does not significantly enhance 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?
The description clearly states the verb 'search', the resource 'symbols', and the method 'by name using AST (not text search)'. It specifies the types of symbols found (classes, functions, methods) and distinguishes from text search, effectively differentiating it from sibling tools like search_code_pattern.
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 notes that the search uses AST and not text search, providing a clear distinction for when to use this tool versus a text-based alternative. However, it does not explicitly state when not to use it or provide alternative tool names, missing the highest level of guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace a symbol with new code. Phase 1 (dry-run): returns diff + token. Phase 2: confirm with token to apply.
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Absolute path to file | |
| projectRoot | Yes | Project root (REQUIRED) | |
| symbolName | Yes | Symbol to replace | |
| newContent | No | New code (Phase 1 only ΞΓΓΆ omit in Phase 2, server uses stored content) | |
| className | No | Class name (optional, for scoping) | |
| confirm | No | Set true to apply a pending operation (Phase 2) | |
| confirmationToken | No | Token from Phase 1 dry-run (Phase 2 only) | |
| diffFormat | No | Diff verbosity in Phase 1 output (default: unified). Use none to skip diff and save tokens. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses the two-phase behavior, token requirement, and that newContent should be omitted in Phase 2. However, it does not mention side effects, error handling, or reversibility of modifications.
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 sentences with no wasted words. The first sentence gives the core purpose, and the second explains the phases. Front-loaded and 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 the complexity (8 parameters, two-phase workflow, no output schema), the description explains the essential workflow but does not detail return values, error states, or prerequisites like file existence. Still, it is largely complete for the intended 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%, but the description adds significant value by explaining how parameters relate to phases (e.g., newContent only used in Phase 1, confirm+confirmationToken for Phase 2). This contextualizes the parameters beyond their 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 replaces a symbol with new code, and the two-phase process (dry-run then confirm) distinguishes it from sibling tools like insert_symbol, remove_symbol, and rename_symbol.
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 the two phases with instructions for each: Phase 1 returns diff+token, Phase 2 requires confirmation and token. While it doesn't name alternatives, the phase logic provides clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most tools have distinct purposes, but some overlap exists (e.g., read_file_surgical and explain_symbol both retrieve symbol information, though with different focuses). Descriptions generally clarify boundaries.
All tool names follow a consistent snake_case verb_noun pattern. Verbs like get_, read_, search_, and direct verbs (clean, clear, insert) are used uniformly per function.
With 25 tools, the server is at the high end of the 'heavy' range. While the number is justified by the breadth of features (reading, writing, analysis, state management), it feels slightly bloated for a typical code context server.
The tool surface covers core read, write, search, and analysis operations well. However, there is no explicit create/delete file tool, and file-level operations are limited, leaving minor gaps.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Provide your AI coding tools with token-efficient access to up-to-date technical documentation forβ¦
Codebase intelligence for agents: 152 structured artifacts across 21 programs, one call.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/achatainga/mcp-code-context'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
