Tools Reference¶

Code Scalpel provides 23 MCP tools that give AI assistants surgical precision for code operations. This section provides complete documentation for every tool.

Browse Tools¶

By Category

Tools organized by what they do: analysis, extraction, security, etc.

Browse by category
By Tier

See which tools are available in Community, Pro, and Enterprise.

Browse by tier
User Stories

Real-world use cases organized by persona (Sarah, Marcus, David, Alex).

Browse by persona
Deep Dives

Detailed documentation for each tool with examples.

Deep dives

Tools at a Glance¶

All Tools Available at All Tiers

Every tool below is available in Community, Pro, and Enterprise tiers. What differs are the limits and capabilities - Pro and Enterprise provide enhanced limits, cross-file analysis, and advanced features. See tier comparison for details.

Analysis & Context¶

Tool	Description
`analyze_code`	Parse code structure (functions, classes, imports)
`crawl_project`	Inventory all files in a project
`get_file_context`	Quick file overview without full read
`get_symbol_references`	Find all usages of a symbol

Code Extraction & Modification¶

Tool	Description
`extract_code`	Surgically extract functions/classes by name
`update_symbol`	Safely replace code with automatic backup
`rename_symbol`	Rename across entire codebase

Security¶

Tool	Description
`security_scan`	Taint-based vulnerability detection
`unified_sink_detect`	Polyglot sink detection
`cross_file_security_scan`	Cross-module taint tracking
`scan_dependencies`	Check for CVEs in dependencies
`type_evaporation_scan`	TypeScript type safety analysis

Graph Analysis¶

Tool	Description
`get_call_graph`	Build function call graphs
`get_project_map`	High-level project structure
`get_graph_neighborhood`	K-hop graph traversal
`get_cross_file_dependencies`	Cross-file import chains

Symbolic Execution¶

Tool	Description
`symbolic_execute`	Z3-based path exploration
`generate_unit_tests`	Auto-generate test cases
`simulate_refactor`	Verify refactors preserve behavior

Policy & Governance¶

Tool	Description
`validate_paths`	Docker-aware path validation
`verify_policy_integrity`	Cryptographic policy verification
`code_policy_check`	Compliance rule checking

Tool Response Format¶

All tools return a consistent response envelope:

{
  "data": {
    // Tool-specific results
  },
  "tier_applied": "community",  // Which tier was used
  "duration_ms": 45,            // Processing time
  "error": null                 // Error message if failed
}

Success Response¶

{
  "data": {
    "functions": [...],
    "classes": [...]
  },
  "tier_applied": "community",
  "duration_ms": 45
}

Error Response¶

{
  "data": null,
  "error": {
    "code": "FILE_NOT_FOUND",
    "message": "File '/path/to/file.py' does not exist",
    "suggestions": ["Check the file path", "Use validate_paths first"]
  },
  "tier_applied": "community"
}

Supported Languages¶

Language	Analysis	Extraction	Security	Graph
Python	✅	✅	✅	✅
JavaScript	✅	✅	✅	✅
TypeScript	✅	✅	✅	✅
Java	✅	✅	✅	✅
JSX	✅	✅	✅	—
TSX	✅	✅	✅	—

How AI Agents Use These Tools¶

Code Scalpel tools are designed for AI assistants to invoke automatically. Here's how they work in practice:

Example: Analyzing Code¶

When you ask an AI assistant to "analyze this Python file," it invokes:

Tool: analyze_code
Parameters: { "file_path": "/path/to/file.py" }

The tool returns structured JSON that the AI interprets and explains to you.

Example: Finding Vulnerabilities¶

When you ask "check this code for security issues," the AI invokes:

Tool: security_scan
Parameters: { "file_path": "/path/to/file.py" }

Example: Safe Code Modification¶

When you ask "rename this function across the codebase," the AI:

Invokes get_symbol_references to find all usages
Invokes rename_symbol to perform the rename
Reports what was changed

Best Practices¶

For Users¶

Be specific - Tell the AI which tool to use if you know
Use absolute paths - Helps avoid file-not-found errors
Start with analysis - Use analyze_code before making changes
Check security - Run security_scan after modifications

For AI Agents¶

Use analyze_code first - Understand structure before modifying
Use extract_code instead of reading - More token-efficient
Use simulate_refactor before update_symbol - Verify safety
Use validate_paths in Docker - Ensure file access

Next Steps¶

Tool Categories

Browse tools by what they do

Categories
Deep Dives

Detailed documentation with examples

Deep dives
Tutorials

Learn tools through practical examples

Tutorials