Decomposes monolithic JavaScript source files into clean modules using mechanical extraction with deterministic function boundary detection, automatic import resolution, and syntax validation.
Decomposes Kotlin source files into modules using mechanical extraction with function boundary detection and import resolution (available in Pro tier).
Decomposes Python monoliths into clean modules using mechanical extraction with automatic function boundary detection, import resolution, and syntax validation.
Decomposes Rust source files into modules using mechanical extraction with deterministic parsing and import resolution (available in Pro tier).
Decomposes Swift source files into modules using mechanical extraction with function boundary detection and import resolution (available in Pro tier).
Decomposes TypeScript source files into modular components using mechanical extraction while preserving type annotations, with automatic import resolution and deterministic parsing.
Hybrid code decomposition. AI plans the boundaries. A deterministic engine handles the routine extractions. Minimize tokens, maximize syntax validity.
Refactory splits monolith source files into clean modules. It uses an LLM for one thing — deciding which functions group together. Everything else is mechanical: function boundary detection, import resolution, module assembly, syntax validation, scoring.
JavaScript and Python extraction is mostly mechanical. The deterministic engine handles the straightforward moves — the routine 80% that's a waste of AI time and tokens. The LLM still handles complex edge cases where judgment matters. Other languages use LLM extraction with adaptive compression.
Works with Claude Code, Cursor, Windsurf, VS Code Copilot — any MCP client. Or use the CLI directly.
Tested against 15 production monoliths:
Metric | Value |
Lines decomposed | 32,736 |
Functions extracted | 1,017 |
Pipeline score | 0.89 |
Mechanical extraction ratio | ~80% |
API cost (extraction) | Near zero |
Related MCP server: sourcebook
Add to your .mcp.json:
{
"mcpServers": {
"refactory": {
"command": "npx",
"args": ["@refactory/mcp"],
"env": {
"GROQ_API_KEY": "your-key-here"
}
}
}
}Then tell your AI tool: "Analyze and decompose src/big-file.js into modules"
One free API key (Groq or Gemini) is needed for the PLAN step only. Extraction is mechanical — no key required for JS/Python.
git clone https://github.com/codedrop-codes/refactory.git
cd refactory && npm install
node src/cli.js decompose src/big-file.jsOther commands:
refactory analyze src/big-file.js # Health check + function map
refactory plan src/big-file.js # Generate module boundaries (needs LLM key)
refactory verify lib/modules/ # Check extracted modules
refactory languages # Show supported languages
refactory providers # Show configured LLM providers
refactory test submit broken.js # Submit a file that breaks extraction
refactory test run # Validate preprocessors against test corpus 1. ANALYZE Scan functions, dependencies, health — mechanical
|
2. CHARACTERIZE Snapshot exports before touching anything — mechanical
|
3. PLAN LLM decides module boundaries — the only AI step
|
4. EXTRACT Copy functions by line range, resolve imports — mechanical
| (LLM fallback for unsupported languages)
5. FIX-IMPORTS Rewrite require()/import paths — mechanical
|
6. VERIFY Syntax check, load check, export comparison — mechanical
|
7. METRICS Refactory Score + HTML report — mechanical6 of 7 steps are deterministic. The LLM only decides where to split — it never touches your code.
Language | Extraction | Status |
JavaScript / TypeScript | Mechanical | Built in |
Python | Mechanical | Built in |
Go, Rust, Java, C#, Kotlin, Swift | Mechanical | |
Everything else | LLM with compression | Automatic fallback |
Mechanical extraction handles the routine cases: the preprocessor finds function boundaries by parsing, copies them by line range, and resolves imports deterministically. Complex patterns (dynamic exports, deeply interleaved logic) still go through the LLM.
Contribute a preprocessor for your language.
A single number (0.0 to 1.0) that measures decomposition quality.
Score = clean_rate × size_reductionclean_rate — modules that load without errors / total modules
size_reduction — 1 − (largest module / original file)
A score of 1.0 means every module loads cleanly and no module is bigger than the original.
You only need one free key for the PLAN step. Extraction is mechanical for supported languages.
Provider | Output | Context | Free? |
Groq Llama 3.3 70B | 32k | 128k | Yes |
Gemini 2.5 Flash | 16k | 1M | Yes |
OpenRouter Qwen 3.6+ | 16k | 1M | Yes |
SambaNova MiniMax | 16k | 163k | Yes |
Set at least one: GROQ_API_KEY, GOOGLE_API_KEY, OPENROUTER_API_KEY, or SAMBANOVA_API_KEY.
Found a file that breaks extraction? Submit it:
refactory test submit broken-file.js -d "what went wrong"Secrets are stripped automatically. Every submission becomes a permanent test case. The extractor gets stronger with every report.
Report via GitHub if you prefer.
Discord — Help, ideas, show your results
Discussions — Feature requests, language requests
Issues — Bug reports
Contributing — Build a preprocessor, submit test files
AGPL-3.0 — see LICENSE.
Premium language packs available under commercial license. See refactory.codedrop.codes.
Analyze a source file for decomposition. Returns health score, function count, dependency graph, and recommended split points.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Path to the monolith file to analyze | |
| language | No | Language (js, ts, py). Auto-detected if omitted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It fails to disclose behavioral traits like whether the tool modifies files (likely read-only) or requires specific permissions. It only lists return values, not side effects or constraints.
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 sentence with no wasted words. It front-loads the action ('Analyze a source file for decomposition') and lists outputs. However, it could be better structured (e.g., bullet points) for clarity when multiple outputs are mentioned.
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 (returns multiple structured items) and lack of output schema, the description is somewhat incomplete. It lists outputs but does not explain what 'health score' or 'recommended split points' mean. It meets minimal viability but leaves 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?
The input schema covers both parameters with descriptions (100% coverage). The description adds value by noting that language is auto-detected if omitted, which is not in the schema. This helps the agent understand optional parameter behavior.
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 analyzes a source file for decomposition and lists the specific outputs (health score, function count, etc.). It distinguishes from siblings like refactory_decompose (which likely performs the decomposition) and refactory_depmap (which focuses on dependency maps). However, it could be more explicit about how it differs from refactory_characterize.
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 no guidance on when to use this tool versus alternatives. It does not mention prerequisites, context, or exclusions. For an analysis tool among many siblings, usage guidelines are necessary but missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate characterization tests and golden export snapshot BEFORE decomposition. Captures behavioral contract.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Path to the module to characterize | |
| outputDir | No | Where to write test + golden files |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It fails to mention side effects (e.g., file creation), required permissions, or error handling, leaving significant gaps.
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?
Two sentences, no wasted words, front-loaded with action. Highly concise and direct.
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?
With no output schema, the description omits what the tool returns (e.g., success indicator, file paths). While purpose is clear, behavioral details are insufficient for complete understanding.
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?
Input schema coverage is 100%, and both parameters have descriptions. The tool description adds no meaningful detail beyond what the schema already provides, so baseline 3 is appropriate.
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 generates characterization tests and golden export snapshots before decomposition, using specific verbs and resources. It distinguishes itself from siblings like refactory_analyze and refactory_decompose.
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 explicitly says 'BEFORE decomposition', providing clear timing context. However, it does not mention when not to use or list alternative tools, missing some guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full decomposition pipeline in one call: analyze, depmap, characterize, plan, extract ALL modules, fix-imports, verify, metrics, re-export, report. The 'just do it' tool.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Path to the monolith file to decompose | |
| outputDir | No | Output directory (default: <dir>/lib/<basename>/ next to source) | |
| maxLines | No | Max lines per module (default: 500) | |
| projectDir | No | Project root for dependency mapping (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description lists the pipeline steps, giving an overview of what it does, but it does not disclose behavioral traits such as side effects (e.g., file modifications), authentication needs, or error handling. With no annotations, the description carries the full burden but only provides a high-level process list.
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?
Two sentences with no fluff. The first sentence front-loads the purpose and steps; the second reinforces the simplicity. Every word 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?
Given the complexity of a 10-step pipeline and no output schema, the description is concise but lacks details on what each step does, error handling, or expected output. It is adequate for a 'just do it' tool but not fully 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 100% with descriptions for all four parameters. The description adds no extra meaning beyond the schema, such as usage notes or constraints. Baseline 3 is appropriate.
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 is a 'full decomposition pipeline in one call' and lists all steps involved (analyze, depmap, etc.), distinguishing it from individual sibling tools like refactory_analyze or refactory_extract.
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 phrase 'The just do it tool' implies it is for running the entire pipeline at once, but it does not explicitly state when to use it versus running individual steps, nor does it mention prerequisites or exclusions. Usage guidance is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Map dependencies for a file — who requires it (consumers), what it requires (dependencies), detect circular deps.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Path to the file to map | |
| projectDir | No | Project root directory |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description adds 'detect circular deps' as a behavioral trait. However, it does not disclose side effects, permissions, or limitations. For a read-only mapping tool, it provides moderate transparency.
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, concise sentence with clear, front-loaded structure using dashes to enumerate outputs. No unnecessary words.
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 lists three output aspects but does not explain how they are returned (e.g., lists, graphs). With no output schema, more detail on the return format would be helpful.
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 100%, so the description adds no extra meaning beyond the schema. It does not elaborate on parameter values or constraints beyond what the schema specifies.
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 verb 'Map', the resource 'dependencies for a file', and distinct results: consumers, dependencies, and circular dep detection. It differentiates from siblings by specifying this unique dependency-mapping purpose.
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 implies usage when dependency mapping is needed but lacks explicit guidance on when to use this tool versus alternatives like refactory_analyze. No 'when-not' or alternative names are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract one module from the monolith according to the plan. Routes to the cheapest capable free LLM API.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Path to the monolith file | |
| module | Yes | Module name to extract (from the plan) | |
| functions | No | Function names to include | |
| outputDir | No | Output directory for extracted module | |
| plan | No | Path to the decomposition plan JSON |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description alone must disclose behavioral traits. It mentions 'routes to the cheapest capable free LLM API', which hints at external dependency and cost optimization but lacks details on failure modes, destructive nature, or prerequisites (e.g., internet access). Essential transparency is missing for a tool that invokes an external service.
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?
Two sentences, each contributing some information. The second sentence about routing could be integrated into behavioral context but is not excessive. However, the first sentence could be more precise (e.g., 'Extract one module from the monolith following the given decomposition plan'). Still, it is reasonably concise with no 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 5 parameters, no output schema, and no annotations, the description is insufficient. It does not explain what the output of extraction is (e.g., new files, modified directory structure, or return value), nor does it clarify the role of the plan parameter. A user would need to guess the tool's behavior beyond the schema.
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 input schema has 100% coverage with descriptions for each parameter. The tool description does not add any additional meaning beyond what the schema already provides. According to the guidelines, with high schema coverage, baseline is 3; no extra value from description.
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 extracts a module from a monolith according to a plan, which is a specific verb+resource combo. It distinguishes from siblings like refactory_decompose (which creates the plan) and refactory_analyze (which analyzes). The mention of routing to an LLM API is tangential but does not obscure the core purpose.
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?
No explicit guidance on when to use this tool versus alternatives (e.g., sibling tools like refactory_analyze or refactory_fix_imports). The phrase 'according to the plan' implies it should follow refactory_decompose, but no clear context or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mechanically fix broken require() paths after module extraction. No LLM needed — pure path resolution.
| Name | Required | Description | Default |
|---|---|---|---|
| moduleDir | Yes | Directory containing extracted modules | |
| projectDir | No | Project root to scan for consumers | |
| dryRun | No | Report changes without writing (default: false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must carry the burden. It discloses it is mechanical and reports via dryRun, but does not specify that files are modified when not in dry-run mode or other side 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 two concise sentences with no filler, front-loaded with purpose and supplemented with a distinguishing statement about no LLM needed.
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?
No output schema, so description should explain outcomes. It states what the tool does but omits details like backup behavior, error handling, or whether it scans subdirectories. Adequate for a simple tool but could be improved.
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 100% with parameter descriptions. The description adds context (after extraction, pure path resolution) but does not significantly augment the existing parameter documentation.
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 fixes broken require() paths after module extraction, specifying it is mechanical (pure path resolution, no LLM). This differentiates it clearly from siblings like refactory_extract or refactory_analyze.
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 implies use after module extraction but does not explicitly state when to use vs. alternatives or provide exclusions. No when-not or alternative tool names are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Calculate before/after metrics and the Refactory Score (0-1). Measures health improvement, module quality, test preservation.
| Name | Required | Description | Default |
|---|---|---|---|
| original | Yes | Path to the original monolith | |
| moduleDir | Yes | Directory containing extracted modules | |
| testResults | No | Path to test results JSON (before/after) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavior. Does not mention if tool is read-only, modifies data, or requires specific permissions. Lacks details on side effects or operation scope.
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?
Two front-loaded sentences: first states primary action, second lists measured aspects. No redundant 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?
Does not describe output format or structure, despite no output schema. Lacks details on what 'before/after metrics' entails or how Refactory Score is presented.
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 100%, so parameters are already documented. Description adds minimal context beyond schema, stating it computes metrics but not elaborating on each parameter's role.
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?
Clearly states it calculates before/after metrics and Refactory Score. Describes measured aspects (health, module quality, test preservation), distinguishing it from sibling tools like refactory_analyze or refactory_characterize.
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?
No guidance on when to use this tool vs alternatives. Does not specify prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a decomposition plan — module boundaries, function assignments, dependency order. Uses AST analysis + LLM reasoning.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Path to the monolith file | |
| modules | No | Target number of modules (auto if omitted) | |
| maxLines | No | Max lines per module (default: 500) | |
| style | No | Grouping style: 'functional' | 'domain' | 'layer' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description partially carries the burden by mentioning AST analysis and LLM reasoning, but it does not describe side effects, return format, or operational traits (e.g., idempotency, rate limits). It is adequate but not comprehensive.
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?
Two sentences, front-loaded with purpose, no wasted words. Every sentence adds value.
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 4-parameter planning tool with no output schema, the description is adequate but lacks details on output format and integration with sibling tools. It could be more helpful by specifying that the plan is returned or how to use the result.
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 100%, so the baseline is 3. The description adds no additional meaning beyond what the schema provides; it does not explain how parameters like 'style' affect the plan or the effect of omitting 'modules'.
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 generates a decomposition plan with specific outputs (module boundaries, function assignments, dependency order) and distinguishes it from sibling tools like refactory_analyze or refactory_decompose by focusing on planning.
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?
No guidance is provided on when to use this tool versus alternatives. The description does not mention prerequisites, when to prefer it, or exclusion criteria, leaving the agent to infer usage context without support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a decomposition report with metrics, dependency graphs, and Refactory Score. Outputs Markdown or HTML.
| Name | Required | Description | Default |
|---|---|---|---|
| metricsFile | Yes | Path to metrics JSON from refactory_metrics | |
| format | No | 'markdown' (default) or 'html' | |
| outputPath | No | Where to write the report |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses it generates a report but does not mention side effects, permissions, or safety aspects. The description is adequate but not rich in 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 a single concise sentence that front-loads the primary action and includes key output details, with no extraneous 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?
Given the tool's simplicity (3 params, no output schema), the description adequately covers what the tool does and its outputs. It could mention whether it overwrites the outputPath file, but overall it is sufficient.
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 100%, so the baseline is 3. The description adds context about the report's content but does not enhance parameter meaning beyond what the schema already provides (e.g., for format, it says 'markdown (default) or html').
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 generates a decomposition report with specific content (metrics, dependency graphs, score) and output formats (Markdown/HTML), effectively distinguishing it from sibling tools like refactory_metrics or refactory_decompose.
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 implies usage after refactory_metrics by requiring a metricsFile input, but it lacks explicit guidance on when to use this tool versus alternatives, such as when to generate a report versus analyzing with other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify a decomposed module: loads without errors, exports match plan, no circular deps, tests pass.
| Name | Required | Description | Default |
|---|---|---|---|
| moduleDir | Yes | Directory containing extracted modules | |
| original | No | Path to the original monolith (for export comparison) | |
| testCmd | No | Test command to run (e.g., 'npm test') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes what the tool checks (load errors, export matching, circular deps, tests pass), but does not state whether it is read-only or has side effects. No annotations provided, so description carries full burden, but safety profile remains unclear.
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?
Single sentence, front-loads the purpose and key checks. No redundant 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?
No output schema and the description does not explain return values or what 'passes' means. Does not detail how parameters like testCmd are executed. Leaves gaps for an agent to understand the tool's full behavior.
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?
All 3 parameters have descriptions in the input schema (100% coverage). The description adds limited extra meaning beyond the schema, like hinting that 'original' is used for export comparison. Baseline 3 is appropriate.
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?
Clearly states the verb 'verify' and the specific resource 'decomposed module' with concrete checks (loads, exports, circular deps, tests). Distinguishes from siblings like refactory_analyze and refactory_verify_exports.
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?
No explicit guidance on when to use this tool versus alternatives. With siblings like refactory_verify_exports, the description lacks context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare post-decomposition module against golden export snapshot. Reports missing, added, or type-changed exports.
| Name | Required | Description | Default |
|---|---|---|---|
| goldenFile | Yes | Path to .golden-exports.json from characterize | |
| newFile | Yes | Path to the new re-export module |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It describes the output (reports missing/added/type-changed exports) but does not clarify whether the tool is read-only, what permissions are needed, or error conditions. The name and schema do not compensate for this lack of transparency.
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?
Two sentences, directly to the point. No unnecessary words. The most important information (what it does and what it reports) is 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 simplicity (two parameters, no output schema), the description provides a reasonable overview. It could mention the output format or relationship to refactory_verify, but is largely adequate for a focused comparison 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 100%, so the schema already documents both parameters adequately. The description adds no extra meaning beyond the schema's field descriptions. Baseline score of 3 is appropriate.
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 compares a post-decomposition module against a golden export snapshot and reports specific differences (missing, added, type-changed exports). This distinguishes it from sibling tools like refactory_characterize or refactory_decompose by its specific focus on export verification.
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 implies usage after decomposition ('post-decomposition module') but does not explicitly state when to use this tool versus alternatives such as refactory_verify or refactory_analyze. No 'when-not-to-use' guidance or alternative tool references are provided.
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.
v0.2.0refactory_analyzerefactory_characterizerefactory_decomposerefactory_depmaprefactory_extractrefactory_fix_importsrefactory_metricsrefactory_planrefactory_reportrefactory_verifyrefactory_verify_exportsScored across 11 tools
Each tool has a distinct and clearly defined purpose within the decomposition pipeline—analyze, characterize, decompose, depmap, extract, fix imports, metrics, plan, report, verify, verify exports. There is no overlap or ambiguity between them; an agent can easily select the correct tool for each step.
All tools follow the consistent pattern 'refactory_verb_noun' (e.g., refactory_analyze, refactory_fix_imports, refactory_verify_exports). The naming is uniform, predictable, and uses only snake_case, making it easy for an agent to infer functionality from the name.
With 11 tools, the server is well-scoped for its domain of code decomposition. Each tool serves a necessary step in the pipeline, and the count is neither too low (missing functionality) nor too high (unwieldy). The tool set earns its place.
The tools cover the entire decomposition lifecycle: analysis, characterization, dependency mapping, planning, extraction, import fixing, verification, metrics, reporting, and export verification. There are no obvious gaps; the surface is complete for the stated purpose of refactoring a monolithic file.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
AI-powered codebase analysis — call graphs, security, dead code, complexity. 150+ tools.
AI Agent with Architectural Memory. Impact analysis (free), tests and code from the graph (pro).
Codebase intelligence for agents: 152 structured artifacts across 21 programs, one call.
