What can you do with this server?

The ast-editor server enables AI agents to surgically read and edit source code using Abstract Syntax Trees (AST), avoiding brittle search-and-replace or diff operations, with significant token savings (40–60% per session). Structural Code Editing * Replace entire functions, bodies, signatures, or snippets within a function body * Insert content inside a function body (top, bottom, or anchored position) * Add top-level content, methods, or fields/attributes to classes * Insert siblings before/after named symbols * Delete functions, methods, or classes (with optional leading comment removal) Parameters & Signatures * Add or remove parameters from function signatures Import/Include Management * Add or remove import statements (idempotent, skips duplicates) * Add or remove individual names from multi-name imports (Python/JS/TS) Comments & Docstrings * Add, replace, or remove leading comments above symbols * Replace or insert Python docstrings Config/Dict/Array Editing (JSON, YAML, TOML, Python literals) * Replace values, add/delete key-value pairs, append/remove array items Read-Only Navigation * List all top-level symbols with line numbers * Read a symbol's full source, interface stub, or just its signature (10–200× fewer tokens than reading whole files) * Read all imports/includes * Find all references to an identifier Supported Languages: Python, JavaScript, TypeScript, C, C++, Ruby, Go, Java, JSON, YAML, TOML

Which integrations are available for this server?

Provides tools for surgically editing C++ source files via AST, including structural edits to functions, classes, methods, fields, and imports, with support for comments and annotations. Provides tools for surgically editing JavaScript/JSX source files via AST, including structural edits to functions, classes, methods, fields, and imports, with support for comments. Provides tools for surgically editing Python source files via AST, including structural edits to functions, classes, methods, fields, imports, docstrings, and module-level dict/list literals. Provides tools for surgically editing Ruby source files via AST, including structural edits to classes, modules, methods, singleton methods, and imports. Provides tools for surgically editing TOML configuration files via AST, including adding, deleting, and replacing keys and values, as well as appending to arrays. Provides tools for surgically editing TypeScript/TSX source files via AST, including structural edits to functions, classes, interfaces, methods, fields, and imports, with support for comments. Provides tools for surgically editing YAML files via AST, including adding, deleting, and replacing keys and values, as well as appending to sequences.

de en es ja ko ru zh

ast-editor

by kambleakash0

Overview Schema Related Servers Score Discussions

Python

Local

AST Code Editor MCP Server

A robust, language-agnostic Model Context Protocol (MCP) server that provides AI coding agents with the ability to edit files surgically via Abstract Syntax Trees (AST) instead of relying on token-heavy, brittle search-and-replace or diff operations.

Why AST Edits?

Every non-AST edit format — search/replace, unified diff, whole-file rewrite — requires the model to copy text perfectly from a file it saw once. One whitespace mismatch on a 4,000-line file and the edit fails. AST edits sidestep the problem entirely: the model names the target (e.g., LRUCache.get) and provides the new code; the parser figures out where it lives.

Geometric AGI benchmarked every major format across 4 models and 29 edit tasks. AST edits were the only format to hit 100% correctness on 3 of 4 models, with 18x fewer output tokens than whole-file rewrite, and zero format failures. Full methodology and results: AST Edits: The Code Editing Format Nobody Uses.

Credits

This MCP server was inspired by research from Jack Foxabbott and the team at Geometric AGI. Their full findings, benchmark suite, and data are available here:

AST Edits: The Code Editing Format Nobody Uses (Blog)
Jack Foxabbott's original post (LinkedIn)
GeometricAGI/blog (Benchmark code & data)

Related MCP server: code-index-mcp

Estimated Token Savings

Per-edit output token savings versus other common edit formats:

Edit size	File size	vs whole-file rewrite	vs unified diff	vs search/replace
1-line tweak	100 LoC	3–5x	~1.5x	~1.5x
Function body rewrite	500 LoC	8–12x	2–3x	2–3x
Function body rewrite	4,000 LoC	15–20x	3–5x	3–5x
Add 2 lines to a function	any size	~20x (via `prepend_to_body` / `append_to_body`)	5–10x	3–5x

Per-read input token savings versus reading the entire file:

Read task	File size	AST reader tool	vs full file read
One function's source	500 LoC	`read_symbol`	~20x fewer tokens
One function's source	2,000 LoC	`read_symbol`	~50-100x fewer tokens
Class API (10 methods, no bodies)	500 LoC	`read_interface`	~10x fewer tokens
Import block only	any size	`read_imports`	~20-50x fewer tokens
Structural overview (names + line numbers)	any size	`list_symbols`	~15-30x fewer tokens
One function's signature	any size	`get_signature`	~50-200x fewer tokens

For daily agent users, a realistic 40-60% reduction in total tokens per session is achievable, on average (combining output savings from surgical edits with input savings from targeted reads).

The savings come from four compounding effects:

Output tokens: Using prepend_to_body / append_to_body for small additions instead of rewriting whole function bodies
Input tokens: Using read_symbol / read_interface / read_imports to read only what's needed instead of entire files (~10-20x fewer input tokens per read)
Discovery: list_symbols / get_signature instead of reading whole files
Zero format failures: AST edits never fail on whitespace drift, eliminating retry loops that plague other formats.

Supported Languages & Capabilities

Language	Extensions	Structural edits	Comments	Docstrings	Notes
Python	`.py`	✅	✅ `#`	✅ function/class	Decorators preserved. Module-level `dict`/`list` literals editable via `add_key` / `append_to_array`.
JavaScript	`.js`, `.jsx`, `.mjs`, `.cjs`	✅	✅ `//` + `/* ... */`	—
TypeScript	`.ts`, `.tsx`	✅	✅ `//` + `/* ... */`	—	Interfaces are treated as classes for `add_method` / `add_field`.
C	`.c`, `.h`	✅	✅ `//` + `/* ... */` (single + multi-line)	—	`.h` defaults to C — use `.hpp`/`.hxx`/`.hh` for C++ headers.
C++	`.cpp`, `.cc`, `.cxx`, `.hpp`, `.hxx`, `.hh`	✅	✅ `//` + `/* ... */` (single + multi-line)	—	Supports `class`, `struct`, `union`, `enum`, `namespace`; `Class::method` qualified names resolve correctly.
Ruby	`.rb`	✅	✅ `#`	—	Classes, modules, instance methods, `singleton_method` (class methods via `def self.foo`). `require`/`require_relative`/`load`/`autoload` recognized as imports.
Go	`.go`	✅	✅ `//` + `/* ... */`	—	`struct`, `interface`, functions, methods. Methods are addressed by receiver: `Cache.Get` resolves to the top-level `func (c *Cache) Get(...)`. Grouped `import (...)` blocks supported.
Java	`.java`	✅	✅ `//` + `/* ... /` + Javadoc `/* ... */`	—	`class`, `interface`, `enum`, `record`; methods, constructors, fields. Annotations (`@Override`, `@Deprecated`) travel with their method on edits (wrapped in the `modifiers` node). Enum methods (nested in `enum_body_declarations`) discovered via BFS in `list_symbols`.
JSON	`.json`	✅ (keys, values, arrays)	— (no comment syntax)	—
YAML	`.yml`, `.yaml`	✅ (keys, values, sequences)	✅ `#`	—	Block and flow sequences supported.
TOML	`.toml`	✅ (keys, values, arrays, tables)	✅ `#`	—	`[table]` headers addressable by name for comment tools.

Cross-cutting features:

