Skip to content

get_symbol_references

Find all usages of a function, class, method, or variable across the project to understand impact before making changes.

Quick Reference

get_symbol_references(
    symbol_name: str,                # Symbol to find
    project_root: str = None,        # Project directory
    scope_prefix: str = None,        # Limit search scope
    include_tests: bool = True       # Include test files
) -> SymbolReferences

User Stories

Persona Story Tool Value
👤 Sarah (AI User) "Find all usages of a function without grepping every file" Precise search, no wasted searching
👥 David (Team Lead) "Find all places this function is used before refactoring" Impact analysis
🏢 Jennifer (Enterprise Architect) "Trace function usages across 500-2000 user organization" Enterprise-scale reference tracking

→ See all user stories

Parameters

Parameter Type Required Default Description
symbol_name string Yes - Name of symbol to find
project_root string No cwd Project root directory
scope_prefix string No None Limit to files matching prefix
include_tests bool No true Include test files in results

Response Schema

{
  "data": {
    "symbol_name": "string",
    "definition": {
      "file": "string",
      "line": "integer",
      "type": "string",
      "code": "string"
    },
    "references": [
      {
        "file": "string",
        "line": "integer",
        "column": "integer",
        "context": "string",
        "usage_type": "string"
      }
    ],
    "summary": {
      "total_references": "integer",
      "files_with_references": "integer",
      "by_usage_type": {
        "call": "integer",
        "import": "integer",
        "assignment": "integer",
        "type_hint": "integer"
      }
    }
  },
  "tier_applied": "string",
  "duration_ms": "integer"
}

Examples

Find All References to a Function

Find all usages of the validate_email function

{
  "symbol_name": "validate_email"
}

codescalpel get-symbol-references validate_email

{
  "data": {
    "symbol_name": "validate_email",
    "definition": {
      "file": "validators.py",
      "line": 15,
      "type": "function",
      "code": "def validate_email(email: str) -> bool:"
    },
    "references": [
      {
        "file": "validators.py",
        "line": 15,
        "context": "def validate_email(email: str) -> bool:",
        "usage_type": "definition"
      },
      {
        "file": "services/user_service.py",
        "line": 5,
        "context": "from validators import validate_email",
        "usage_type": "import"
      },
      {
        "file": "services/user_service.py",
        "line": 28,
        "context": "if not validate_email(user.email):",
        "usage_type": "call"
      },
      {
        "file": "api/routes.py",
        "line": 12,
        "context": "from validators import validate_email",
        "usage_type": "import"
      },
      {
        "file": "api/routes.py",
        "line": 45,
        "context": "is_valid = validate_email(request.form['email'])",
        "usage_type": "call"
      },
      {
        "file": "tests/test_validators.py",
        "line": 8,
        "context": "from validators import validate_email",
        "usage_type": "import"
      },
      {
        "file": "tests/test_validators.py",
        "line": 15,
        "context": "assert validate_email('user@example.com') == True",
        "usage_type": "call"
      }
    ],
    "summary": {
      "total_references": 7,
      "files_with_references": 4,
      "by_usage_type": {
        "definition": 1,
        "import": 3,
        "call": 3
      }
    }
  },
  "tier_applied": "community",
  "duration_ms": 85
}

Find Class References

Find all usages of the UserService class

{
  "symbol_name": "UserService"
}

codescalpel get-symbol-references UserService

{
  "data": {
    "symbol_name": "UserService",
    "definition": {
      "file": "services/user_service.py",
      "line": 10,
      "type": "class",
      "code": "class UserService:"
    },
    "references": [
      {
        "file": "services/user_service.py",
        "line": 10,
        "usage_type": "definition"
      },
      {
        "file": "api/routes.py",
        "line": 8,
        "context": "from services.user_service import UserService",
        "usage_type": "import"
      },
      {
        "file": "api/routes.py",
        "line": 25,
        "context": "user_service = UserService(db)",
        "usage_type": "instantiation"
      },
      {
        "file": "main.py",
        "line": 15,
        "context": "service: UserService",
        "usage_type": "type_hint"
      }
    ],
    "summary": {
      "total_references": 4,
      "by_usage_type": {
        "definition": 1,
        "import": 1,
        "instantiation": 1,
        "type_hint": 1
      }
    }
  }
}

