Code Extraction & Modification Tools¶

Extraction tools allow AI assistants to surgically extract specific code elements and safely modify them without affecting surrounding code.

Tools in This Category¶

extract_code¶

Extract a specific function, class, or method by name.

What It Does¶

extract_code retrieves exactly the code you need by name—no line number guessing:

• Surgical extraction: Get only the specified symbol
• Dependency info: What imports/dependencies the code needs
• Token estimate: How many tokens the extracted code uses
• Cross-file deps: Optionally resolve imports from other files (Pro+)

When AI Agents Use This¶

• Getting a specific function to review or modify
• Reducing token usage (extract vs read entire file)
• Understanding what dependencies code needs
• Preparing code for modification with update_symbol

Quick Reference¶

Parameters¶

*Provide either file_path or code, not both.

Example Usage¶

{
  "tool": "extract_code",
  "parameters": {
    "file_path": "src/orders.py",
    "target_type": "function",
    "target_name": "process_order"
  }
}

{
  "tool": "extract_code",
  "parameters": {
    "file_path": "src/services/user.py",
    "target_type": "class",
    "target_name": "UserService"
  }
}

{
  "tool": "extract_code",
  "parameters": {
    "file_path": "src/models/order.py",
    "target_type": "method",
    "target_name": "Order.validate"
  }
}

Response Format¶

{
  "data": {
    "success": true,
    "target_type": "function",
    "target_name": "process_order",
    "source": "def process_order(order_id: str, items: list) -> Order:\n    \"\"\"Process a new order.\"\"\"\n    order = Order(order_id)\n    for item in items:\n        order.add_item(item)\n    order.calculate_total()\n    return order",
    "line_start": 45,
    "line_end": 52,
    "dependencies": ["Order"],
    "imports_needed": ["from models import Order"],
    "token_estimate": 87
  },
  "tier_applied": "community",
  "duration_ms": 28
}

Why This Matters¶

Tier Differences¶

Full deep dive

update_symbol¶

Safely replace a function, class, or method with new code.

What It Does¶

update_symbol replaces specific code elements without touching surrounding code:

• Automatic backup: Creates backup before modifying
• Syntax validation: Verifies new code is valid
• Surrounding preservation: Doesn't affect other code
• Precise targeting: By name, not line numbers

When AI Agents Use This¶

• Fixing bugs in specific functions
• Refactoring code after review
• Implementing feature changes
• Applying security patches

Quick Reference¶

Parameters¶

Example Usage¶

{
  "tool": "update_symbol",
  "parameters": {
    "file_path": "src/auth.py",
    "target_type": "function",
    "target_name": "authenticate_user",
    "new_code": "def authenticate_user(username: str, password: str) -> Optional[User]:\n    \"\"\"Authenticate user with parameterized query.\"\"\"\n    cursor.execute('SELECT * FROM users WHERE username = ?', (username,))\n    return cursor.fetchone()"
  }
}

{
  "tool": "update_symbol",
  "parameters": {
    "file_path": "src/models/user.py",
    "target_type": "method",
    "target_name": "User.validate",
    "new_code": "def validate(self) -> bool:\n    \"\"\"Validate user data including email format.\"\"\"\n    if not self.email or '@' not in self.email:\n        return False\n    return len(self.name) > 0"
  }
}

Response Format¶

{
  "data": {
    "success": true,
    "file_path": "src/auth.py",
    "target_type": "function",
    "target_name": "authenticate_user",
    "backup_path": "src/auth.py.bak",
    "lines_replaced": {
      "start": 15,
      "end": 25
    },
    "new_lines": {
      "start": 15,
      "end": 20
    }
  },
  "tier_applied": "community",
  "duration_ms": 45
}

Tier Differences¶

Full deep dive

rename_symbol¶

Rename a symbol across the entire codebase.

What It Does¶

rename_symbol performs project-wide renaming:

• Finds all usages: Uses get_symbol_references internally
• Updates all files: Renames in every location
• Preserves references: Updates imports, calls, and definitions
• Creates backups: For all modified files

When AI Agents Use This¶

• Refactoring for better naming
• Fixing typos in function/class names
• Standardizing naming conventions
• API migrations

Quick Reference¶

Parameters¶

Example Usage¶

Prompt:

"Rename getUserData to fetchUserProfile across the codebase"

Tool Call:

{
  "tool": "rename_symbol",
  "parameters": {
    "file_path": "src/api/users.py",
    "target_type": "function",
    "target_name": "getUserData",
    "new_name": "fetchUserProfile"
  }
}

Response Format¶

{
  "data": {
    "success": true,
    "old_name": "getUserData",
    "new_name": "fetchUserProfile",
    "files_modified": [
      "src/api/users.py",
      "src/api/routes.py",
      "src/services/user_service.py",
      "tests/test_users.py"
    ],
    "references_updated": 12,
    "backups_created": [
      "src/api/users.py.bak",
      "src/api/routes.py.bak",
      "src/services/user_service.py.bak",
      "tests/test_users.py.bak"
    ]
  },
  "tier_applied": "pro",
  "duration_ms": 890
}

Tier Differences¶

Full deep dive

Common Workflows¶

Extract → Review → Update¶

1. extract_code("src/auth.py", "function", "login")
   → Get the current code

2. [AI reviews and improves code]

3. update_symbol("src/auth.py", "function", "login", new_code)
   → Apply the improvement

Analyze → Extract → Rename¶

1. analyze_code("src/api.py")
   → Find all functions

2. extract_code("src/api.py", "function", "getData")
   → Review the function

3. rename_symbol("src/api.py", "function", "getData", "fetch_data")
   → Rename to snake_case

Related Categories¶

• Analysis Tools - Understand code before extracting
• Security Tools - Scan code after modifying
• Symbolic Tools - Verify changes don't break behavior