Skip to main content

​
Overview

The context tool provides comprehensive information about a specific code symbol, including all incoming and outgoing relationships, process participation, and categorized references. It’s the go-to tool for understanding “what does this symbol do and how is it connected to the rest of the codebase?”
When to use: After query() to understand a specific symbol in depth. When you need to know all callers, callees, and what execution flows a symbol participates in.Next step: Use impact() if planning changes, or READ gitnexus://repo/{name}/process/{processName} for full execution trace.

​
Parameters

​
name
string
Symbol name to look up (e.g., “validateUser”, “AuthService”)If multiple symbols share this name, the tool returns disambiguation candidates.
​
uid
string
Direct symbol UID from prior tool results for zero-ambiguity lookupWhen you have a uid from query() results, prefer this over name to avoid disambiguation.
​
file_path
string
File path to disambiguate common namesExample: "src/auth/validator.ts" when multiple validate functions exist
​
include_content
boolean
default:false
Include full source code for the symbol in results
Enabling this increases response size.
​
repo
string
Repository name or path. Required when multiple repos are indexed.
At least one of name, uid, or file_path must be provided.

​
Response

​
symbol
object
required
The target symbol’s metadata
​
incoming
object
required
Categorized incoming references (what depends on this symbol)
​
outgoing
object
required
Categorized outgoing references (what this symbol depends on)
​
processes
array
Execution flows this symbol participates in
​
disambiguation
array
When multiple symbols match, returns candidates to choose from

​
Example Usage

​
Lookup by Name

context({
  name: "validateUser"
})

​
Lookup by UID (Zero-Ambiguity)

// Using uid from query() results
context({
  uid: "func_validateUser_abc123"
})

​
Disambiguate by File Path

context({
  name: "validate",
  file_path: "src/auth/validator.ts"
})

​
With Source Code

context({
  name: "processPayment",
  include_content: true
})

​
Multi-Repo Context

context({
  name: "validateUser",
  repo: "my-app"
})

​
Example Response

{
  "symbol": {
    "uid": "func_validateUser_abc123",
    "name": "validateUser",
    "type": "Function",
    "filePath": "src/auth/validator.ts",
    "line": 42,
    "module": "Authentication"
  },
  "incoming": {
    "calls": [
      {
        "name": "loginHandler",
        "type": "Function",
        "filePath": "src/auth/login.ts",
        "line": 18
      },
      {
        "name": "apiMiddleware",
        "type": "Function",
        "filePath": "src/api/middleware.ts",
        "line": 25
      }
    ],
    "imports": [
      {
        "name": "authRouter",
        "filePath": "src/routes/auth.ts"
      }
    ]
  },
  "outgoing": {
    "calls": [
      {
        "name": "checkToken",
        "type": "Function",
        "filePath": "src/auth/token.ts",
        "line": 10
      },
      {
        "name": "getUserById",
        "type": "Function",
        "filePath": "src/db/users.ts",
        "line": 34
      }
    ],
    "imports": [
      {
        "module": "jsonwebtoken"
      }
    ]
  },
  "processes": [
    {
      "name": "LoginFlow",
      "step": 2,
      "totalSteps": 5
    },
    {
      "name": "TokenRefresh",
      "step": 1,
      "totalSteps": 3
    }
  ]
}

​
Disambiguation Example

When multiple symbols share the same name: 
{
  "disambiguation": [
    {
      "uid": "func_validate_auth_123",
      "name": "validate",
      "type": "Function",
      "filePath": "src/auth/validator.ts",
      "line": 10
    },
    {
      "uid": "func_validate_payment_456",
      "name": "validate",
      "type": "Function",
      "filePath": "src/payments/validator.ts",
      "line": 22
    }
  ],
  "message": "Multiple symbols found. Please refine your query using uid or file_path."
}

​
Real-World Examples

​
Example 1: Understanding a Function

// Task: "What does validateUser do and who calls it?"
context({
  name: "validateUser"
})

// Returns:
// - Incoming calls: loginHandler, apiMiddleware
// - Outgoing calls: checkToken, getUserById
// - Processes: LoginFlow (step 2/5), TokenRefresh (step 1/3)

​
Example 2: Debugging an Error

// Task: "This function is failing - what does it call?"
context({
  name: "validatePayment",
  include_content: true
})

// Returns:
// - Outgoing calls: verifyCard, fetchRates (external API!)
// - Root cause found: fetchRates has no timeout

​
Example 3: Impact Analysis Prep

// Task: "I want to change this - what depends on it?"
context({
  name: "processCheckout"
})

// Returns:
// - Incoming calls: checkoutHandler, webhookHandler, scheduledProcessor
// - Affected processes: CheckoutFlow, RefundFlow

​
Best Practices

If you have a uid from query() results, always use it for instant, unambiguous lookup. This avoids disambiguation overhead.
The categorization (calls, imports, extends, implements) helps you quickly understand different types of relationships without parsing raw data.
The processes array shows which execution flows involve this symbol. This is crucial for understanding the symbol’s role in the system.
Use context() iteratively: start with one symbol, then call context() on its dependencies to trace through the codebase.
For common names like “validate” or “process”, provide file_path upfront to avoid disambiguation rounds.

​
Use Cases

  • Understanding symbols: “What does this function do?”
  • Finding dependencies: “What does this call?”
  • Finding dependents: “What calls this?”
  • Debugging: “Trace this error’s call chain”
  • Refactoring prep: “What breaks if I change this?”
  • Process tracing: “Which flows use this?”
  • query - Find symbols before getting their context
  • impact - Analyze blast radius before changes
  • cypher - Custom relationship queries
  • gitnexus://repo/{name}/process/{name} - Full execution trace for processes
  • gitnexus://repo/{name}/cluster/{name} - View all symbols in a functional area

Build docs developers (and LLMs) love

Get started for freeTalk to us