R3

Rename a component (its entityRef)

r3_component_rename

Destructive

Rename a component: its entityRef, the name scripts address it by (this['name'] / this.name), and its display name when that is where the entityRef came from. Name it by entityRef or componentId. Without planId it only PLANS and changes nothing: it checks the new name (refused: not an entityRef R3 makes, a reserved name, or taken in the same namespace: inside the same Entity, or at project level, naming the holder), and lists every Code script whose this['old'] / this.old finds THIS component (a script inside an Entity finds its own member first), with codeVersion and line numbers, plus scripts where the name is ambiguous and scripts that already read the new name. With that planId it applies the plan as ONE undoable change every open R3 tab sees. updateCode: true also rewrites those scripts in the same change (each on the version planned: one changed since refuses the whole rename, never merged); without it they keep the old name and silently find nothing. If anything changed since the plan, nothing is written and the new plan is returned.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "projectId": "<projectId>",
      "newRef": "<newRef>"
    },
    "name": "r3_component_rename"
  }
}

Input Schema

Name	Required	Description
`newRef`	Yes	The new entityRef: lower case, _ instead of spaces, @ and dots (e.g. "arena_ground").
`planId`	No	The plan being applied, from this tool without planId (same component and newRef). Leave it out to plan.
`entityRef`	No	The component to rename, by its entityRef (or its id). Or use componentId.
`projectId`	Yes	The project, from r3_project_load.
`updateCode`	No	With planId: also rewrite this['old'] / this.old in the listed scripts, in the same change. Default false.
`componentId`	No	The component to rename, by its id (needed when several share the entityRef).

Output Schema

Name	Required	Description
`seq`	Yes
`answer`	Yes	This answer in words: what was done, what R3 measured, decided or refused, and what to do next. The same text as the result's text block. Read it: the fields beside it are the data, this is the guidance.
`newRef`	Yes
`oldRef`	Yes
`planId`	Yes
`applied`	Yes
`patched`	Yes
`scripts`	Yes
`refusals`	Yes
`template`	Yes
`component`	Yes
`projectId`	Yes
`applicable`	Yes
`nameChange`	Yes
`notPatched`	Yes
`updateCode`	Yes
`environment`	Yes
`modulesScanned`	Yes
`newNameReaders`	Yes
`templateCopies`	Yes
`ambiguousScripts`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

AddedNov 9, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Far beyond the annotations: it discloses the two-phase plan/apply contract, the exact refusal conditions (not an entityRef R3 makes, reserved, taken in namespace), the script-impact scan with codeVersion and line numbers, ambiguity reporting, the atomic undoable nature of the apply, cross-tab visibility, and the stale-plan invalidation behavior. This is exactly the mutation context destructiveHint=true implies but cannot spell out.

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?

Front-loaded with purpose and the plan/apply rule, and every clause carries information; nothing is filler. However, the heavy parenthetical nesting and ALL-CAPS emphasis make it a dense run-on that is harder to parse than an equivalent set of shorter sentences.

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

Completeness5/5

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

For a destructive, stateful, two-call rename with code rewriting, all decision-relevant facts are present: validation failures, script discovery semantics, conflict refusal, and the plan application path. An output schema exists, so return-shape detail is appropriately left out.

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 coverage is 100%, so the baseline is 3; the description earns above that by explaining planId's provenance ('from this tool without planId') and the real consequence of updateCode (scripts keep the old name and silently find nothing, and one changed script refuses the whole rename, never merged). It also clarifies entityRef vs componentId selection.

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?

States a specific verb+resource (rename a component) and immediately specifies what is renamed: the entityRef, the name scripts address it by (this['name'] / this.name), and the display name where it was derived from the ref. That level of specificity distinguishes it from r3_component_set or r3_code_write, which touch adjacent concerns.

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

Usage Guidelines4/5

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

Gives explicit operating guidance: without planId it only plans, with that planId it applies. It also conditions updateCode usage and describes what happens if either is omitted. It does not explicitly name sibling tools (r3_component_set, r3_code_write) as alternatives, which keeps it short of a 5.

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

All R3 tools Inspect

Try in Browser

Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?