Context & Navigation Tools¶

Context tools help AI assistants navigate large codebases efficiently. Instead of reading entire files, these tools provide targeted information about project structure, file contents, and symbol locations.

Tools in This Category¶

crawl_project¶

Inventory all files in a project with language detection and statistics.

What It Does¶

crawl_project scans a directory tree and returns:

• File inventory: All files with paths and languages
• Statistics: Line counts, function counts, class counts
• Complexity warnings: Files that exceed complexity thresholds
• Entry points: Detected main files, CLI commands, routes
• Framework hints: Detected frameworks (Django, Flask, React, etc.)

When AI Agents Use This¶

• Starting work on a new codebase
• Understanding project organization
• Finding files related to a feature
• Identifying complex "hot spots"

Quick Reference¶

Parameters¶

Example Usage¶

{
  "tool": "crawl_project",
  "parameters": {
    "root_path": "/path/to/project"
  }
}

{
  "tool": "crawl_project",
  "parameters": {
    "root_path": "/path/to/project/src",
    "pattern": "\\.py$",
    "pattern_type": "regex"
  }
}

Response Format¶

{
  "data": {
    "success": true,
    "root_path": "/path/to/project",
    "summary": {
      "total_files": 45,
      "total_lines_of_code": 12500,
      "total_functions": 230,
      "total_classes": 42,
      "complexity_warnings": 3
    },
    "language_breakdown": {
      "Python": 30,
      "JavaScript": 10,
      "TypeScript": 5
    },
    "entrypoints": [
      "src/main.py",
      "src/cli.py"
    ],
    "framework_hints": ["Flask", "SQLAlchemy"],
    "files": [
      {
        "path": "src/main.py",
        "language": "Python",
        "lines": 150,
        "functions": 8,
        "classes": 2
      }
    ]
  },
  "tier_applied": "community",
  "duration_ms": 1250
}

Tier Differences¶

Full deep dive

get_file_context¶

Get a quick overview of a file without reading its full contents.

What It Does¶

get_file_context provides a token-efficient summary of a file:

• Structure overview: Functions, classes, imports (first 20)
• Metadata: Line count, language, complexity score
• Exports: Public API (all or exports)
• Security flag: Whether security issues detected

When AI Agents Use This¶

• Deciding whether to read a file in detail
• Quick lookup of what's in a file
• Checking if a file is relevant to the task
• Finding the right file in a large codebase

Quick Reference¶

Parameters¶

Example Usage¶

Prompt:

"What's in the auth.py file?"

Tool Call:

{
  "tool": "get_file_context",
  "parameters": {
    "file_path": "src/auth.py"
  }
}

Response Format¶

{
  "data": {
    "success": true,
    "file_path": "src/auth.py",
    "language": "Python",
    "line_count": 245,
    "functions": ["authenticate", "logout", "refresh_token"],
    "classes": ["AuthService", "TokenManager"],
    "imports": ["flask", "jwt", "datetime"],
    "exports": ["AuthService", "authenticate"],
    "complexity_score": 12.5,
    "has_security_issues": false,
    "summary": "Authentication service with JWT token management"
  },
  "tier_applied": "community",
  "duration_ms": 35
}

Tier Differences¶

Full deep dive

get_symbol_references¶

Find all usages of a symbol across the project.

What It Does¶

get_symbol_references searches the entire codebase for references to a symbol:

• Definition location: Where the symbol is defined
• All usages: Every file and line where it's used
• Reference types: Calls, reads, writes, imports (Pro+)
• Impact analysis: Risk assessment for changes (Enterprise)

When AI Agents Use This¶

• Before renaming a function/class
• Understanding how code is used
• Finding all callers of a function
• Impact analysis before refactoring

Quick Reference¶

Parameters¶

Example Usage¶

Prompt:

"Find all places where authenticate_user is called"

Tool Call:

{
  "tool": "get_symbol_references",
  "parameters": {
    "symbol_name": "authenticate_user",
    "project_root": "/path/to/project"
  }
}

Response Format¶

{
  "data": {
    "success": true,
    "symbol_name": "authenticate_user",
    "definition_file": "src/auth/service.py",
    "definition_line": 45,
    "references": [
      {
        "file": "src/api/routes.py",
        "line": 23,
        "column": 12,
        "context": "user = authenticate_user(username, password)",
        "reference_type": "call"
      },
      {
        "file": "src/cli/commands.py",
        "line": 67,
        "column": 8,
        "context": "from src.auth.service import authenticate_user",
        "reference_type": "import"
      }
    ],
    "total_references": 15,
    "files_scanned": 42,
    "category_counts": {
      "call": 12,
      "import": 3
    }
  },
  "tier_applied": "pro",
  "duration_ms": 340
}

Tier Differences¶

Full deep dive

Related Categories¶

• Analysis Tools - Parse code structure
• Extraction Tools - Extract specific code
• Graph Tools - Visualize code relationships