Find usages of process_order only in the services directory

{
  "symbol_name": "process_order",
  "scope_prefix": "services/"
}

codescalpel get-symbol-references process_order --scope-prefix services/

{
  "data": {
    "symbol_name": "process_order",
    "references": [
      {
        "file": "services/order_service.py",
        "line": 45,
        "usage_type": "definition"
      },
      {
        "file": "services/payment_service.py",
        "line": 78,
        "context": "order_service.process_order(order_data)",
        "usage_type": "call"
      }
    ],
    "scope_applied": "services/",
    "summary": {
      "total_references": 2
    }
  }
}

Exclude Tests

Find usages of calculate_total excluding test files

{
  "symbol_name": "calculate_total",
  "include_tests": false
}

codescalpel get-symbol-references calculate_total --no-tests

{
  "data": {
    "symbol_name": "calculate_total",
    "references": [
      {
        "file": "utils/math.py",
        "line": 20,
        "usage_type": "definition"
      },
      {
        "file": "services/order_service.py",
        "line": 56,
        "usage_type": "call"
      },
      {
        "file": "api/routes.py",
        "line": 89,
        "usage_type": "call"
      }
    ],
    "excluded_test_references": 5,
    "summary": {
      "total_references": 3
    }
  }
}

Usage Types

Type Description Example
definition Where symbol is defined def func():
import Import statement from mod import func
call Function/method call func(args)
instantiation Class instantiation obj = Class()
type_hint Type annotation x: Class
assignment Variable assignment func = other_func
attribute_access Attribute access obj.method
inheritance Class inheritance class Sub(Base):

Tier Differences

This tool is available at all tiers. What differs are the limits and capabilities:

Feature Community Pro Enterprise
Availability ✅ Available ✅ Available ✅ Available
Basic reference finding ✅ ✅ Advanced ✅ Advanced
Usage type classification ✅ ✅ ✅
Scope filtering ✅ ✅ ✅
Max files 100 1,000 Unlimited
Cross-project references Not available Not available ✅ Multi-repo

Error Handling

Symbol Not Found

{
  "data": {
    "symbol_name": "validat_email",
    "definition": null,
    "references": [],
    "suggestions": ["validate_email", "validate_mail"]
  }
}

Tier Limits

get_symbol_references capabilities vary by tier:

Feature Community Pro Enterprise
Max files searched 10 Unlimited Unlimited
Max references 50 Unlimited Unlimited
Cross-file search ✅ ✅ ✅
Test file inclusion ✅ ✅ ✅
Scope filtering Basic ✅ Advanced ✅ Advanced
Reference context Basic ✅ Enhanced ✅ Full

Community Tier

  • ✅ Find symbol references across files
  • ✅ Include test files in search
  • ✅ Basic scope filtering
  • ⚠️ Limited to 10 files searched - May miss references in large codebases
  • ⚠️ Max 50 references returned - Truncated for popular symbols
  • ❌ No advanced filtering options

Pro Tier

  • ✅ All Community features
  • ✅ Unlimited file search - Search entire codebase
  • ✅ Unlimited references - Complete reference list
  • ✅ Advanced scope filtering - Filter by module, package, or custom prefix
  • ✅ Enhanced reference context - Line numbers, surrounding code

Enterprise Tier

  • ✅ All Pro features
  • ✅ Full semantic context - Understand how symbol is used
  • ✅ Cross-repository search - Find references across multiple repos
  • ✅ Usage pattern analysis - Common usage patterns
  • ✅ Impact analysis - What breaks if symbol changes

Key Difference: Search Scope - Community: 10 files, 50 references - Quick check in small projects - Pro: Unlimited - Full codebase reference search - Enterprise: Unlimited + cross-repo - Organization-wide search

→ See tier comparison

Best Practices

  1. Check before renaming - Know impact before changing
  2. Use scope - Narrow down large projects
  3. Exclude tests for refactoring - Focus on production code
  4. Check all usage types - Imports, calls, type hints all matter
  5. Review definitions - Ensure you found the right symbol

Workflow

graph TD
    A[Want to change symbol] --> B[get_symbol_references]
    B --> C{Many references?}
    C -->|Yes| D[Plan carefully]
    C -->|No| E[Safe to change]
    D --> F[Update incrementally]
    E --> G[rename_symbol or update_symbol]