Decorated functions (Python @decorator): decorators are preserved on body/signature edits and included on delete.
Byte-correct slicing: multi-byte characters (emoji, ═, →) handled safely in source text.
Idempotent imports: add_import skips exact duplicates automatically. For Go specifically, when a parenthesized import ( ... ) block already exists, new specs are inserted inside the block rather than as a bare top-level line (which would be a syntax error for spec-only input like "path/filepath").
Doc-comment-aware deletion: delete_symbol by default removes the contiguous leading comment block above the symbol (Godoc, Javadoc, #/// comment runs) so docs don't become orphaned. Opt out with include_leading_comments=False.

Language-specific design decisions

A few tools have language-specific semantics where multiple reasonable interpretations exist. The chosen behavior is documented here for transparency:

add_field (Ruby and Go) — option (a): literal text passthrough

Ruby: add_field("LRUCache", " attr_accessor :capacity") inserts the literal string at the top of the class body. The tool does not auto-wrap bare names in attr_accessor — you provide the exact text you want (whether that's attr_accessor, attr_reader, @instance_var = nil in initialize, or CLASS_CONST = 42).
Go: add_field("Cache", "\tversion int") inserts the literal string inside the struct { ... } body. The tool does not infer types from bare names — you provide the full Go field declaration.
Rationale: consistent with how add_field works for other languages (Python, JS/TS, C++) where the caller provides the full source text. The alternative option (b) — auto-wrapping (e.g. attr_accessor :foo from the name foo) — would be more magical but harder to use for edge cases (typed fields, readonly fields, field with default value, etc.).

add_method (Go) — option (a): top-level sibling insertion

add_method("Cache", "func (c *Cache) Has(key string) bool { ... }") locates the type Cache struct { ... } declaration and inserts the new method immediately after it, at the top level (not inside the struct's braces).
Rationale: Go methods are lexically top-level, not nested inside their receiver type — this matches how Go code is actually written. The alternative option (b) — refusing because "Go methods aren't inside structs" — would be pedantically correct but force callers to use insert_after("Cache", content) instead, which loses the semantic signal that this is a method addition.

Tools Exposed

All tools require file_path to be an absolute path to an existing file.

Code editing — structural (Python, JS, TS, C, C++, Ruby, Go, Java)

Tool	Parameters	Description
`replace_function`	`file_path`, `target`, `content`	Replace a full function definition (signature + body + decorators).
`replace_function_body`	`file_path`, `target`, `content`	Replace only the body of a function, preserving signature and decorators.
`replace_signature`	`file_path`, `target`, `new_signature`	Replace only the signature, preserving body and decorators.
`replace_in_body`	`file_path`, `target`, `old_snippet`, `new_snippet`	Replace a byte-identical snippet inside a function body. Scoped to target's body; raises on multiple matches.
`delete_in_body`	`file_path`, `target`, `snippet`	Delete a byte-identical snippet inside a function body. Scoped to target's body; raises on multiple matches.
`insert_in_body`	`file_path`, `target`, `new_snippet`, `at` \| `after` \| `before`	Insert a snippet inside a function body. Pass exactly ONE of: `at="top"` (prepend), `at="bottom"` (append), `after=<snippet>` (anchored), `before=<snippet>` (anchored).
`add_top_level`	`file_path`, `content`, `position="bottom"`	Insert top-level content. `position="bottom"` appends at end of file (default); `position="top"` inserts after preamble (package/imports/includes/leading comments, plus Python module docstring) and before the first real declaration.
`add_method`	`file_path`, `class_target`, `content`	Add a method at the end of a class body.
`add_field`	`file_path`, `class_target`, `content`	Add a field/attribute/member at the top of a class body.
`insert_sibling`	`file_path`, `target`, `content`, `position`	Insert content as a sibling of a named symbol. `position="before"` or `"after"`.
`delete_symbol`	`file_path`, `target`, `include_leading_comments=True`	Delete a function or class definition block (including decorators). By default also consumes the contiguous leading comment block above the symbol (Godoc, Javadoc `/** ... */`, `#` or `//` comments); pass `include_leading_comments=False` to keep it.

Parameters & signatures

Tool	Parameters	Description
`add_parameter`	`file_path`, `target`, `parameter`, `position`	Add a parameter to a function signature (`position`: `"start"` or `"end"`).
`remove_parameter`	`file_path`, `target`, `parameter_name`	Remove a parameter by name.

Imports & includes

Tool	Parameters	Description
`add_import`	`file_path`, `import_text`	Add an `import`/`from`/`#include` line. Skips duplicates. For Go, if a parenthesized `import ( ... )` block already exists, the spec is inserted inside that block (accepts either `import "foo"` or just `"foo"` / `alias "foo"` as input).
`remove_import`	`file_path`, `import_text`	Remove a matching import line.
`add_import_name`	`file_path`, `module`, `name`	Add one name to an existing named-import statement: `from <module> import a, b` (Python) or `import { a, b } from "<module>"` (JS/TS). Idempotent.
`remove_import_name`	`file_path`, `module`, `name`	Remove one name from a multi-name named-import statement (Python and JS/TS). If the last named import is removed and no default/namespace binding remains, the whole line is removed.

Comments & docstrings

Tool	Parameters	Description
`edit_leading_comment`	`file_path`, `target`, `op`, `comment=""`	Edit the contiguous leading-comment block above a named symbol. `op="add"` inserts; `op="replace"` replaces (or inserts if none); `op="remove"` deletes. Works for `#` / `//` / `/* ... /` / Javadoc `/* ... */`.
`replace_docstring`	`file_path`, `target`, `new_docstring`	Replace or insert a Python function/class docstring. Python-only.

Dict/list editing (JSON, YAML, TOML, AND Python module-level dict/list literals)

Tool	Parameters	Description
`replace_value`	`file_path`, `target`, `content`	Replace the value of an existing config key. `target` is the dotted key path.
`add_key`	`file_path`, `parent_target`, `key`, `value`	Add a key-value pair to a dict/object/mapping/table. For Python, `parent_target` is the dict variable name; for config, a dotted path (use `""` for root).
`delete_key`	`file_path`, `target`	Delete a key-value pair. Targets: JSON/YAML/TOML dotted path; Python `DictName.keyExpr`; JS/TS `VarName.keyName` on `const`/`let`/`var` or `export const` object literals (handles regular pairs, `{ key }` shorthand, and quoted `"complex-key"`). For JSON and JS/TS, adjacent comma is also removed.
`append_to_array`	`file_path`, `target`, `value`	Append a literal value to a list/array/sequence. For Python, `target` is the list variable name; for config, a dotted path.
`remove_from_array`	`file_path`, `target`, `value_match`	Remove the first matching element from a list/array/sequence.

Tool	Parameters	Description
`list_symbols`	`file_path`	Formatted outline of all top-level functions, classes, and methods with line numbers.
`find_references`	`file_path`, `target`	Syntactic search for all occurrences of an identifier (no scope awareness).
`read_symbol`	`file_path`, `target`, `depth="full"`	Return source text of a single named symbol. `depth` controls how much: `"full"` returns the entire source (typically 10-20x fewer tokens than the whole file); `"interface"` returns a class stub (header + fields + method sigs with `...`) or a function's signature; `"signature"` returns signature-only.
`read_imports`	`file_path`	Return all import/include statements in the file.

Target format: Use the exact function name (e.g., get) or dotted Class.method path (e.g., LRUCache.get). Decorated Python functions are fully supported — decorators are preserved when replacing bodies or signatures, and included when deleting or replacing the full function.

Tip: Call list_symbols first to discover exact target names before editing. This avoids guessing and makes subsequent edits much more reliable.

Which tool should I use?

A decision guide grouped by intent. Start at the top and pick the narrowest match.

Discovering what's in a file (do this first)

Don't know what symbols exist? → list_symbols
Need one specific function's full source? → read_symbol (depth="full", the default — 10-20x cheaper than reading the whole file)
Need a class's public API (methods + fields, no bodies)? → read_symbol(target, depth="interface")
Need just a function's signature? → read_symbol(target, depth="signature")
Need to see a file's imports/dependencies? → read_imports
Where is a symbol used? → find_references

Dotted targets descend into closures: Go stdioCmd.RunE (func_literal in struct field), TS app.handler (arrow function in object literal).

Adding new content

Intent	Tool
New top-level function, class, constant, or type alias	`add_top_level` (use `position="top"` to prepend after preamble)
New method in an existing class	`add_method`
New field/attribute/member in a class	`add_field`
New content before or after a top-level symbol	`insert_sibling(position="before" \| "after")`
New lines at the top of an existing function body	`insert_in_body(at="top")`
New lines at the bottom of an existing function body	`insert_in_body(at="bottom")`
New lines at a specific spot inside a function body (anchored to existing text)	`insert_in_body(after=…)` or `insert_in_body(before=…)`
New parameter on an existing function	`add_parameter`
New import or `#include`	`add_import`
New name in an existing `from X import …` or `import { a, b } from "mod"`	`add_import_name`
New comment above a symbol	`edit_leading_comment(op="add")`
New Python docstring on a function/class	`replace_docstring`
New key in a dict/object/mapping/table (any lang)	`add_key`
New item in a list/array/sequence (any lang)	`append_to_array`

Modifying existing content

Intent	Tool
Rewrite the full function (signature + body)	`replace_function`
Rewrite only the body, keep the signature	`replace_function_body`
Change one statement/block inside a large body	`replace_in_body` (scoped snippet match)
Change only the signature, keep the body	`replace_signature`
Change only the leading comment above a symbol	`edit_leading_comment(op="replace")`
Change only the Python docstring	`replace_docstring`
Change the value of an existing config key	`replace_value`

Removing content

Intent	Tool
Remove a function, method, or class	`delete_symbol` (consumes leading doc comment by default)
Remove one statement/line inside a function body	`delete_in_body`
Remove a parameter from a function	`remove_parameter`
Remove an import or `#include`	`remove_import`
Remove one name from a multi-name named-import (Python or JS/TS)	`remove_import_name`
Remove a leading comment above a symbol	`edit_leading_comment(op="remove")`
Remove a key from a dict / config / JS-TS object literal	`delete_key`
Remove an item from a list/array	`remove_from_array`

Anti-patterns to avoid

Don't use replace_function or replace_function_body to change a few lines — use replace_in_body (scoped snippet match) or insert_in_body(at="top" \| "bottom") for appending/prepending. Rewriting the whole function is wasteful and error-prone.
Don't use replace_signature to add or remove one parameter — use add_parameter/remove_parameter.
Don't use replace_value to add a new key — use add_key. replace_value only updates existing keys.
Don't use add_import to add a name to an existing from X import … or named import — use add_import_name.
Don't guess at target names. Call list_symbols first. Names are case-sensitive and must match exactly.

Logging & Debugging

The server logs all tool invocations and errors to stderr (safe for stdio transport — does not interfere with JSON-RPC). Logs include timestamps and severity levels.

To inspect logs when running under Claude Desktop, check ~/Library/Logs/Claude/mcp*.log (macOS) or %APPDATA%\Claude\logs\mcp*.log (Windows).

For interactive testing, use the MCP Inspector.

Prerequisites

This MCP server uses uv to manage its Python environment and dependencies automatically. Install uv if you don't have it already:

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Homebrew (macOS):

brew install uv

pip (any platform):

pip install uv

Verify the installation:

uv --version

For more options (Docker, Cargo, WinGet, etc.), see the official uv installation docs.

Installation

Note: Replace /absolute/path/to below with the actual path to this repository on your machine.

Method 1: CLI Configuration (Claude Code, Codex, Gemini)

If your agent supports adding servers via CLI, run the following:

Claude Code / Codex CLI / Gemini CLI:

--scope user installs the server globally so it's available in every project on your machine. Drop it if you only want the server active in the current project.

# Claude Code / Codex
[claude|codex] mcp add ast-editor --scope user -- uv --directory /absolute/path/to/ast-editor run ast-editor-mcp

# Gemini CLI
gemini mcp add --transport stdio --scope user ast-editor -- uv --directory /absolute/path/to/ast-editor run ast-editor-mcp

Method 2: JSON Configuration

For tools that use a mcp_config.json or settings.json file, add the following block to the appropriate file path.

Important: Use the absolute path to uv for "command", not just "uv". GUI-based MCP clients (Claude Desktop, Cursor) don't always inherit your shell PATH, so a bare "uv" will fail with a "command not found" error. Get your absolute path with:
which uv
# e.g. /Users/you/.local/bin/uv  or  /opt/homebrew/bin/uv

{
  "mcpServers": {
    "ast-editor": {
      "command": "/absolute/path/to/uv",
      "args": [
        "--directory",
        "/absolute/path/to/ast-editor",
        "run",
        "ast-editor-mcp"
      ]
    }
  }
}

Agent	Configuration File Path
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS); `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
Cursor	`.cursor/mcp.json` (Project) or `~/.cursor/mcp.json` (Global)
Windsurf	Agent Panel → "..." → MCP Servers → View raw config
Antigravity	`~/.gemini/config/mcp_config.json` — see Antigravity IDE (uses `uvx --from`)
Gemini CLI	`~/.gemini/settings.json` (Global) or `.gemini/settings.json` (Project)

Antigravity IDE

The Antigravity IDE uses its own MCP config file and a uvx-based command — not the uv --directory … run form shown above. Add the server to ~/.gemini/config/mcp_config.json:

Important: Use the absolute path to uvx for "command", not a bare "uvx" — Antigravity doesn't inherit your shell PATH. Find it with which uvx (e.g. /opt/homebrew/bin/uvx).

{
  "mcpServers": {
    "ast-editor": {
      "command": "/absolute/path/to/uvx",
      "args": [
        "--from",
        "/absolute/path/to/ast-editor",
        "ast-editor-mcp"
      ]
    }
  }
}

Using Standard Python (Fallback)

If you prefer not to use uv, install manually and point to the .venv executable in ast-editor directory:

python3 -m venv .venv && source .venv/bin/activate && pip install .

{
  "mcpServers": {
    "ast-editor": {
      "command": "/absolute/path/to/ast-editor/.venv/bin/python",
      "args": ["-m", "ast_editor.server"]
    }
  }
}

Agent Configuration (Important)

Coding agents are heavily biased toward their default tools. You must explicitly instruct them to use AST tools. The agent prompt lives in AST-EDITOR.md — a standalone file you wire into your agent's system instructions.

Claude Code / Claude Desktop (via `@`-include)

Claude Code supports @filename includes in CLAUDE.md. Copy the prompt file into your global config directory and add one include line:

cp /absolute/path/to/ast-editor/AST-EDITOR.md ~/.claude/
echo '@AST-EDITOR.md' >> ~/.claude/CLAUDE.md

Or for a single project, place it next to the project's CLAUDE.md and add @AST-EDITOR.md there.

Other agents (Cursor, Codex CLI, Windsurf, Antigravity, Aider, Gemini CLI, etc.)

Copy the contents of AST-EDITOR.md into your agent's instruction file (AGENTS.md, .cursor/rules/*.mdc, .windsurfrules, .github/copilot-instructions.md, system prompt, etc.). Most non-Claude agents don't support @-include — paste the prompt body directly.

Agent	Instruction file
Any agent that reads `AGENTS.md` (Codex CLI, Windsurf, Zed, Cursor secondary)	`AGENTS.md` at repo root
Cursor	`.cursor/rules/*.mdc` (current) — legacy: `.cursorrules`
GitHub Copilot	`.github/copilot-instructions.md`
Windsurf	`.windsurfrules` or `AGENTS.md`
Antigravity	`_agents/rules/`
Aider / Gemini CLI / generic	Rules file or system prompt

Available Tools

28 tools

add_fieldA

Add a field/attribute/member at the top of a class body (fields-before-methods convention).

Use this when: You're adding a class attribute (Python), class field (JS/TS), or member variable (C++). Don't use this when: You're adding a method -> use add_method.

Example: class_target="LRUCache" content=' version = "1.0"'

ParametersJSON Schema

Name	Required	Description	Default
`content`	Yes
`file_path`	Yes
`class_target`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4/5.0

Behavior3/5

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

No annotations are provided, so the description must fully disclose behavior. It mentions placement convention (top of class body, fields-before-methods), but does not specify whether it checks for duplicates, permissions, or side effects. Some behavioral context is given, 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.

Conciseness5/5

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

The description is concise, with a clear verb+resource structure, a usage guideline, and a concrete example. Every sentence serves a purpose, and the information is front-loaded.

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

Completeness3/5

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

Given the low schema coverage and absence of annotations, the description should compensate more. It provides good purpose and usage but leaves file_path unexplained. The output schema exists but is not referenced. The tool is simple, so basic usage is clear, but completeness is moderate.

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

Parameters2/5

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

The input schema has three parameters with 0% description coverage. The description only provides an example that explains class_target and content implicitly, but does not describe file_path at all. The example adds some meaning for two parameters, but the missing explanation for file_path leaves a significant gap.

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

Purpose5/5

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

The description clearly states it adds a field/attribute/member at the top of a class body, with specific language for Python, JS/TS, and C++. It distinguishes itself from add_method, making the purpose unmistakable.

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

Usage Guidelines5/5

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

The description explicitly states when to use (adding class attributes, fields, or member variables) and when not to use (adding methods), directing to add_method as an alternative. This provides clear guidance on tool selection.

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

add_importA

Add an import statement to a source file. Skips exact duplicates. Places new imports after existing ones, or at the top of the file if none exist.

Use this when: You need to import something the file does not already reference. Don't use this when: You're adding a single name to an existing multi-name import statement like from X import a, b -> use add_import_name.

Example: import_text="from typing import Optional" # Python import_text="import { readFile } from 'fs';" # JS/TS import_text="#include <stdlib.h>" # C/C++

ParametersJSON Schema

Name	Required	Description	Default
`file_path`	Yes
`import_text`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.7/5.0

Behavior4/5

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

No annotations provided, but description covers deduplication, placement, and gives examples across languages. Missing details on error handling or file modification confirmation, but still strong.

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

Conciseness5/5

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

Concise, front-loaded with purpose, then usage, then examples. Every sentence adds value; no waste.

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

Completeness5/5

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

Given no annotations and presence of output schema, description fully addresses selection and invocation needs with usage, examples, and sibling differentiation.

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

Parameters4/5

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

Schema has 0% coverage; description adds meaning by explaining import_text with multi-language examples and implying file_path usage. Sufficient for understanding parameter roles.

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

Purpose5/5

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

Description clearly states the tool adds an import statement with deduplication and placement details, and distinguishes from sibling add_import_name via specific verb+resource.

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

Usage Guidelines5/5

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

Explicitly says when to use ('needs import not already referenced') and when not to use (adding to existing multi-name import → use add_import_name), providing clear context.

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

add_import_nameA

Add a name to an existing named-import statement. Idempotent: skips if the name is already present.

Python (.py): from <module> import a, b
JS/TS: import { a, b } from "<module>"

Use this when: The module is already imported via a named-import form and you want to add another name to that existing statement. Don't use this when: The import statement doesn't exist yet -> use add_import. You want a default or namespace import (import Foo from ... or import * as ns from ...) -> use add_import with the full line.

Example (Python): module="typing" name="Optional" Example (TS): module="./utils" name="baz"

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes
`module`	Yes
`file_path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.7/5.0

Behavior4/5

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

Discloses idempotency and effect on code; no annotations provided, so description carries full burden. Could mention error handling, but sufficient for typical use.

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

Conciseness5/5

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

Well-structured with sections, examples, and bullet points; every sentence adds value without redundancy.

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

Completeness5/5

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

Fully explains tool's purpose, usage, and behavior; output schema exists but description focuses on input and effect, which is appropriate for a simple mutation tool.

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

Parameters4/5

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

Schema has zero descriptions; description adds meaning for all parameters with clear examples (module is import source, name is the symbol). Completes missing schema info.

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

Purpose5/5

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

Clearly states 'Add a name to an existing named-import statement', specifies languages (Python, JS/TS) with examples, and distinguishes from siblings like add_import.

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

Usage Guidelines5/5

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

Explicitly provides when to use (existing named-import) and when not to use (use add_import for new imports or default/namespace imports), with alternatives named.

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

add_keyA

Add a new key-value pair inside a dict-like container. Works for JSON objects, YAML mappings, TOML tables, AND Python module-level dict literals.

For JSON/YAML/TOML: parent_target is the dotted path to the parent (use "" for root). For Python (.py): parent_target is the module-level variable name (e.g. 'CONFIG'). value should be a literal source expression in the target file's syntax (e.g. JSON '"foo"' or '42'; Python '"foo"' or '42').

Use this when: The key does not exist yet and you want to add it. Don't use this when: The key already exists -> use replace_value. You're adding an item to a list/array -> use append_to_array.

Example (JSON): parent_target="dependencies" key="mcp" value='"^1.2.0"' Example (Python): parent_target="CONFIG" # module-level CONFIG = {...} key='"timeout"' # include quotes if key is a string literal value="30"

ParametersJSON Schema

Name	Required	Description	Default
`key`	Yes
`value`	Yes
`file_path`	Yes
`parent_target`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.7/5.0

Behavior4/5

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

With no annotations, the description carries full burden. It explains different behavior per file type, required value syntax, and parent_target usage. Does not cover error handling or permissions, but these are less critical for this code manipulation tool.

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

Conciseness4/5

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

Well-structured with purpose, format-specific notes, usage guidelines, and examples. Slightly verbose due to examples, but content earns its place.

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

Completeness5/5

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

Given output schema exists, return values need not be explained. Description covers purpose, parameters, usage boundaries, and multiple file formats. No significant gaps for intended use.

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

Parameters5/5

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

Schema has 0% description coverage, so description compensates fully. It explains parent_target as dotted path vs. variable name, key as any string, value as literal expression. Examples clarify syntax for JSON and Python.

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

Purpose5/5

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

The description clearly states the tool adds a new key-value pair to dict-like containers, specifying supported formats (JSON, YAML, TOML, Python). It distinguishes from siblings like replace_value and append_to_array.

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

Usage Guidelines5/5

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

Explicitly provides when to use (key does not exist) and when not to use (key exists -> replace_value; adding to list -> append_to_array). Also gives format-specific guidance for parent_target and value.

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

add_methodA

Add a new method at the end of a class body.

Use this when: You're adding a method to an existing class. Don't use this when: You're adding a field/attribute -> use add_field. You're adding a top-level function (not inside a class) -> use add_top_level.

Example: class_target="LRUCache" content=' def clear(self):\n self.items.clear()'

ParametersJSON Schema

Name	Required	Description	Default
`content`	Yes
`file_path`	Yes
`class_target`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.4/5.0

Behavior3/5

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

No annotations provided, so description carries full burden. It reveals the insertion position (end of class body) but lacks details on side effects, validation, or file modification behavior.

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

Conciseness5/5

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

Extremely concise: three short sentences plus an example. Each sentence is purposeful and front-loaded with the core operation.

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

Completeness4/5

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

Covers operation, usage guidance, and example. With an output schema present, return values are not needed. Minor gaps: no mention that the class must exist or that file is modified in place.

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

Parameters4/5

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

Schema has 0% description coverage, but description partially compensates with a concrete example that clarifies class_target and content. However, file_path is not explained.

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

Purpose5/5

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

Clearly states 'Add a new method at the end of a class body.' The verb and resource are specific, and it distinguishes from siblings add_field and add_top_level.

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

Usage Guidelines5/5

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

Provides explicit when-to-use and when-not-to-use with named alternatives: use for adding methods to classes, not for fields (use add_field) or top-level functions (use add_top_level).

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

add_parameterA

Add a parameter to a function signature at position 'end' (default) or 'start'. Leaves the body untouched.

Use this when: You need to add one or two parameters without retyping the whole signature. Don't use this when: You need to replace the entire signature -> use replace_signature. You also want to change the body -> use replace_function.

Example: target="LRUCache.get" parameter="default=None" position="end"

ParametersJSON Schema

Name	Required	Default
`target`	Yes
`position`	No	end
`file_path`	Yes
`parameter`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.4/5.0

Behavior3/5

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

Description mentions 'Leaves the body untouched' but lacks details on error cases, permissions, or side effects. No annotations exist to supplement.

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

Conciseness5/5

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

Concise, front-loaded purpose statement, followed by usage guidance and a clear example. No unnecessary words.

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

Completeness4/5

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

Covers purpose, usage, and parameter semantics. With output schema existing, return values are likely covered. Could add error conditions but overall sufficient.

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

Parameters4/5

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

With 0% schema coverage, the description adds meaning by explaining the 'position' parameter defaults and valid values, and provides an example illustrating 'target' and 'parameter'.

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

Purpose5/5

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

Description clearly states 'Add a parameter to a function signature' with specific verb and resource. It distinguishes from siblings like replace_signature and remove_parameter.

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

Usage Guidelines5/5

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

Explicitly explains when to use (add one or two parameters) and when not to use (replace signature or change body), with specific alternative tools named.

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

add_top_levelA

Insert top-level content into the file: a function, class, constant, type alias, or any other top-level statement. position controls placement:

"bottom" (default): append to end of file.
"top": insert after the preamble (package/imports/includes/leading comments, plus the Python module docstring if present) and before the first real declaration.

Use this when: You're adding any kind of top-level code. Use position="top" when inserting multiple declarations at the top of a file without the insert_before <target> reverse-order problem. Don't use this when: You need placement relative to a specific symbol -> use insert_before / insert_after. You're adding to a class body -> use add_method / add_field. You're adding a line inside an existing function body -> use prepend_to_body / append_to_body.

Example: content="def parse_version(text):\n return tuple(int(x) for x in text.split('.'))" content="class Logger:\n pass", position="top" content="MAX_CONNECTIONS = 10", position="top"

ParametersJSON Schema

Name	Required	Default
`content`	Yes
`position`	No	bottom
`file_path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.7/5.0

Behavior4/5

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

Explains position parameter behavior with definitions for 'top' and 'bottom'. Missing explicit statement about file mutation, but context implies it; still solid given no annotations.

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

Conciseness4/5

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

Concise and well-structured with clear sections and examples. Slightly verbose with example duplication but overall efficient.

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

Completeness5/5

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

Covers all needed aspects for a tool with output schema: usage, exclusions, examples, and behavioral nuances. No gaps.

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

Parameters5/5

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

With 0% schema coverage, description fully explains all three parameters: file_path (implied), content (examples), position (two values and respective effects).

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

Purpose5/5

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

Description clearly states it inserts top-level content like functions, classes, constants. It distinguishes from siblings like add_method, add_field, etc., by specifying scope.

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

Usage Guidelines5/5

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

Explicitly provides when to use (any top-level code) and when not, with specific alternatives (insert_before/insert_after, add_method, prepend_to_body).

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

append_to_arrayA

Append a literal value to an array/list. Works for JSON arrays, YAML sequences, TOML arrays, AND Python module-level list literals.

For JSON/YAML/TOML: target is the dotted path to the array. For Python (.py): target is the module-level variable name (e.g. 'ITEMS').

Use this when: You want to add an item to a list (dependencies, keywords, include paths, fixtures, etc.). Don't use this when: You're adding a key-value pair -> use add_key.

Example (TOML): target="project.dependencies" value='"new-package"' Example (Python): target="ITEMS" value='"new-item"'

ParametersJSON Schema

Name	Required	Description	Default
`value`	Yes
`target`	Yes
`file_path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.6/5.0

Behavior4/5

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

With no annotations, the description carries full burden. It explains behavior for different file types (JSON/YAML/TOML vs Python), target format (dotted path vs variable name), and value formatting (with quoting examples). However, it does not mention error handling (e.g., what if target path does not exist) or whether the operation is idempotent. Still, the provided details go well beyond a generic statement.

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

Conciseness5/5

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

The description is concise and well-structured: a one-line purpose, then file-specific notes, usage guidance, and examples. Every sentence adds value, and there is no redundancy. The examples are placed at the end without bloating the core message.

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

Completeness4/5

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

Output schema exists, so return values need not be described. The description covers input semantics well for the given complexity (multiple file types). However, it omits details like error scenarios or whether appending to a non-existent array creates it. Given the good annotations from siblings, it is still fairly complete for a mutation tool.

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

Parameters4/5

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

Input schema has 3 parameters with 0% description coverage in the schema. The description adds meaning for 'target' (explains dotted path vs variable name) and 'value' (literal string with quoting examples). 'file_path' is not elaborated, but its purpose is obvious. The description partially compensates for the missing schema descriptions.

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

Purpose5/5

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

The description clearly states the tool appends a literal value to an array/list, specifies file types (JSON, YAML, TOML, Python), and distinguishes itself from the sibling tool 'add_key' by explicitly saying not to use it for key-value pairs. The verb 'append' plus resource 'array/list' is specific and unambiguous.

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

Usage Guidelines5/5

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

Provides explicit when-to-use and when-not-to-use guidance: 'Use this when: You want to add an item to a list... Don't use this when: You're adding a key-value pair -> use add_key.' This clearly sets the context and points to an alternative, making it easy for an agent to decide.

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

delete_in_bodyA

Delete a byte-identical snippet inside a named function/method body. Scoped to the target's body so global file matches don't apply.

Raises if the snippet is not found, or if it appears more than once in the body (include more surrounding context to make the match unique).

Use this when: You want to remove a specific statement, block, or line inside a function body without rewriting the whole body. Also useful for removing a single entry from an inline object-literal passed as a function argument -- target the enclosing function and delete the entry text. Don't use this when: You're deleting the entire function/class -> use delete_symbol.

Example (remove a mount call inside a function): target="RegisterRoutes" snippet='\tr.Mount("/kb", kbHandler)\n'

Example (remove a key from an inline object arg): target="main" snippet="\t\tclassification,\n"

ParametersJSON Schema

Name	Required	Description	Default
`target`	Yes
`snippet`	Yes
`file_path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.3/5.0

Behavior4/5

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

No annotations provided, so description carries full burden. It discloses error conditions (raises if not found or appears more than once), suggests making the match unique, and specifies byte-identical matching. Could mention permissions or side effects, but sufficient for a deletion tool.

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

Conciseness4/5

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

Well-structured with sections and examples. Not overly verbose, but every sentence adds value. Could be slightly more concise, but still effective.

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

Completeness4/5

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

Covers error conditions, usage guidelines, and examples. Has output schema, so return values not needed. For a tool with 3 required parameters and no enums, the description is fairly complete.

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

Parameters3/5

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

Schema coverage is 0%, but description indirectly explains target and snippet via examples and context. Does not explain file_path. With no param descriptions in schema, description could add more detail, but the examples help infer meaning.

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

Purpose5/5

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

The description clearly states it deletes a byte-identical snippet inside a named function/method body, scoped to the target's body. It distinguishes from delete_symbol by noting when to use the other tool for deleting entire functions/classes.

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

Usage Guidelines5/5

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

Provides explicit when-to-use (remove specific statement/block/line inside function body, or delete entry from inline object) and when-not-to-use (use delete_symbol for entire function). Includes examples demonstrating typical usage.

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

delete_keyA

Delete a key-value pair from a dict-like container.

JSON / YAML / TOML: dotted path to the key.
Python (.py) module-level dict literals: target is 'DictName.keyExpr' (e.g. 'CONFIG."timeout"').
JS / TS module-level const / let / var object literals (including export const ... = { ... }): target is 'VarName.keyName' or 'VarName."quoted-key"'. Handles both regular { key: value } pairs and shorthand { key } properties.

For JSON and JS/TS, the adjacent comma is also removed to keep the file valid.

Use this when: You want to remove an entire entry. Don't use this when: You want to remove an item from a list/array -> use remove_from_array. You need to edit an inline object literal passed as a function argument (foo({ x })) -- use delete_in_body (Phase 3) scoped to the enclosing function instead.

Example (JSON): target="dependencies.tree-sitter" Example (Python): target='CONFIG."timeout"' Example (TS): target="CONFIG.port" # regular pair target="CONFIG.name" # shorthand { name } target='CONFIG."complex-key"' # quoted key

ParametersJSON Schema

Name	Required	Description	Default
`target`	Yes
`file_path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.7/5.0

Behavior4/5

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

No annotations, so description carries burden. It explains comma removal for JSON/JS/TS but does not explicitly mention destructive nature or irreversibility. Otherwise, behavior is well described.

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

Conciseness4/5

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

Well-organized with sections, examples, and bullet points, but slightly verbose. Purpose and guidelines are front-loaded.

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

Completeness5/5

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

Covers purpose, usage, syntax, examples, boundaries, and alternatives. Includes edge cases like comma removal. Output schema exists, so return values are covered.

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

Parameters5/5

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

Input schema has 0% description coverage, but description extensively explains the 'target' parameter with syntax for each file type and examples. Adds significant meaning beyond schema.

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

Purpose5/5

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

Clearly states it deletes a key-value pair from dict-like containers, with specific file type syntax and examples. Distinguishes from sibling tools like remove_from_array and delete_in_body.

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

Usage Guidelines5/5

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

Explicitly provides 'Use this when' and 'Don't use this when' with named alternatives (remove_from_array, delete_in_body), guiding correct tool selection.

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

delete_symbolA

Delete an entire function or class definition, including its decorators. By default, also removes the contiguous leading comment block above the symbol (Godoc, Javadoc /** ... */, # or // comment runs) so the doc doesn't become orphaned floating text. Pass include_leading_comments=False to leave that comment in place.

Use this when: You want to remove a function, method, or class entirely from a source file -- along with its doc comment by default. Don't use this when: You want to remove a config key -> use delete_key. You want to remove an import -> use remove_import. You want to remove lines inside a function -> use delete_in_body (or replace_function_body to rewrite the whole body without the unwanted lines).

Example: target="LRUCache.old_method" # deletes a method + its leading comment target="DeprecatedClass" # deletes class, all methods, and preceding Javadoc target="Foo", include_leading_comments=False # keep the comment, delete only the symbol

ParametersJSON Schema

Name	Required	Description	Default
`target`	Yes
`file_path`	Yes
`include_leading_comments`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.4/5.0

Behavior3/5

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

While the description explains the default behavior of removing leading comments and the include_leading_comments parameter, it lacks details on side effects, permissions, error handling, or reversibility. Without annotations, more transparency would be beneficial.

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

Conciseness5/5

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

The description is well-structured: purpose first, then details, usage guidelines, and examples. Every sentence adds value with minimal verbosity.

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

Completeness4/5

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

Given the tool has an output schema and moderate complexity, the description covers usage, parameter behavior, and alternatives. It could include error scenarios but is sufficient for correct invocation.

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

Parameters4/5

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

The description explains the 'target' and 'include_leading_comments' parameters with examples and default behavior, adding meaning beyond the bare schema. The 'file_path' parameter is not explicitly described but its purpose is implied.

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

Purpose5/5

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

The description clearly states that the tool deletes an entire function or class definition along with its decorators. It differentiates from siblings by naming alternative tools like delete_key, remove_import, and delete_in_body.

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

Usage Guidelines5/5

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

Explicit 'Use this when' and 'Don't use this when' sections with specific alternatives, providing clear context for appropriate usage.

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

edit_leading_commentA

Edit the contiguous leading-comment block above a named symbol. One tool covering three operations on the same comment block.

Supported values for op:

"add": Insert a new comment block above the symbol. Requires comment. Raises if a leading comment already exists and would be pushed down as a separate block.
"replace": Replace the existing leading comment block with comment; if no leading comment exists, inserts one. Requires comment.
"remove": Delete the existing leading comment block. comment is ignored.

The comment must include the language's comment marker (# for Python/Ruby/YAML/TOML, // or /* ... */ for JS/TS/C/C++/Go/Java, /** ... */ Javadoc for Java). Supports multi-line C-style block comments as a single contiguous run.

Use this when: You want to document, update, or delete a leading comment on a function/class/method. Don't use this when: You want a Python docstring (which lives inside the function body) -> use replace_docstring. You want to edit text inside the function body itself -> use replace_in_body.

Example: target="LRUCache.get", op="add", comment=" # Retrieve an item by key, returning None if absent"

target="LRUCache.get", op="replace",
comment="    # Retrieve an item from the cache"

target="LRUCache.get", op="remove"

ParametersJSON Schema

Name	Required	Description	Default
`op`	Yes
`target`	Yes
`comment`	No
`file_path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.6/5.0

Behavior4/5

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

No annotations provided, but the description fully explains the three operations, including error conditions (raises on 'add' if existing) and comment syntax requirements. Does not mention file system effects but that is implied.

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

Conciseness4/5

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

Well-structured with sections for operations, usage, and examples. Front-loaded with purpose. A bit lengthy but each sentence adds value.

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

Completeness5/5

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

Given the tool's complexity (three operations, multiple parameters, error conditions), the description is thorough. Provides examples and covers all key aspects. Output schema likely covers return details.

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

Parameters4/5

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

The input schema has 0% description coverage, but the description compensates by detailing the 'op' enum values, the 'comment' parameter behavior per operation, and provides examples. Does not explicitly describe 'file_path' or 'target' but they are understandable from context.

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

Purpose5/5

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

The description clearly states it edits the contiguous leading-comment block above a named symbol, and distinguishes itself from siblings like replace_docstring and replace_in_body by specifying different use cases.

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

Usage Guidelines5/5

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

Explicitly states when to use ('when you want to document, update, or delete a leading comment') and when not to use ('Don't use this when: ...') with named alternatives, providing clear guidance.

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

find_referencesA

Return all occurrences of an identifier named target in a source file, as 'line N: '. Read-only, syntactic only (no scope awareness), so results may include unrelated identifiers that happen to share the same name.

Use this when: You're about to rename or refactor a symbol and need a quick survey of where it appears in the file. Don't use this when: You need cross-file or scope-aware analysis -> use a full language server.

Example: target="LRUCache"

ParametersJSON Schema

Name	Required	Description	Default
`target`	Yes
`file_path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior5/5

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

No annotations exist, so the description fully shoulders transparency. It states read-only behavior, syntactic-only analysis, and the limitation that results may include unrelated identifiers. This sets accurate expectations.

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

Conciseness4/5

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

The description is well-structured with a clear flow: purpose, behavioral note, usage guidance, example. However, the first sentence is slightly verbose. Overall efficient and front-loaded.

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

Completeness4/5

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

Given the tool's simplicity and no annotations, the description covers essential aspects: input parameters, behavior, output format, and usage context. The output schema existence is noted but not detailed; however, the description provides enough for an agent to use the tool.

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

Parameters3/5

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

Schema coverage is 0%, so the description must add meaning. It clarifies that 'target' is the identifier name to search for, but does not explain 'file_path' format or provide detailed syntax. The example helps somewhat but is insufficient for complete understanding.

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

Purpose5/5

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

The description clearly states the tool returns all occurrences of an identifier in a source file, formatted as 'line N: <source line>'. It distinguishes itself from sibling tools like list_symbols by focusing on references rather than definitions.

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

Usage Guidelines5/5

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

Explicitly describes when to use (renaming/refactoring) and when not to use (cross-file or scope-aware analysis), with a clear alternative (full language server). This helps the agent decide correctly.

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

insert_in_bodyA

Insert new_snippet inside a named function/method body. Pass EXACTLY ONE of at, after, or before -- this one tool covers four placement modes that used to be spread across three separate tools.

at="top": insert at the top of the body.
at="bottom": insert at the bottom of the body.
after=: insert immediately after a byte-identical anchor.
before=: insert immediately before a byte-identical anchor.

The anchor match (for after/before) is scoped to the target's body and must be unique -- multiple matches raise an error telling you to include more surrounding context. Caller is responsible for any leading/trailing newlines and indentation in new_snippet.

Use this when: You're inserting new lines into a function body. Use at="top"/at="bottom" for simple prepend/append, or after/before for anchored insertion. Don't use this when: You're replacing the whole body -> use replace_function_body. You're adding a top-level symbol -> use add_top_level. You're changing an existing snippet in the body -> use replace_in_body.

Example (prepend): target="handle" new_snippet=' log("start")\n' at="top"

Example (append): target="handle" new_snippet=' log("end")\n' at="bottom"

Example (after anchor): target="handle" new_snippet=' metrics.incr("calls")\n' after=' validate(request)\n'

Example (before anchor): target="handle" new_snippet=' auth_check(request)\n' before=' validate(request)\n'

ParametersJSON Schema

Name	Required	Description	Default
`at`	No
`after`	No
`before`	No
`target`	Yes
`file_path`	Yes
`new_snippet`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.7/5.0

Behavior4/5

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

With no annotations, the description carries the full burden. It discloses key behaviors: the requirement to pass exactly one of at/after/before, the uniqueness requirement for anchored matches, and the caller's responsibility for newlines and indentation. However, it does not specify error handling for invalid combinations or missing target, which slightly reduces completeness.

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

Conciseness5/5

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

The description is well-structured, starting with a concise purpose statement, followed by bullet points for modes, usage guidelines, and examples. Every sentence adds value without redundancy, achieving high information density with no wasted words.

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

Completeness4/5

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

Given the tool's complexity (6 parameters, 0% schema coverage) and the presence of an output schema, the description covers essential usage patterns and constraints. It could have addressed edge cases like missing target or conflicting placements more explicitly, but overall it is sufficiently complete for effective agent use.

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

Parameters5/5

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

Schema coverage is 0%, so the description must compensate, and it does so thoroughly. It explains the meaning of each parameter (file_path implied, target, new_snippet, at, after, before), their usage constraints, and provides concrete examples. The constraint that exactly one placement mode must be used is clearly communicated.

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

Purpose5/5

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

The description clearly states the tool's purpose with specific verb and resource: 'Insert new_snippet inside a named function/method body.' It further distinguishes its four placement modes and explicitly differentiates from sibling tools like replace_function_body, add_top_level, and replace_in_body, making the purpose unambiguous.

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

Usage Guidelines5/5

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

The description provides explicit when-to-use and when-not-to-use guidance, including direct references to alternative tools (e.g., 'use replace_function_body' for replacing the whole body). This makes the selection criteria very clear for an AI agent.

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

insert_siblingA

Insert content as a sibling of a named symbol (function, class, method, or top-level assignment). Pass position="before" or position="after".

Use this when: You need precise placement relative to another top-level symbol -- e.g. a helper function immediately before its caller, a constant immediately above the class that uses it. Don't use this when: You just want to append to the end of the file -> use add_top_level. You're inserting inside a function body -> use insert_in_body (with at, after, or before).

Example: target="LRUCache" content="CACHE_SIZE = 100" position="before"

target="LRUCache"
content="RELATED_CONSTANT = 42"
position="after"

ParametersJSON Schema

Name	Required	Description	Default
`target`	Yes
`content`	Yes
`position`	Yes
`file_path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.7/5.0

Behavior4/5

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

With no annotations, the description carries full burden. It explains insertion behavior (sibling vs inside), the role of position parameter, and provides usage examples. It does not mention error handling or side effects but is transparent enough for typical use.

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

Conciseness4/5

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

The description is somewhat verbose but well-structured with bullet points and examples. It front-loads the core action and follows with when-to-use guidance, making it easy to scan. Minor redundancy (e.g., repeating position examples) kept at bay.

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

Completeness5/5

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

Given 4 required parameters, no annotations, and an output schema present, the description covers all necessary aspects: purpose, parameter roles, usage guidelines, and examples. It is sufficient for an agent to invoke correctly without additional context.

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

Parameters5/5

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

Schema coverage is 0%, so description compensates fully. It explains the purpose of target, content, and position parameters, and includes concrete examples showing their values. file_path is implicit but clear from context.

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

Purpose5/5

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

The description clearly states the tool inserts content as a sibling of a named symbol, specifying position options. It distinguishes from sibling tools like add_top_level (append to file end) and insert_in_body (inside function body), making purpose unambiguous.

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

Usage Guidelines5/5

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

Explicitly provides when to use (precise placement relative to a symbol) and when not to use, with clear alternatives (add_top_level for end-of-file, insert_in_body for function bodies). Examples further clarify correct usage.

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

list_symbolsA

Return a formatted outline of all top-level functions, classes, and methods in a source file (Python, JS, TS, C, C++), with line numbers. Read-only.

Use this when: You're about to edit an unfamiliar file and want to see its structure and exact symbol names. ALWAYS a good first call before editing -- avoids guessing at target names. Don't use this when: You already know the exact target name.

Example: file_path="/abs/path/to/module.py"

ParametersJSON Schema

Name	Required	Description	Default
`file_path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.7/5.0

Behavior4/5

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

Declares read-only behavior and specifies supported languages and return content (line numbers, formatted outline). Lacks mention of error handling for invalid paths or unsupported languages, but overall transparent.

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

Conciseness5/5

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

Four concise sentences plus an example, no fluff. Information is front-loaded: purpose, usage, anti-usage, example. Every sentence adds unique value.

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

Completeness5/5

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

Covers purpose, usage, parameter example, and output format. Has output schema so return description is sufficient. Complete for a simple list tool with one parameter.

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

Parameters4/5

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

Adds context beyond the schema by providing an example and stating the file should be a source file in supported languages. Schema coverage is 0% so description compensates adequately.

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

Purpose5/5

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

The description clearly states the tool returns a formatted outline of top-level symbols with line numbers for multiple languages. It distinguishes itself from sibling tools that modify or delete symbols.

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

Usage Guidelines5/5

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

Explicitly provides when to use (before editing unfamiliar files) and when not to use (already know target name). Recommends it as a first call to avoid guessing, which is actionable guidance.

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

read_importsA

Return all import statements in a source file as a multi-line string. Read-only.

Use this when: You need to see a file's dependencies without reading the entire file (e.g. before adding a new import, or to understand what a module uses). Don't use this when: You want to add/remove imports -> use add_import / remove_import.

Example: file_path="/abs/path/to/module.py"

ParametersJSON Schema

Name	Required	Description	Default
`file_path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior4/5

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

Without annotations, the description discloses read-only behavior ('Read-only') and the return format. It does not cover error cases like missing files or unsupported extensions, but for a simple read tool, this is acceptable.

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

Conciseness5/5

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

The description is concise, with front-loaded key information in two short paragraphs and an example. Every sentence adds value without redundancy.

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

Completeness5/5

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

For a simple tool with one parameter and an output schema, the description covers the essential purpose, usage context, and an example. No additional details are necessary.

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

Parameters3/5

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

The sole parameter file_path has no schema description (0% coverage). The description provides an example showing an absolute path, but does not specify that the path must be absolute or exist, leaving ambiguity.

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

Purpose5/5

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

The description clearly states the tool returns all import statements in a source file as a multi-line string, distinguishing it from sibling tools like add_import and remove_import with an explicit purpose.

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

Usage Guidelines5/5

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

The description explicitly states when to use (e.g., before adding an import) and when not to use (e.g., adding/removing imports), and names the appropriate sibling tools (add_import, remove_import).

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

read_symbolA

Return source text for a single named symbol (function, class, method, config key) without reading the entire file. Read-only.

depth controls how much is returned:

"full" (default): Entire source of the symbol. Typical savings: 10-20x fewer tokens than reading the whole file.
"interface": For a class -> header + field declarations + method signatures with bodies replaced by ' ...'. For a function -> just the signature.
"signature": Signature-only. For a function -> the line(s) before the body. For a class -> the class header.

Use this when: You need to read a specific symbol without reading the whole file. Pick the narrowest depth that contains what you need. Don't use this when: You need a structural overview of the whole file -> use list_symbols. You need to see the file's imports -> use read_imports.

Example: target="LRUCache.get" # full method source target="LRUCache", depth="interface" # class skeleton target="LRUCache.get", depth="signature" # just the def line target="project.version" # config value

ParametersJSON Schema

Name	Required	Default
`depth`	No	full
`target`	Yes
`file_path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.6/5.0

Behavior4/5

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

No annotations provided, so description carries burden. Declares read-only nature, explains depth behavior thoroughly, but lacks details on error handling or file path expectations. Still very good.

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

Conciseness5/5

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

Concise, well-structured with bullet points and examples. Information is front-loaded. Every sentence is informative and earns its place.

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

Completeness4/5

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

Output schema exists so return values are covered. Description covers depth, usage, and examples. Could mention error handling or file path constraints, but overall quite complete for the tool's simplicity.

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

Parameters4/5

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

Schema description coverage is 0%, so description must compensate. It provides extensive detail on depth parameter, and example usage for target. Could be more explicit about target format and file_path requirements, but adds significant value.

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

Purpose5/5

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

The description clearly states it returns source text for a single named symbol, includes details on depth levels, and differentiates from sibling tools like list_symbols. The examples reinforce the purpose.

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

Usage Guidelines5/5

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

Explicitly says when to use (need to read a specific symbol) and when not (structural overview -> list_symbols; imports -> read_imports). Also advises to pick narrowest depth.

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

remove_from_arrayA

Remove the first element matching value_match (stripped text equality) from an array/list. Works for JSON/YAML/TOML config arrays AND Python module-level list literals.

For JSON/YAML/TOML: target is the dotted path to the array. For Python (.py): target is the module-level variable name.

Use this when: You want to remove a specific item from a list. Don't use this when: You want to remove a whole key -> use delete_key.

Example (TOML): target="project.dependencies" value_match='"old-package"' Example (Python): target="ITEMS" value_match='"old-item"'

ParametersJSON Schema

Name	Required	Description	Default
`target`	Yes
`file_path`	Yes
`value_match`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior3/5

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

Explains 'stripped text equality' and target semantics for different file types. But does not disclose error behavior (e.g., if value not found), side effects, or idempotency. No annotation provided so description carries the burden.

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

Conciseness4/5

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

Well-structured with main action, format notes, usage guidelines, and examples. Moderate length, front-loaded. Could be slightly more concise but overall efficient.

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

Completeness3/5

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

Covers main use cases and target formats. But missing return value description (though output schema exists but not shown) and error handling. Does not mention what happens if value not found or if file is read-only.

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

Parameters4/5

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

With 0% schema coverage, description adds significant meaning: explains target as dotted path or variable name, value_match as stripped text equality. Provides examples for TOML and Python. However, file_path is not described.

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

Purpose5/5

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

Description clearly states the action: remove first matching element from an array/list. It specifies supported formats (JSON/YAML/TOML and Python) and distinguishes from sibling delete_key.

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

Usage Guidelines5/5

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

Explicitly says 'Use this when:' and 'Don't use this when:' with a clear alternative (delete_key). Provides example contexts for different file types.

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

remove_importA

Remove a matching import statement from a source file. Matching is by stripped text equality -- pass the exact import line you want to remove.

Use this when: You want to remove an unused import. Don't use this when: You want to remove one name from a multi-name import -> use remove_import_name.

Example: import_text="import os"

ParametersJSON Schema

Name	Required	Description	Default
`file_path`	Yes
`import_text`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.4/5.0

Behavior3/5

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

Without annotations, the description should fully disclose behavior. It explains the matching logic ('stripped text equality') and provides an example, but does not mention error handling (e.g., what if the import is not found), return value, or side effects like file modification. This leaves some behavioral gaps.

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

Conciseness5/5

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

The description is very concise: three short sentences plus an example. The first sentence states the purpose, followed by usage guidelines and a concrete example. No wasted words.

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

Completeness4/5

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

Given the tool's simplicity (2 params, no nested objects, output schema exists), the description covers the core functionality and usage. It does not detail the output schema, but that is acceptable as the schema itself provides that information. Could mention what happens on success/failure, but overall sufficient.

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

Parameters4/5

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

Schema coverage is 0%, so the description must explain parameters. It describes 'import_text' as the exact import line to match (stripped) and provides an example. 'file_path' is not described but is self-explanatory. The description adds meaningful semantics beyond the bare schema.

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

Purpose5/5

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

The description clearly states the action: 'Remove a matching import statement from a source file.' It also distinguishes from the sibling tool 'remove_import_name' by specifying that this tool removes whole import lines, not individual names from multi-name imports.

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

Usage Guidelines5/5

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

Explicitly tells when to use ('remove an unused import') and when not to use ('remove one name from a multi-name import'), with a direct reference to the alternative tool 'remove_import_name'. This provides clear guidance for the AI agent.

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

remove_import_nameA

Remove a name from a named-import statement.

Python (.py): from <module> import a, b, c
JS/TS: import { a, b, c } from "<module>"

If the name removed is the only remaining one AND there are no other bindings (default / namespace) in the same statement, the entire import line is removed. Raises an error if removing the last name would leave an invalid import Default, {} from "mod" fragment.

Use this when: You want to remove a single name from a multi-name import. Don't use this when: You want to remove the entire import line -> use remove_import.

Example (Python): module="typing" name="List" Example (TS): module="./utils" name="bar"

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes
`module`	Yes
`file_path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior4/5

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

No annotations provided, so description carries full burden. It discloses edge cases: removing the last name removes entire line if no other bindings, and raises error for invalid fragments. Could mention permissions or side effects, but current coverage is strong.

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

Conciseness4/5

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

Description is concise and well-structured with bullet points and examples. A few lines could be streamlined, but overall it efficiently conveys necessary information.

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

Completeness4/5

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

Covers purpose, parameters, usage, and error cases. Does not explain output, but an output schema is present. For a code-modifying tool, it provides sufficient context.

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

Parameters4/5

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

Input schema has 0% description coverage, but description compensates with examples and clarifies the meaning of 'module' and 'name' via Python and TS examples. 'file_path' is self-explanatory but lacks explicit description.

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

Purpose5/5

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

Clearly states the tool removes a name from a named-import statement. Differentiates from sibling 'remove_import' by specifying it's for single name removal, not entire line.

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

Usage Guidelines5/5

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

Explicitly states when to use (removing a single name from a multi-name import) and when not to (use 'remove_import' instead). Provides language-specific examples and explains error conditions.

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

remove_parameterA

Remove a parameter by name from a function signature. Leaves the body untouched.

Use this when: You need to remove one parameter without retyping the whole signature. Don't use this when: You need to replace the whole signature -> use replace_signature.

Example: target="LRUCache.get" parameter_name="default"

ParametersJSON Schema

Name	Required	Description	Default
`target`	Yes
`file_path`	Yes
`parameter_name`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.4/5.0

Behavior4/5

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

No annotations provided, so description carries full burden. It states 'Leaves the body untouched' to indicate non-destructive nature. Could mention behavior when parameter not found, but otherwise clear.

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

Conciseness5/5

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

Extremely concise with a clear structure: purpose statement, usage guidelines, example. Every sentence adds value, no redundancy.

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

Completeness4/5

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

Given a simple 3-parameter tool with an output schema (not shown), the description covers essential aspects. Could mention error handling (e.g., missing parameter), but overall adequate.

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

Parameters3/5

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

Schema coverage is 0%, but the description uses an example to illustrate parameter usage (target, parameter_name). However, file_path is not described beyond being required.

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

Purpose5/5

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

The description clearly states the tool removes a parameter by name from a function signature, which is specific and distinct from siblings like 'replace_signature'. The example clarifies the target and parameter_name.

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

Usage Guidelines5/5

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

Explicit 'Use this when' and 'Don't use this when' sections provide clear context and name the alternative tool 'replace_signature', aiding correct selection.

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

replace_docstringA

Replace or insert a Python docstring on a function or class. Python-only. The new_docstring should be a valid Python string literal including its surrounding triple quotes.

Use this when: You want to add or update a Python docstring without touching the function body. Don't use this when: You're editing a # comment above the symbol -> use replace_leading_comment. You're in a non-Python file -> no equivalent tool.

Example: target="LRUCache.get" new_docstring=(triple-quoted string, e.g. with three double-quotes before and after the summary text)

ParametersJSON Schema

Name	Required	Description	Default
`target`	Yes
`file_path`	Yes
`new_docstring`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.7/5.0

Behavior4/5

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

No annotations are present, so the description carries full transparency burden. It covers the basic operation and language restriction, but could elaborate on overwrite behavior and potential 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.

Conciseness5/5

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

Tightly written with no wasted words. Usage guidelines, example, and constraints are presented efficiently. Front-loaded with core action.

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

Completeness5/5

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

Given the tool's simplicity and the presence of an output schema (implied), the description sufficiently covers all necessary information: action, target, language, and formatting requirements.

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

Parameters4/5

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

Schema coverage is 0%, so description adds value. It explains the new_docstring format requirement (valid Python string literal with triple quotes) and provides an example illustrating the target parameter.

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

Purpose5/5

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

The description clearly states it replaces or inserts Python docstrings on functions or classes, with explicit Python-only restriction. It distinguishes from sibling tools like replace_leading_comment.

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

Usage Guidelines5/5

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

Provides explicit 'when to use' and 'when not to use' guidance, with clear references to alternative tools and language-specific limitations.

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

replace_functionA

Replace an entire function definition with new content -- signature, body, and decorators.

Use this when: You're rewriting a function top-to-bottom (e.g., renaming it, changing parameters AND implementation together). Don't use this when: You only need to change the body -> use replace_function_body. You only need to change the signature -> use replace_signature.

Example: target="LRUCache.get" content=' def get(self, key, default=None):\n return self.items.get(key, default)'

ParametersJSON Schema

Name	Required	Description	Default
`target`	Yes
`content`	Yes
`file_path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.3/5.0

Behavior4/5

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

With no annotations, the description carries full burden. It explains the action and provides an example, but lacks details on side effects, error handling, or what happens if the target doesn't exist. Slightly above average but not fully transparent.

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

Conciseness4/5

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

The description is concise with a clear structure: purpose, usage guidelines, and example. It is well-organized but the example adds minimal overhead. Slightly above average due to efficiency.

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

Completeness4/5

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

Given the tool's simplicity and the presence of an output schema, the description covers most essential aspects. However, the omission of 'file_path' parameter explanation leaves a gap, preventing a perfect score.

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

Parameters3/5

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

Schema has 0% description coverage, so description must explain parameters. The example explains 'target' and 'content' but does not explain 'file_path'. This is a significant gap, though the example helps infer usage.

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

Purpose5/5

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

The description clearly states the tool replaces an entire function definition (signature, body, decorators). It distinguishes from sibling tools like replace_function_body and replace_signature by specifying what not to use it for.

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

Usage Guidelines5/5

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

Explicitly provides when to use (rewriting top-to-bottom) and when not to use (only body or signature changes), with named alternatives. This is excellent guidance for agent decision-making.

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

replace_function_bodyA

Replace only the body of a function, preserving its signature and decorators.

Use this when: You're changing the implementation while keeping the interface stable. Don't use this when: You're also changing parameters or return type -> use replace_signature or replace_function.

Example: target="LRUCache.get" content=' if key in self.items:\n return self.items[key]\n return None'

ParametersJSON Schema

Name	Required	Description	Default
`target`	Yes
`content`	Yes
`file_path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior4/5

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

No annotations provided, so description carries full burden. It states it preserves signature and decorators, implying no external side effects. Could mention file overwriting but still adds sufficient 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.

Conciseness5/5

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

Very concise: two short paragraphs and an example. Every sentence adds value; no wasted words.

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

Completeness5/5

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

Given many sibling tools and an output schema (not shown), the description is complete: it defines use cases, provides an example, and distinguishes from alternatives. No gaps remain.

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

Parameters3/5

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

Schema coverage is 0%, so description must add meaning. Example explains 'target' and 'content', but 'file_path' is only implied in the tool name. Basic understanding is possible, but not all parameters are explicitly described.

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

Purpose5/5

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

The description clearly states it replaces only the function body while preserving signature and decorators, using the specific verb 'Replace'. It distinguishes from sibling tools like replace_signature and replace_function by explicitly noting what is preserved.

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

Usage Guidelines5/5

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

Explicitly tells when to use (changing implementation, stable interface) and when not to (changing parameters/return type), naming alternative tools replace_signature and replace_function.

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

replace_in_bodyA

Replace a byte-identical snippet inside a named function/method body, without touching the surrounding code. The match is scoped to the target's body so accidental matches elsewhere in the file cannot happen.

Raises if the snippet is not found, or if it appears more than once in the body (include more surrounding context to disambiguate).

Use this when: You need to change a specific statement or block inside a large function body without rewriting the whole body. The single biggest token-saver for long functions with ~30 similar lines where you only want to change one of them. Don't use this when: You're replacing the entire body -> use replace_function_body. You need to change a sub-expression inside a method chain that string matching can't uniquely locate -> use the default Edit tool instead.

Example: target="init" old_snippet="viper.BindPFlag("port", cmd.Flags().Lookup("port"))" new_snippet="viper.BindPFlag("port", cmd.PersistentFlags().Lookup("port"))"

ParametersJSON Schema

Name	Required	Description	Default
`target`	Yes
`file_path`	Yes
`new_snippet`	Yes
`old_snippet`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.6/5.0

Behavior4/5

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

No annotations provided, so description carries full burden. It discloses scoping to function body to prevent accidental matches, and raises on missing/duplicate snippet. It implies mutation but doesn't explicitly state file-saving behavior; however, output schema exists to cover return values. Overall good transparency.

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

Conciseness5/5

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

Well-structured with clear sentences: purpose first, then error conditions, usage guidelines, and a concrete example. No redundant or irrelevant information; every sentence earns its place.

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

Completeness4/5

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

Given 4 required params and existence of output schema, description covers purpose, usage, error cases, and example. It does not explain return value (but output schema exists) or prerequisites (e.g., file must exist, target must be defined), but these are implied. Adequate for effective use.

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

Parameters4/5

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

Schema coverage is 0%, so description compensates by explaining each parameter: file_path, target (name of function/method), old_snippet and new_snippet (byte-identical snippets). An example illustrates usage. Could add more on file_path requirements, but sufficient for clear understanding.

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

Purpose5/5

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

The description clearly states the tool replaces a byte-identical snippet inside a named function/method body without affecting surrounding code. It distinguishes itself from sibling tools like replace_function_body (entire body replacement) and Edit (for sub-expressions in method chains).

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

Usage Guidelines5/5

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

Explicitly provides when to use (changing a specific statement in a long function) and when not to use (entire body -> use replace_function_body; sub-expression in method chain -> use Edit). Also explains error conditions (raises if not found or duplicate) and how to disambiguate (add more context).

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

replace_signatureA

Replace only the signature of a function, preserving its body and decorators.

Use this when: You're changing parameters, return type, or function name without modifying the implementation. Don't use this when: You also want to change the body -> use replace_function. You're adding/removing one parameter -> use add_parameter/remove_parameter.

Example: target="LRUCache.get" new_signature=" def get(self, key, default=None):"

ParametersJSON Schema

Name	Required	Description	Default
`target`	Yes
`file_path`	Yes
`new_signature`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.9/5.0

Behavior3/5

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

No annotations, so description carries full burden. It explains that the body and decorators are preserved. However, it doesn't mention error handling, permissions, or what happens if the target doesn't exist.

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

Conciseness5/5

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

The description is concise with only a few sentences and an example. It is front-loaded with the core action and uses bullet-like structure for usage guidelines. No wasted words.

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

Completeness2/5

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

Given 0% schema description coverage and an output schema not detailed, the description should provide more context. It lacks explicit parameter definitions and does not address return values or edge cases.

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

Parameters2/5

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

Schema coverage is 0% and the description does not explicitly define each parameter. While the example shows target and new_signature, file_path is not described. More parameter explanation is needed.

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

Purpose5/5

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

The description clearly states the tool's purpose: 'Replace only the signature of a function, preserving its body and decorators.' It specifies the verb and resource and distinguishes from siblings like replace_function.

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

Usage Guidelines5/5

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

Explicit guidance on when to use (changing parameters, return type, or function name without modifying body) and when not to use (use replace_function for body changes, add_parameter/remove_parameter for single parameter changes). Alternatives are named.

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

replace_valueA

Replace the value of an existing key in a JSON, YAML, or TOML file.

Use this when: A key already exists and you want to update its value. Don't use this when: The key doesn't exist yet -> use add_key. You're modifying an array -> use append_to_array or remove_from_array.

Example: target="project.version" content='"2.0.0"'

ParametersJSON Schema

Name	Required	Description	Default
`target`	Yes
`content`	Yes
`file_path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.6/5.0

Behavior2/5

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

No annotations provided, so the description must disclose behavioral traits. It does not mention error handling (e.g., key not found, invalid content), file system side effects, or whether the operation is destructive. This is insufficient for a file-modifying tool.

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

Conciseness4/5

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

The description is concise with a few lines and an example. Each sentence serves a purpose. However, the example could be more detailed to improve clarity.

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

Completeness2/5

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

The tool has 3 required parameters, no annotations, and an output schema (content unknown). The description lacks details on return values, error conditions, or file writing behavior, making it incomplete for a mutation tool.

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

Parameters2/5

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

Schema description coverage is 0%, so the description must fully explain parameters. It only provides an example with 'target' and 'content' but does not define them or explain 'file_path'. The example is too minimal to convey accurate parameter meaning.

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

Purpose5/5

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

The description clearly states the tool replaces the value of an existing key in JSON, YAML, or TOML files. It specifies the verb, resource, and file types, and distinguishes from sibling tools like add_key and append_to_array.

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

Usage Guidelines5/5

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

Explicitly states when to use (key exists) and when not to use (key missing or array modification), with alternative tool names. This provides clear guidance for the agent.

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

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0

Disambiguation5/5

Each tool has a clearly distinct purpose with explicit 'Use this when' and 'Don't use this when' guidance that eliminates ambiguity. For example, add_comment_before vs replace_leading_comment vs replace_docstring are carefully distinguished, and tools for different data structures (dict vs array) are separated. The descriptions create clear boundaries between overlapping operations.

Naming Consistency5/5

All tools follow a consistent verb_noun or verb_preposition_noun pattern throughout (add_comment_before, add_field, add_import, replace_function_body, etc.). The naming convention is perfectly uniform with snake_case used consistently across all 32 tools, making the tool set highly predictable and readable.

Tool Count3/5

With 32 tools, the count feels heavy for an AST editor, though each tool appears specialized. While many tools earn their place through distinct operations, the high number could overwhelm agents and suggests potential over-specialization. A typical well-scoped server might have 15-25 tools; 32 is borderline excessive but not extreme.

Completeness5/5

The tool set provides comprehensive coverage for AST editing across multiple languages and file types. It includes full CRUD operations for symbols, imports, comments, parameters, and configuration data, plus read-only analysis tools. There are no obvious gaps—every editing need appears addressed with appropriate granularity, and the domain is fully covered without dead ends.

Maintenance

ActivityMaintained

ResponsivenessSyncing

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

hithereiamaliff-mcp-nextcloudOAuth
ai.smithery
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Cloud Storage File Systems Workplace & Productivity
237
mcp-server
com.niftypm
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Project Management Communication File Systems
2
mcp COAuth
com.wix
A Model Context Protocol server for Wix AI tools
Developer Tools Content Management Systems App Automation
216
Apideck MCP A
dev.apideck.mcp
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
Developer Tools
42

Related MCP Servers

mcp-server-tree-sitter
Code Analysis Developer Tools
wrale
A
license
B
quality
F
maintenance
A Model Context Protocol (MCP) server that provides code analysis capabilities using tree-sitter, designed to give Claude intelligent access to codebases with appropriate context management.
Updated 3 months ago (2026-05-21 01:35 UTC)
26
310
MIT
code-index-mcp
Code Analysis Developer Tools Search
johnhuang316
A
license
A
quality
A
maintenance
A Model Context Protocol (MCP) server that helps large language models index, search, and analyze code repositories with minimal setup
Updated a month ago (2026-07-27 08:14 UTC)
14
1,005
MIT
@lex-tools/codebase-contextofficial
Code Analysis Developer Tools Documentation Access
lex-tools
A
license
A
quality
D
maintenance
A Model Context Protocol (MCP) server designed to easily dump your codebase context into Large Language Models (LLMs).
Updated a year ago (2025-08-02 06:43 UTC)
1
12
3
Apache 2.0
CodeAlive MCPofficial
Code Analysis RAG Systems Developer Tools
CodeAlive-AI
A
license
Not graded
quality
A
maintenance
A Model Context Protocol server that enhances AI agents by providing deep semantic understanding of codebases, enabling more intelligent interactions through advanced code search and contextual awareness.
Updated 18 days ago (2026-08-16 13:58 UTC)
88
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/kambleakash0/agent-skills'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

AST Code Editor MCP Server

Why AST Edits?

Credits

Estimated Token Savings

Supported Languages & Capabilities

Language-specific design decisions

Tools Exposed

Code editing — structural (Python, JS, TS, C, C++, Ruby, Go, Java)

Parameters & signatures

Imports & includes

Comments & docstrings

Dict/list editing (JSON, YAML, TOML, AND Python module-level dict/list literals)

Navigation & reading (read-only)

Which tool should I use?

Discovering what's in a file (do this first)

Adding new content

Modifying existing content

Removing content

Anti-patterns to avoid

Logging & Debugging

Prerequisites

Installation

Method 1: CLI Configuration (Claude Code, Codex, Gemini)

Method 2: JSON Configuration

Antigravity IDE

Using Standard Python (Fallback)

Agent Configuration (Important)

Claude Code / Claude Desktop (via @-include)

Other agents (Cursor, Codex CLI, Windsurf, Antigravity, Aider, Gemini CLI, etc.)

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

@lex-tools/codebase-contextofficial

CodeAlive MCPofficial

Latest Blog Posts

MCP directory API

Claude Code / Claude Desktop (via `@`-include)