ast-editor

Overview Schema Source Related Servers Discussions Admin

edit_leading_comment

Destructive

Add, replace, or remove a symbol's leading comment block, re-indented above decorators, annotations, exports, and template headers. Use it for doc comments, not Python docstrings or in-body comments.

Instructions

Add, replace or remove the comment block directly above a symbol, its doc comment. The block sits above the symbol's decorators, annotations, export and C++ template <...> header, and a new comment goes there, re-indented to the symbol. A comment indented deeper than the symbol ends the code above and is not part of the block. A symbol that other code comes before on its line is refused. In YAML and TOML the target is a key path or a TOML [table]; JSON has no comments and is refused.

Use this when: adding, rewriting or deleting a symbol's doc comment. Don't use this when: writing a Python docstring (replace_docstring) or a comment inside a body (insert_in_body, replace_in_body).

Example: target="LRUCache.get", op="add", comment="# Return the cached value."

Input Schema

Name	Required	Description
`op`	Yes	'add' inserts a comment, refused when the symbol has one (the error quotes it: use 'replace' with a block that repeats lines to keep, such as lint directives); 'replace' replaces the block, or adds one; 'remove' deletes it. Other values are refused.
`target`	Yes	Symbol name as list_symbols lists it, dotted for nesting ('LRUCache.get'), or a YAML/TOML key path from the top level or TOML [table] name ('tool.uv').
`comment`	No	Comment text with its markers ('# note', '// note', '/** ... */'); required for 'add' and 'replace', ignored for 'remove'.
`file_path`	Yes	Absolute path to the source or config file.

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv3.2.0Oct 29, 2026

addedInput schema / properties / comment / description

Added value: +"Comment text with its markers ('# note', '// note', '/** ... */'); required for 'add' and 'replace', ignored for 'remove'."

addedInput schema / properties / file_path / description

Added value: +"Absolute path to the source or config file."

addedInput schema / properties / op / description

Added value: +"'add' inserts a comment, refused when the symbol has one (the error quotes it: use 'replace' with a block that repeats lines to keep, such as lint directives); 'replace' replaces the block, or adds one; 'remove' deletes it. Other values are refused."

addedInput schema / properties / target / description

Added value: +"Symbol name as list_symbols lists it, dotted for nesting ('LRUCache.get'), or a YAML/TOML key path from the top level or TOML [table] name ('tool.uv')."

First observedv2.0.1May 6, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations only say destructiveHint=true/readOnly=false, but the description adds the real behavioral context: indentation is rewritten to match the symbol, a comment indented deeper than the symbol terminates the code above, symbols with preceding code on their line are refused, JSON has no comments and is refused, and YAML/TOML targets are key paths or [table] names. This is exactly the mutation-risk detail the annotations cannot express.

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 scoping facts (where the block goes, indentation, refusals) come first, then the use/don't-use routing, then a compact example. Every clause carries a distinct rule; there is no filler despite the length.

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?

Output schema exists so return values need no explanation, and the description still covers all four parameters' behavior indirectly plus the language-specific edge cases (YAML/TOML/JSON) and the refusal conditions. For a destructive, file-mutating tool, an agent has everything needed to call it correctly.

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 100%, so the baseline of 3 is met by the schema alone; the description adds value by giving a worked example (`target="LRUCache.get"`, `op="add"`) that shows the dotted-symbol targeting convention in use. It does not restate `op` refusal rules or `comment` requirements, which live in the 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?

States a specific triple of operations ('Add, replace or remove') on a precisely scoped resource ('the comment block directly above a symbol, its doc comment'), with the boundary of what counts as the block spelled out (sits above decorators, annotations, `export`, C++ `template <...>` headers). An agent can immediately distinguish it from `insert_in_body`, `replace_in_body` or `replace_docstring`.

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' clauses, and the exclusions name the exact sibling tools (`replace_docstring`, `insert_in_body`, `replace_in_body`) plus the condition (Python docstring, comment inside a body) that routes the agent away. Nothing left to inference.

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