Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ropey rename get_data to fetch_data in current file"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Safe, project-wide Python refactoring for coding agents. ropey is an MCP server that exposes the rope refactoring library as tools a coding agent (Claude in Claude Code, OpenCode, or any MCP client) can call.
Coding agents read and navigate Python well. An LSP like Astral's ty answers "where is this defined?" and "who references it?" precisely. What agents lack is a safe way to change Python structurally. Renaming a symbol used across thirty files by hand-editing text is slow and unreliable: the agent can't be sure it found every reference, can't prove a textual match is the same binding, and routinely leaves half-renamed code.
ropey closes that gap with one division of labour:
ty finds and reads; ropey changes.
The agent points at code using the exact line/character coordinates its
LSP already returned, and ropey performs the behaviour-preserving
transformation across the whole project: rename, move, extract, inline,
change signature, organise imports, and so on. One sibling tool, rewrite,
takes a pattern→goal transformation for structural changes none of the
refactorings express, addressed by a code template rather than a
coordinate (see the safety contract).
Related MCP server: MCP Refactoring
Behaviour is preserved, with one exception. Every refactoring
alters the structure of your code without changing what it does, and
rope proves each transformation safe before ropey writes it. rewrite
is the exception: it makes no behaviour-preservation claim. The agent
asserts that pattern and goal are equivalent, and the tool guarantees
only that it rewrites exactly the matches it reports. In exchange it
surfaces every Match Site (file + range, flagged matched or
unsure) for the agent to audit, leaves unprovable sites un-rewritten
unless explicitly opted in, and refuses any rewrite that would produce
unparsable Python. Both preview and apply mode enforce that refusal.
Dry Run by default. Every tool takes an apply flag. With
apply=false (the default) the full consequence is computed and reported
but nothing is written. apply=true performs the same change for real.
Both report identical detail.
The Blast Radius. Every result enumerates every affected file with
what happened to it: modified, created, moved (with its old path),
or deleted. The list is never truncated and never carries file
contents. After a live run, git diff shows the exact text.
Uncertain Occurrences. Python is dynamically typed, so sometimes rope
cannot prove that obj.save() refers to the method being renamed. ropey
applies only the certain occurrences and reports every uncertain one as a
flagged location for the agent to adjudicate. Nothing is silently included
or silently dropped.
Freshness is self-established. Before every refactoring the server
re-checks the source on disk, so edits from any writer are reflected,
whether they came from the agent, a human editor, git checkout, or a
formatter. Correctness never depends on the host announcing its edits.
git is the undo. ropey writes no cache artifacts into your repo
(no .ropeproject/), never edits gitignored files (git couldn't revert
them), and recommends a clean working tree before applying so git diff
/ git checkout are always a complete reversal mechanism.
Failures are structured. A refactoring that cannot proceed returns a
machine-readable reason ("the selection crosses a scope boundary", "the
file broken.py cannot be parsed") rather than a stack trace.
/plugin marketplace add andrewesweet/ropey
/plugin install ropey@ropeyThe plugin bundles the MCP server config; tools appear after a restart. Requires uv on your PATH.
Add to opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"ropey": {
"type": "local",
"command": [
"uvx", "--from", "git+https://github.com/andrewesweet/ropey", "ropey"
],
"enabled": true
}
}
}ropey is a standard stdio MCP server. Generic config:
{
"mcpServers": {
"ropey": {
"command": "uvx",
"args": ["--from", "git+https://github.com/andrewesweet/ropey", "ropey"]
}
}
}Or run it directly: uvx --from git+https://github.com/andrewesweet/ropey ropey
Tool | What it does |
| Rename a symbol everywhere, optionally in docstrings/comments and across a class hierarchy |
| Move a global, a method, or a whole module; imports updated project-wide |
| Convert a module file into a package |
| Extract a selection into a helper or a named value |
| Inline a method, variable, or parameter (kind auto-detected) |
| Add / remove / reorder parameters with every call site updated |
| Sort, dedupe, expand star-imports, relative→absolute |
| Turn a selected expression into a new parameter that defaults to it, with call sites updated |
| Wrap a class attribute behind getter/setter; reads and writes rewritten project-wide |
| Add a factory (static method or module function) for a class and route instantiations through it |
| Convert a method into a method object (a class whose |
| Promote a method-local variable to an instance field ( |
| Replace code that duplicates a function's body with calls to it, project-wide |
| Pattern→goal rewrite of every matching site ( |
Targets are addressed with LSP coordinates (0-based line/character, UTF-16
units), the same coordinates an LSP returns; byte offsets never appear.
Point refactorings accept an optional expected_symbol so a stale position
fails loudly instead of refactoring the wrong code. The exception is
rewrite, which is addressed by a pattern (Python source with
${wildcard} placeholders) instead of a coordinate, and reports its Match
Sites back as LSP ranges. ty finds and reads; ropey changes.
uv sync
uv run pytestDomain documentation lives in CONTEXT.md, the decision
records in docs/adr/, and the PRD in
docs/prd/. Operability notes and measured latency envelopes:
docs/operability.md.
Change a function or method signature — add, remove, or reorder parameters — updating every certain call site across the project. Point at the function name (0-based LSP line/character, UTF-16 units) and pass operations, a list applied in order: {action:'add', name, index?, default?, value?} (default is the parameter's default expression; value is what existing call sites should pass), {action:'remove', name or index}, {action:'reorder', order:[names or indices covering every parameter]}. For methods, parameter lists include self (index 0). across_class_hierarchy applies the change to matching overrides. Defaults to a Dry Run preview; set apply=true to write. Uncertain call sites are reported as uncertain_occurrences, never silently edited. Locate the function with your LSP first; this tool only changes code.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | ||
| line | Yes | ||
| root | No | ||
| apply | No | ||
| character | Yes | ||
| operations | Yes | ||
| expected_symbol | No | ||
| across_class_hierarchy | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral burden. It fully discloses the dry-run default, the apply=true switch, handling of uncertain call sites, and the across_class_hierarchy behavior. This is exceptional transparency, especially for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence adds necessary information: purpose, operation syntax, LSP coordinates, self handling, hierarchy support, dry-run behavior, and LSP prerequisite. There is no filler, and the structure flows logically from main action to details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multiple operations, optional parameters, LSP dependency), the description is remarkably complete. It covers all critical aspects for an agent to use it correctly, and the presence of an output schema means return-value details are not required in the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description compensates thoroughly for the core parameters: line/character units, operations structure with add/remove/reorder semantics, and default vs. value. It omits root and expected_symbol, which are auxiliary optional params, but the critical ones are well described.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's specific verb ('Change') and resource ('function or method signature'), and enumerates the operations (add, remove, reorder parameters). This distinguishes it from sibling tools like rename or move, which target different refactorings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context on how to invoke the tool, including LSP coordinates and the apply flag, and notes the tool only changes code (implying a preceding LSP lookup). It does not explicitly name alternative tools for when not to use it, but the operations are specific enough to imply applicability.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Encapsulate a class attribute behind getter/setter methods, rewriting reads to the getter and writes to the setter across the project. Point at the attribute name (0-based LSP line/character, UTF-16 units), exactly as your LSP returns it. getter_name and setter_name override the default get_/set_ names. Defaults to a Dry Run preview; set apply=true to write. Accesses that cannot be proven to be this attribute are reported as uncertain_occurrences, never silently rewritten. Supply expected_symbol when edits may have intervened since your LSP answer. Locate the attribute with your LSP first; this tool only changes code.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | ||
| line | Yes | ||
| root | No | ||
| apply | No | ||
| character | Yes | ||
| getter_name | No | ||
| setter_name | No | ||
| expected_symbol | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses key behaviors: defaults to Dry Run, apply=true writes, uncertain accesses are reported as 'uncertain_occurrences' and never silently rewritten, and expected_symbol handles stale LSP answers. It also states the tool only changes code, setting accurate expectations for project-wide effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise yet dense, with each sentence serving a purpose. It front-loads the primary function and then explains parameters, safety defaults, and usage prerequisites without irrelevant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 params, project-wide rewrites, LSP dependency, dry-run default), the description covers what the tool does, how to invoke it, what to expect (uncertain occurrences), and when to supply extra params. The output schema handles return details, so no further elaboration is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must explain parameters. It explains file/line/character as LSP coordinates (0-based, UTF-16), getter_name/setter_name overrides, apply=true, and expected_symbol. This adds substantial meaning beyond the bare schema, covering all essential params except root, which is inferable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies a clear action: 'Encapsulate a class attribute behind getter/setter methods, rewriting reads to the getter and writes to the setter across the project.' This distinguishes it from sibling refactoring tools like rename or move, and includes the target resource (class attribute) and the specific transformation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear usage context: point at the attribute name with LSP coordinates, defaults to dry run, apply=true to write, and 'Locate the attribute with your LSP first; this tool only changes code.' It does not explicitly mention alternatives or exclusions versus siblings, but the context is clear enough for appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract a selected block of statements (or an expression) into a new method or function, with parameters and return values inferred from the data flow. Pass the file and the selection Range — start_line/start_character to end_line/end_character, 0-based, character in UTF-16 units, exactly as an editor selection. The selection must be complete statements or one complete expression. Options: replace_similar replaces other occurrences of the same pattern; to_global_scope extracts to module level; method_kind makes a classmethod or staticmethod. Defaults to a Dry Run preview; set apply=true to write. Read the code with your LSP first; leave formatting to black/ruff.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | ||
| name | Yes | ||
| root | No | ||
| apply | No | ||
| end_line | Yes | ||
| start_line | Yes | ||
| method_kind | No | ||
| end_character | Yes | ||
| replace_similar | No | ||
| start_character | Yes | ||
| to_global_scope | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of disclosing behavior. It does so well by stating the dry-run default, the apply flag to actually write, that parameters/returns are inferred from data flow, and that formatting is left to black/ruff. It does not cover failure modes or side effects, but the safety-critical dry-run behavior is clearly conveyed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is information-dense and front-loaded with the core purpose. Each sentence adds new valuable information, from the selection requirements to the options to the dry-run default. There is no redundant or vague phrasing, and the structure flows logically from what the tool does to how to invoke it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (11 parameters, no annotations) and the presence of an output schema, the description covers the essential aspects: purpose, selection semantics, options, and the safety default. It does not delve into error cases or exact return behavior, but those are partly covered by the output schema. Overall, it is quite complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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. It explains the range parameters (0-based, UTF-16 units), the options (replace_similar, to_global_scope, method_kind), and the apply flag. However, it does not mention the required 'name' parameter or the optional 'root' parameter, which are left unexplained. Still, the majority of parameters are semantically clarified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Extract a selected block of statements (or an expression) into a new method or function'. It distinguishes itself from sibling tools like extract_variable by emphasizing method/function extraction and complete statements/expressions. The mention of inferred parameters and return values adds specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context on how to use the tool, including the exact range format, the requirement for complete statements or one expression, and the dry-run/apply flow. It also gives advice to read code with LSP first and leave formatting to black/ruff. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls 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.
Extract a selected expression into a named variable, replacing the expression with the name. Pass the file and the selection Range (start_line/start_character to end_line/end_character, 0-based, UTF-16 units) covering exactly one expression. replace_similar also substitutes other occurrences of the same expression; to_global_scope creates the variable at module level. Defaults to a Dry Run preview; set apply=true to write. Read the code with your LSP first; leave formatting to black/ruff.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | ||
| name | Yes | ||
| root | No | ||
| apply | No | ||
| end_line | Yes | ||
| start_line | Yes | ||
| end_character | Yes | ||
| replace_similar | No | ||
| start_character | Yes | ||
| to_global_scope | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden. It discloses defaults ('Defaults to a Dry Run preview; set apply=true to write'), side effects of flags ('replace_similar... to_global_scope...'), and dependencies ('Read the code with your LSP first; leave formatting to black/ruff'). This is excellent behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action, then efficiently packs parameter semantics and usage guidance. No filler; every clause adds valuable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 10 parameters, the description covers the core behavior, defaults, preconditions, and external dependencies. With an output schema present, not explaining return values is acceptable. The description is sufficiently complete for a complex refactoring tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description explains the meaning of all key parameters: the Range coordinates (0-based, UTF-16 units), name, apply, replace_similar, to_global_scope. It adds essential semantics to raw schema fields and even specifies the units for line/character offsets.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Extract') and resource ('selected expression into a named variable'), clearly distinguishing this from sibling tools like extract_method or introduce_parameter. It states the action and effect in the first sentence.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: 'Pass the file and the selection Range... covering exactly one expression' and 'Read the code with your LSP first; leave formatting to black/ruff.' It does not explicitly list alternative tools or when not to use it, but the conditions are implied. A 4 is appropriate for clear context without explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inline the method, variable, or parameter at a Position — the server detects which kind, so just point at the name (0-based LSP line/character, UTF-16 units). Methods and variables: every certain use is replaced by the body or value; remove_definition=false keeps the definition; only_current_occurrence=true inlines just the occurrence at the Position. Parameters: the default value is written into call sites that omit it. Defaults to a Dry Run preview; set apply=true to write. Supply expected_symbol when edits may have intervened since your LSP answer, so a stale Position fails safely instead of inlining the wrong thing. Locate the definition with your LSP first; this tool only changes code.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | ||
| line | Yes | ||
| root | No | ||
| apply | No | ||
| character | Yes | ||
| expected_symbol | No | ||
| remove_definition | No | ||
| only_current_occurrence | No | ||
| in_docstrings_and_comments | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: dry-run default, apply semantics, remove_definition behavior, only_current_occurrence, parameter inlining (default value written into call sites), and expected_symbol as a safety mechanism. This exceeds typical transparency and leaves little ambiguity about the tool's effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph, but every sentence earns its place—covering core purpose, per-kind behavior, dry-run/apply, safety, and a closing instruction. It is somewhat long but not wasteful; slight structure improvement (e.g., bullets) would make it a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex refactoring tool with 9 parameters and no annotations, the description covers all major behavioral aspects: dry-run vs. apply, handling of methods/variables vs. parameters, safety with expected_symbol, and the LSP workflow. With an output schema present, return-value details can reside there, so this description is highly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must explain parameters. It explains line/character coordinate format (0-based LSP, UTF-16), apply, remove_definition, only_current_occurrence, and expected_symbol. However, it omits root and in_docstrings_and_comments, leaving those less clear. Given the high parameter count, this is a solid but not perfect compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Inline the method, variable, or parameter at a Position'. It names the specific verb (inline), the resource types, and the positional targeting, distinguishing it from siblings like rename, move, and extract_method.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides concrete usage context: 'Defaults to a Dry Run preview; set apply=true to write' and the prerequisite 'Locate the definition with your LSP first; this tool only changes code.' It also advises using expected_symbol for stale positions, which is a clear when-to-use guideline. It doesn't explicitly discuss when not to use the tool or name alternatives, so it's a 4 rather than a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Introduce a factory for a class and route instantiations through it. Point at the class name (0-based LSP line/character, UTF-16 units). By default the factory is a static method named factory_name on the class; global_factory=true creates a module-level function instead. Existing constructor calls across the project are rewritten to the factory. Defaults to a Dry Run preview; set apply=true to write. Supply expected_symbol when edits may have intervened since your LSP answer, so a stale Position fails safely. Locate the class with your LSP first; this tool only changes code.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | ||
| line | Yes | ||
| root | No | ||
| apply | No | ||
| character | Yes | ||
| factory_name | Yes | ||
| global_factory | No | ||
| expected_symbol | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses key behaviors: 'Existing constructor calls across the project are rewritten to the factory' (a side effect), the default Dry Run mode, the use of apply to write, and the fail-safe behavior of expected_symbol. It also clarifies the tool's scope ('this tool only changes code'), making side effects transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four dense sentences, front-loaded with the core purpose. Every sentence provides essential information: the action, location semantics, default vs. global factory behavior, dry-run/apply, expected_symbol safety, and the prerequisite LSP step. There is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, project-wide effects), the description covers prerequisites, safety, side effects, and parameter nuances. The presence of an output schema makes it unnecessary to describe return values. The note to locate the class with LSP first is critical contextual guidance. Overall, it is a complete and robust description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning beyond the schema for most parameters: it explains factory_name ('static method named factory_name'), global_factory ('creates a module-level function instead'), apply ('set apply=true to write'), and expected_symbol ('so a stale Position fails safely'). It also explains line/character positioning. However, it does not explicitly mention the 'file' parameter or the optional 'root' parameter, leaving a minor gap for a required input.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Introduce a factory for a class and route instantiations through it.' It also specifies the target ('Point at the class name') and the project-wide effect ('Existing constructor calls across the project are rewritten to the factory.'). The verb+resource+scope is specific and distinguishes this from sibling refactoring tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: 'Locate the class with your LSP first; this tool only changes code.' It also explains how to control behavior: 'Defaults to a Dry Run preview; set apply=true to write' and when to supply optional parameters: 'Supply expected_symbol when edits may have intervened since your LSP answer.' This is clear operational context with no ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Turn a value used inside a function into a new parameter, with the original expression becoming the parameter's default. Select the expression — a name or attribute access such as a module constant or self. — with a Range (start_line/start_character to end_line/end_character, 0-based, character in UTF-16 units) inside the function body and give the parameter a name. Defaults to a Dry Run preview; set apply=true to write. Read the code with your LSP first; this tool only changes code.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | ||
| root | No | ||
| apply | No | ||
| end_line | Yes | ||
| start_line | Yes | ||
| end_character | Yes | ||
| parameter_name | Yes | ||
| start_character | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description properly discloses the key behavioral traits: it defaults to a Dry Run preview, requires apply=true to write changes, and states 'this tool only changes code' after reading with LSP. This is valuable side-effect and prerequisite information that goes well beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences but every sentence adds essential value: the transformation, the selection syntax, the dry-run/apply behavior, and the LSP prerequisite. It is dense with no filler and front-loads the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex 8-parameter refactoring tool with no annotations and no schema descriptions, this description is unusually complete. It covers purpose, selection criteria, range semantics, apply behavior, and the important prerequisite to read code with LSP. The presence of an output schema means return values need not be described, and the only minor omission (root) is optional and likely inferable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It explains the Range parameters in detail (0-based, UTF-16 units), the parameter_name, and the apply flag. It does not mention the optional root parameter at all, but the core parameters are well covered and the file is implied via the LSP instruction.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the core transformation: turning a value inside a function into a new parameter, with the original expression becoming the default. It specifies the verb ('Turn'), the resource (a value inside a function), and the result (new parameter), which distinguishes it from sibling refactorings like extract_variable or change_signature by its mechanism and outcome.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete when/how: select an expression inside the function body, provide a parameter name, and use LSP first. It also explains the dry-run vs apply workflow. However, it does not explicitly mention when not to use this tool or compare it to alternatives such as change_signature, so the guidance is clear but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Promote a local variable inside a method to an instance field: the local becomes self. everywhere in the class. Point at the local variable's name (0-based LSP line/character, UTF-16 units). Defaults to a Dry Run preview; set apply=true to write. Supply expected_symbol when edits may have intervened since your LSP answer, so a stale Position fails safely. Locate the variable with your LSP first; this tool only changes code.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | ||
| line | Yes | ||
| root | No | ||
| apply | No | ||
| character | Yes | ||
| expected_symbol | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so thoroughly: it discloses dry-run vs apply behavior, 0-based LSP line/character coordinates in UTF-16 units, the expected_symbol safety mechanism for stale positions, and the class-wide scope of the change. This is rich, actionable behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no filler. It front-loads the purpose and then adds necessary technical and safety details in a tightly structured manner.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no schema descriptions, the description is complete enough for correct use: it explains the operation, coordinate system, dry-run preview, apply behavior, stale-position safety, and the LSP prerequisite. The presence of an output schema makes omission of return-value details acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates for the key parameters: line/character coordinates, apply, and expected_symbol. It does not clarify the 'root' parameter, which is a minor gap, but the most important invocation details are well explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it promotes a local variable inside a method to an instance field, transforming the local into self.<name> everywhere in the class. This specific verb+resource combination distinguishes it from siblings like extract_variable or introduce_parameter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear workflow context: locate the variable with LSP first, use dry-run preview by default, and set apply=true to write. However, it does not explicitly name alternative tools or state when not to use this tool, so exclusion guidance is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert a method into a method object: a new class whose call holds the method body, with the original method delegating to it — a stepping stone for decomposing a complex method. Point at the method name (0-based LSP line/character, UTF-16 units) and name the new class. Defaults to a Dry Run preview; set apply=true to write. Supply expected_symbol when edits may have intervened since your LSP answer, so a stale Position fails safely. Read the method with your LSP first; this tool only changes code.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | ||
| line | Yes | ||
| root | No | ||
| apply | No | ||
| character | Yes | ||
| class_name | Yes | ||
| expected_symbol | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries full burden. It discloses multiple behavioral traits: dry run default vs. apply=true, the fail-safe behavior when expected_symbol is supplied, and the explicit statement that this tool only changes code (not reads). This goes beyond basic safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences deliver all essential information without fluff. The opening sentence defines the operation, the second gives positional details, and the third covers dry-run/apply, expected_symbol, and prerequisite. Well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the description covers purpose, usage, behavior, and parameter semantics comprehensively. An output schema exists to clarify return values, so no further explanation is needed. Minor gaps like root are negligible.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates well by explaining line/character as 0-based LSP positions in UTF-16 units, apply defaulting to false, and expected_symbol for stale positions. However, the root parameter is not mentioned and its meaning remains unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool converts a method into a method object, specifically a new class with a __call__ holding the method body and the original method delegating to it. This specific verb+resource+pattern distinguishes it from siblings like extract_method or inline.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear usage context: it's a stepping stone for decomposing a complex method, defaults to a dry run, and instructs to set apply=true to write. Also advises reading the method with LSP first. While it doesn't explicitly name alternative tools, the guidance is sufficient for an agent to choose appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert a Python module file into a package: creates a directory of the module's name and moves the module to its init.py, rewriting relative imports to absolute. Pass the module's file path alone; no Position needed. Defaults to a Dry Run preview (created and moved entries appear in the Blast Radius); set apply=true to write. Use your LSP for navigation and reading; this tool only restructures.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | ||
| root | No | ||
| apply | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses the steps (creates directory, moves module, rewrites imports), the dry-run default, and the apply flag to write. It also clarifies the tool's scope ('only restructures'), preventing misuse. No annotation contradictions exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four concise sentences, each with a clear informational role: purpose/mechanism, parameter guidance, dry-run behavior, and scope limitation. Every sentence earns its place with no repetition or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for the core use case: it explains what the tool does, how to invoke it, and its safety default (dry run). The output schema exists, so return values are not needed. However, it omits edge cases such as handling conflicts (e.g., directory already exists) and does not explain the 'Blast Radius' term, nor the 'root' parameter's role, leaving minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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. It explains 'file' (pass the file path alone) and 'apply' (set apply=true to write), but says nothing about the optional 'root' parameter. While root is optional with a default, its purpose remains ambiguous, leaving one of three parameters semantically unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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: 'Convert a Python module file into a package,' followed by a clear mechanism (creates directory, moves module to __init__.py, rewrites relative imports). This clearly differentiates it from sibling refactoring tools like move or rename.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'Pass the module's file path alone; no Position needed' distinguishes it from tools requiring positional arguments. It also states 'Use your LSP for navigation and reading; this tool only restructures,' which is an explicit when-not-to-use. The dry-run default and apply=true instruction further clarify how to execute the operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move a Python symbol or module and update imports project-wide. Three targets, one tool: a global function/class/variable at a Position moves to another module (pass destination: that module's file path); a method at a Position moves to the class held by an attribute of self (pass destination_attribute, and optionally new_name); a whole module or package moves into a package when you omit line/character entirely (pass destination: the package directory). Coordinates are 0-based LSP line/character (UTF-16 units), exactly as your LSP returns them — locate the symbol with the LSP first. Defaults to a Dry Run preview; set apply=true to write. Prefer a clean git tree before applying, since git is the reversal mechanism. Moved resources report old_path; new files report created.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | ||
| line | No | ||
| root | No | ||
| apply | No | ||
| new_name | No | ||
| character | No | ||
| destination | No | ||
| expected_symbol | No | ||
| destination_attribute | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description takes full responsibility for disclosing behavior. It reveals that the tool defaults to a dry-run preview, requires apply=true to write, uses git as the reversal mechanism, and reports moved resources as old_path and new files as created. It also explains the coordinate system (0-based LSP line/character in UTF-16). This is far beyond what most tool descriptions provide and gives the agent a clear model of side effects and safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence carries distinct, necessary information: purpose, three usage modes, coordinate details, dry-run behavior, and output reporting. It is front-loaded with the main purpose and follows a logical, structured flow. No filler or redundant phrasing; it earns its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 9 parameters, three modes, and no annotations, the description delivers a robust operational picture. It explains the coordinate system, destination selection, dry-run/apply semantics, and output behavior. The gaps are the unexplained expected_symbol and root parameters, which could cause misconfiguration, but the overall usage is well covered. The existence of an output schema partially mitigates the need to describe return values, so a 4 is appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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. It does so admirably for most parameters: destination, destination_attribute, new_name, line, character, and apply are all semantically explained via the three scenarios. However, expected_symbol and root are left unexplained, and file is only implied. Given the complexity, this is a strong but not complete compensation, so a 4 is fitting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific, unambiguous statement: 'Move a Python symbol or module and update imports project-wide.' It then enumerates three distinct targets (global symbol, method, module/package), distinguishing this tool from siblings like rename or extract_method. The verb 'move' plus the resource types and the import-update behavior make the purpose crystal clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance for all three modes: pass destination for global symbols, destination_attribute for methods, and omit line/character for module moves. It also advises using an LSP to locate the symbol first and to ensure a clean git tree before applying. However, it does not explicitly mention alternatives or when not to use this tool (e.g., 'use rename for simple renames'), so it stops short of the full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tidy a module's import block structurally (not formatting — black/ruff own that). Pass the file alone; no Position. One mode per call: 'organize' (default) sorts, deduplicates, and drops unused imports; 'expand_star_imports' replaces from m import * with explicit names (follow with 'organize' to prune unused ones); 'relatives_to_absolutes' rewrites relative imports as absolute; 'froms_to_imports' converts from-imports to plain imports; 'handle_long_imports' shortens deep module paths. Defaults to a Dry Run preview; set apply=true to write. An empty blast_radius means the module already conforms.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | ||
| mode | No | organize | |
| root | No | ||
| apply | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden and does so thoroughly: it discloses the dry-run default, the apply=true write behavior, the meaning of an empty blast_radius, and per-mode effects including destructive actions like 'drops unused imports'. This is strong transparency for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Five sentences pack a wealth of information with no fluff. It front-loads the primary purpose, then clearly enumerates modes, defaults, and result interpretation. The structure is logical and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a multi-mode refactoring tool, the description covers purpose, usage constraints, mode behaviors, and result semantics. The presence of an output schema removes the need to describe return values. The only notable gap is the undocumented 'root' parameter, which prevents a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description adds rich semantics for the 'mode' parameter (explaining all possible values in detail) and for 'apply' (default false = dry run). It also implies 'file' is the only required argument. However, the optional 'root' parameter is never explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource pair ('Tidy a module's import block') and further distinguishes itself from sibling refactoring tools by clearly focusing on import organization rather than general code restructuring. It also explicitly excludes formatting, clarifying the tool's exact scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides concrete usage constraints: 'Pass the file alone; no Position' and 'One mode per call'. It also gives sequential guidance for expand_star_imports ('follow with organize'). The exclusion of formatting ('black/ruff own that') is an explicit when-not, though it doesn't name alternative sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rename a Python symbol (function, class, method, variable, module-level name) and update every reference across the project — a binding-aware alternative to find-and-replace. Use your LSP to locate the symbol first; pass its file and 0-based line/character Position (character in UTF-16 units, exactly as the LSP returns). Defaults to a Dry Run that previews the full Blast Radius without writing; set apply=true to write. Supply expected_symbol (the identifier you believe is at the Position) when edits may have happened since your LSP answer — a mismatch fails safely instead of renaming the wrong code. Prefer a clean git working tree before applying, since git is the reversal mechanism; use git diff afterwards for exact text. Occurrences that cannot be proven to refer to this symbol are reported as uncertain_occurrences for you to adjudicate, never silently changed. Keep navigation and reading with your LSP, and formatting with black/ruff — this tool only changes code structure.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | ||
| line | Yes | ||
| root | No | ||
| apply | No | ||
| new_name | Yes | ||
| character | Yes | ||
| expected_symbol | No | ||
| across_class_hierarchy | No | ||
| in_docstrings_and_comments | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses the dry-run default, the apply flag for side effects, the expected_symbol safety check, git as reversal mechanism, and that uncertain occurrences are reported rather than silently changed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph but front-loaded with the core action. Every sentence adds operational value, and it avoids redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and lack of annotations, the description provides thorough coverage: how to locate the symbol, dry-run behavior, when to supply expected_symbol, git considerations, and how uncertain occurrences are handled. It also clarifies scope relative to other tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It explains file, line/character Position (0-based UTF-16), apply, and expected_symbol in meaningful detail. However, across_class_hierarchy and in_docstrings_and_comments are not mentioned, leaving some parameters under-specified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States 'Rename a Python symbol... and update every reference across the project' — a specific verb+resource that clearly distinguishes from siblings like move or rewrite. The 'binding-aware alternative to find-and-replace' further clarifies its unique role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to use LSP first, and specifies that navigation, reading, and formatting should be done with other tools (LSP, black/ruff), while this tool only changes code structure. Also advises on when to use dry run and clean git tree, giving clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rewrite every site matching a structural Pattern into a Goal, project-wide — for transformations no dedicated refactoring expresses, such as migrating a deprecated call form (${obj}.get_attribute(${key}) -> ${obj}[${key}]) or collapsing an idiom. The Pattern is Python source with ${wildcard} placeholders; the Goal is the replacement template reusing those Wildcards. Prefer a dedicated behaviour-preserving tool (rename, inline, change_signature, move, use_function) whenever one fits; use rewrite only when none does, because a Rewrite is not behaviour-preserving: you assert that Pattern and Goal are equivalent, and the tool guarantees only that it rewrites exactly the Match Sites it reports. Control over-matching with per-Wildcard Match Constraints, e.g. constraints={"obj": {"type": "myapp.models.User"}}: name / type / object / instance narrow by a symbol's dotted path (one per Wildcard), and exact: true narrows to the Wildcard's literal name. type matches instances of exactly that class; instance matches instances of its subclasses (not the base class's own) — to cover a class and its subclasses, run once with each. A constrained run reports only the sites the constraint engages (matched or unsure), not every textual match. Each Match Site reports its certainty: matched (constraints satisfied) or unsure (a constraint that cannot be established at that site, common in dynamically typed code). Unsure sites are surfaced but not rewritten, so nothing is silently skipped; add unsure: true to a Wildcard's constraints to rewrite them too — they stay flagged unsure in the result for you to audit. When the Goal introduces a name the target modules do not import, pass imports (a list of import statements, added to each changed module, deduplicated); the tool never infers imports — checking for missing names is your LSP's job, so an omitted import leaves broken code. A rewrite that would produce unparsable Python fails safely in either mode, naming the file and parse location, with nothing written. Defaults to a Dry Run that previews without writing; review every Match Site for over-matching before setting apply=true. A truncated Match Site list ('showing N of M', unsure sites first) means the audit is incomplete — tighten the Pattern or Match Constraints and preview again before a Live Run. Both modes report the file-level Blast Radius and every Match Site (file + Range in 0-based UTF-16 LSP coordinates, against the pre-apply text — live targets for your LSP on a Dry Run, audit records after a Live Run). Start from a clean git tree, since git is the reversal mechanism, and run git diff after a Live Run to verify the equivalence you asserted. Pass root (the project directory) explicitly. Keep navigation and reading with your LSP; this tool only changes code.
| Name | Required | Description | Default |
|---|---|---|---|
| goal | Yes | ||
| root | No | ||
| apply | No | ||
| imports | No | ||
| pattern | Yes | ||
| constraints | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses the tool's non-behaviour-preserving nature, its dry-run default, handling of unsure match sites, safe failure on unparsable output, import behavior, and reliance on git for reversal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Although long, each sentence delivers unique operational knowledge—from matching semantics to failure behavior—without repetition. The structure logically moves from purpose to usage to parameter details to safety, justifying its length for a complex tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the full lifecycle: selection, pattern/goal authoring, constraint control, dry-run preview, apply mode, output interpretation (blast radius, match sites, certainty), and post-run verification via git. It even explains truncated output and the need for a clean git tree, leaving no critical gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only titles and types (0% description coverage), but the description explains pattern and goal templates, details constraint keys with exact/type/instance semantics, defines imports, apply, and root, adding meaning to every parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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: 'Rewrite every site matching a structural Pattern into a Goal, project-wide', and gives concrete examples (get_attribute -> subscript). It explicitly distinguishes itself from dedicated refactoring tools by noting it is for transformations no dedicated refactoring expresses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly instructs 'Prefer a dedicated behaviour-preserving tool... whenever one fits; use rewrite only when none does', naming sibling tools. It also provides a workflow: dry-run, review match sites, set apply=true, and run git diff.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace code that duplicates a function's body with calls to that function, across the whole project. Point at the name of a module-level function (0-based LSP line/character, UTF-16 units); statements matching its body pattern are rewritten into calls. Defaults to a Dry Run preview; set apply=true to write. Sites that cannot be proven to match are reported as uncertain_occurrences for you to adjudicate, never silently rewritten. Supply expected_symbol when edits may have intervened since your LSP answer, so a stale Position fails safely. Locate the function with your LSP first; this tool only changes code.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | ||
| line | Yes | ||
| root | No | ||
| apply | No | ||
| character | Yes | ||
| expected_symbol | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility. It discloses the dry-run default, apply flag, project-wide scope, uncertain occurrence reporting, safe failure on stale positions, and the guarantee that sites are never silently rewritten. This is comprehensive behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a dense paragraph of six sentences, each adding meaningful details without redundancy. It is front-loaded with the core purpose and then explains safety mechanisms. Slightly long but appropriate for a complex tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 6 parameters and an output schema, the description covers the essential workflow, safety guarantees, and invocation details. The only minor omission is the 'root' parameter, but overall it is complete enough for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the positional parameters (0-based LSP line/character, UTF-16 units), the apply flag, and expected_symbol's purpose. It does not explicitly describe 'root', leaving a small gap, but given 0% schema description coverage, it compensates well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool replaces duplicated function bodies with calls to that function across the project. It explicitly names the action and resource, and the closing 'this tool only changes code' distinguishes it from sibling refactoring tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use it (deduplication of matching code) and outlines the workflow: locate the function with LSP, point at it, dry run by default, apply to write. It does not explicitly list alternatives or when-not cases, but the context is sufficiently clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.2.0change_signatureencapsulate_fieldextract_methodextract_variableinlineintroduce_factoryintroduce_parameterlocal_to_fieldmethod_objectmodule_to_packagemoveorganize_importsrenamerewriteuse_functionEach tool targets a distinct refactoring operation (rename, move, extract, inline, signature changes, etc.). Even potentially overlapping tools like rewrite and extract_method are clearly differentiated by their descriptions and explicit guidance on when to use the dedicated tool.
All names use snake_case and are generally descriptive, but there's a mix of grammatical patterns: single verbs (rename, move), verb-noun (extract_method, change_signature), and noun-based phrases (method_object, local_to_field). This is mostly consistent with a refactoring domain, though a more uniform verb-first pattern would be slightly clearer.
15 tools is within the desirable range for a specialized refactoring server. Each tool covers a well-known Python refactoring, and none feel redundant or unnecessary. The set is neither too thin nor bloated.
The server covers a broad spectrum of common refactorings, including structural changes (move, module_to_package), local transformations (extract_variable, local_to_field), and signature/class operations. Some advanced refactorings like 'pull up' or 'extract class' are absent, but the core workflows are well represented, and the rewrite tool provides a fallback for custom transformations.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Production-readiness for your AI coding agents.
Ask a codebase what calls what: search, blast radius, paths between symbols, and diffs.
Cross-agent artifact workspace with provenance across Claude Code, Codex, Cursor, LangGraph.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/andrewesweet/ropey'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
