ghidra-mcp

Overview Schema Source Related Servers Discussions Admin

rename

Assign new names to functions, global variables, function arguments, or local variables in Ghidra, with support for namespace-qualified names and split-out variable occurrences.

Instructions

Rename a function, global label/variable, function argument, or local variable.

The target can be selected either with a compact typed selector or with the
`kind` and `function` arguments:
- `function:main` or `kind="function", target="main"`
- `global:g_counter` or `kind="global", target="0x404020"`
- `arg:#0@main`, `arg:argc@main`, or `kind="argument", function="main"`
- `local:uVar4@main` or `kind="local", function="main"`
- `var:name@main` or `kind="variable", function="main"` to match either
  an argument or local variable

For the decompiler's "Split Out As New Variable" behavior, pass
`split_at` with the instruction address of the variable occurrence to
isolate, for example `target="local:res@handler", new_name="did_index",
split_at="0x90003482"`. The split variable is type-locked the same way
Ghidra's UI action does, so the split survives the next decompile.

If `kind` is `auto` and no `function` is supplied, the target is first
treated as a function at/containing the resolved address, then as a global
label/variable. Function, global, argument, and local renames are marked as
`USER_DEFINED` in Ghidra.

For C++, `new_name` may be namespace-qualified, e.g.
`new_name="MyClass::method"` or `new_name="ns::sub::g_table"`. The namespace
hierarchy is created if missing (missing levels become plain namespaces;
existing namespaces/classes are reused), and the function or global symbol
is placed in that namespace. To create a real C++ class first (so methods
land in a `Class` rather than a plain namespace), use `namespaces(...,
action="create", kind="class")`. Namespace-qualified names are only valid
for function and global renames, not argument/local variables.

Args:
    target: Rename target selector. Local/argument selectors can use
        `<kind>:<variable-or-#index>@<function>`.
    new_name: Replacement name.
    program: Required Ghidra project path or name to target.
    kind: One of `auto`, `function`, `global`, `argument`, `local`, or
        `variable`.
    function: Function address/name for argument, local, or variable
        renames when not using the `@function` selector syntax.
    split_at: Optional instruction address of the local/argument
        occurrence to split out as a new variable before renaming.
    timeout: Decompiler timeout in seconds for local/argument renames.

Input Schema

TableJSON Schema

Name	Required	Default
`kind`	No	auto
`target`	Yes
`program`	Yes
`timeout`	No
`function`	No
`new_name`	Yes
`split_at`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.2.0Sep 15, 2026

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does a strong job: it states that renames are marked as USER_DEFINED in Ghidra, that split variables are type-locked the same way Ghidra's UI action does so the split survives the next decompile, and that namespace hierarchies are created if missing. It doesn't explicitly state that renames are destructive/irreversible or require write permissions, but the mutation semantics are clear from 'rename' and the USER_DEFINED detail adds meaningful context. A 4 is appropriate because it discloses key behavioral traits without explicitly covering reversibility or permission requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every section earns its place: selector syntax, split behavior, auto resolution, C++ namespaces, and parameter summaries. It is front-loaded with the core purpose and selector examples before diving into edge cases. It could be tightened slightly (the selector examples and the Args section overlap), but the density of useful information justifies the length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (7 parameters, 5 target kinds, split behavior, C++ namespace handling) and the absence of annotations, the description is remarkably complete. It covers selector syntax, auto-resolution order, split_at semantics, namespace qualification rules, and parameter roles. The only notable omissions are return value details (though an output schema exists) and explicit error/edge-case behavior (e.g., what happens if the target doesn't resolve). For a tool this complex, a 4 is strong; a 5 would require explicit failure-mode documentation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for the schema's bare parameter names. It does: it explains the target selector grammar in detail, defines each kind value, clarifies when function is needed, and gives a concrete split_at example. The only minor gap is that timeout is mentioned as 'Decompiler timeout in seconds for local/argument renames' but the description doesn't explain why a timeout matters or what happens on timeout. Still, this is far beyond what the schema provides, so a 4 is warranted.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Rename a function, global label/variable, function argument, or local variable.' It then enumerates the exact selector forms for each target kind, which distinguishes it from sibling tools like rename_batch, labels, and set_register. The scope is precise and immediately actionable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance: it explains the compact selector syntax versus the kind/function arguments, covers the decompiler's 'Split Out As New Variable' behavior with a concrete example, and even tells the agent when to use a sibling tool (namespaces(... action='create', kind='class')) for creating a real C++ class. It also states that namespace-qualified names are only valid for function and global renames, not argument/local variables. This is comprehensive routing and exclusion guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server