Rename Symbol

Rename a symbol across your entire codebase. Discovers all references via the knowledge graph and AST-aware search, then previews or applies the rename with confidence tags on every edit.

Parameters

Parameter	Type	Required	Default	Description
`repository`	string	Yes	-	Repository name (e.g., "owner/repo")
`symbol_name`	string	No	-	Symbol name to rename (e.g., "getUserById", "BookingService.validate")
`symbol_uid`	string	No	-	Direct symbol UID from prior tool calls
`new_name`	string	Yes	-	The new name for the symbol
`file_path`	string	No	-	Relative file path to disambiguate common names
`dry_run`	boolean	No	`true`	Preview edits without modifying files

Either symbol_name or symbol_uid must be provided. Default is dry_run: true (safe preview mode). Set dry_run: false to apply changes to disk.

Usage

Ask your agent:

"Rename getUserById to findUserById"

"Preview a rename of PaymentService.process to PaymentService.execute"

"Apply the rename of validateBooking to checkBooking"

Response Format

The response is a tagged enum with two possible outcomes:

Success

When the symbol is uniquely identified, returns the rename preview or result:

{
  "status": "success",
  "old_name": "getUserById",
  "new_name": "findUserById",
  "files_affected": 4,
  "total_edits": 7,
  "graph_edits": 5,
  "ast_search_edits": 2,
  "changes": [
    {
      "file_path": "src/users/service.ts",
      "edits": [
        {
          "line": 23,
          "old_text": "export function getUserById(id: string): User {",
          "new_text": "export function findUserById(id: string): User {",
          "confidence": "graph"
        }
      ]
    },
    {
      "file_path": "src/auth/service.ts",
      "edits": [
        {
          "line": 45,
          "old_text": "const user = await getUserById(token.userId);",
          "new_text": "const user = await findUserById(token.userId);",
          "confidence": "graph"
        }
      ]
    },
    {
      "file_path": "src/users/service.spec.ts",
      "edits": [
        {
          "line": 12,
          "old_text": "describe('getUserById', () => {",
          "new_text": "describe('findUserById', () => {",
          "confidence": "ast_search"
        }
      ]
    }
  ],
  "applied": false
}

Ambiguous

When multiple symbols match the query, returns candidates for disambiguation:

{
  "status": "ambiguous",
  "message": "Found 2 symbols matching 'validate'. Use symbol_uid or file_path to disambiguate.",
  "candidates": [
    {
      "uid": "abc123",
      "name": "validate",
      "kind": "Function",
      "file_path": "src/booking/validator.ts",
      "line": 15
    },
    {
      "uid": "def456",
      "name": "validate",
      "kind": "Method",
      "file_path": "src/payment/processor.ts",
      "line": 42
    }
  ]
}

To resolve ambiguity, re-call the tool with the symbol_uid from the desired candidate.

Response Fields

Success Fields

Field	Type	Description
`old_name`	string	The original symbol name
`new_name`	string	The new symbol name
`files_affected`	number	Number of files with changes
`total_edits`	number	Total number of individual edits
`graph_edits`	number	Edits from the knowledge graph (semantic, high confidence)
`ast_search_edits`	number	Edits from AST tree-sitter search (structural, lower confidence)
`changes`	array	Per-file changes with individual edits
`applied`	boolean	Whether changes were written to disk

Edit Confidence

Each edit is tagged with a confidence level indicating how it was discovered:

Confidence	Source	Meaning
`graph`	Knowledge graph	Semantic reference from the analyzed graph. High confidence -- these are known callers, importers, and references.
`ast_search`	Tree-sitter AST search	Structural match found by scanning AST nodes. Lower confidence -- includes test files, string literals, and references not captured by the graph.

Review ast_search edits carefully. They may include matches in comments, string literals, or unrelated symbols that happen to share the name.

File Change

Field	Type	Description
`file_path`	string	Relative path within the repository
`edits`	array	Individual line-level edits for this file

Rename Edit

Field	Type	Description
`line`	number	1-based line number
`old_text`	string	Original line text (trimmed)
`new_text`	string	Modified line text (trimmed)
`confidence`	string	`"graph"` or `"ast_search"`

Workflow

Safe Rename (Recommended)

Preview the rename with dry_run: true (default)
Review the edits, paying attention to ast_search confidence edits
Apply by re-calling with dry_run: false

Quick Rename

For well-isolated symbols with few references:

Rename getUserById to findUserById and apply the changes

The agent will call with dry_run: false directly.

Tips

Always preview first for symbols with many references
Use symbol_uid from noodlbox_symbol_context results for unambiguous renames
Check graph_edits vs ast_search_edits to understand edit confidence distribution
Auto-accept graph edits -- they come from semantic analysis of the knowledge graph
Manually review ast_search edits -- they may include false positives
File paths are all relative to the repository root

Symbol Context - Understand a symbol before renaming
Impact Detection - Check impact after rename
Context Search - Find related code
Refactoring Workflow - Guided refactoring workflows

On this page