ast-editor

Overview Schema Source Related Servers Discussions Admin

add_import_name

Adds a named import to an existing Python or JS/TS named-import statement, placing it in sorted order or at the end while leaving existing names unchanged.

Instructions

Add a name to an existing from <module> import ... (Python) or import { ... } from "<module>" (JS/TS) statement; a name already there is left as is. It goes at its sorted place when the names are sorted (plainly or as isort and ruff sort them), else at the end, in the list's layout: names one per line give it a line of its own, an inline list stays inline. Refused when the file has no such import.

Use this when: the module is already imported with named imports. Don't use this when: there is no such import yet, or for a default or namespace import (add_import with the full line).

Example (from typing import Any, cast becomes Any, Dict, cast): module="typing" name="Dict"

Tool call template

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

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "file_path": "<file_path>",
      "module": "<module>",
      "name": "<name>"
    },
    "name": "add_import_name"
  }
}

Input Schema

Name	Required	Description
`name`	Yes	One imported name, e.g. 'Optional'.
`module`	Yes	Module of the import as written, without quotes (e.g. 'typing' or './utils').
`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.

Changed3 schema fields changedv3.2.0Nov 1, 2026

addedInput schema / properties / file_path / description

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

addedInput schema / properties / module / description

Added value: +"Module of the import as written, without quotes (e.g. 'typing' or './utils')."

addedInput schema / properties / name / description

Added value: +"One imported name, e.g. 'Optional'."

First observedv1.2.0Apr 12, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only declare the generic mutating-but-non-destructive profile; the description adds real behavior: idempotency ('a name already there is left as is'), the exact insertion position (sorted place per isort/ruff, else end), layout preservation (one-per-line vs inline), and the failure mode ('Refused when the file has no such import'). That is precisely the context the annotations cannot carry.

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

Conciseness4/5

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

Front-loaded with the core action, then structured into when/when-not and a worked example, so an agent can stop reading once it has what it needs. The placement/layout paragraph is long but each clause changes behavior; the only marginal cost is the explicit example block.

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 3-required-param mutation tool, the description covers preconditions, insertion semantics, failure behavior, and forwarding to the sibling tool; an output schema exists so return values need no explanation. Nothing an agent needs to call this correctly is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3; the description goes further by grounding all three parameters in a concrete before/after example (`from typing import Any, cast` -> `Any, Dict, cast`) with module and name values, which demonstrates the 'as written, no quotes' convention in practice. It does not, however, say anything about file_path beyond what the schema already states.

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?

Specific verb+resource: adds a single name to an existing named-import statement, with the exact syntax for both Python and JS/TS spelled out. It is clearly distinguished from the siblings add_import (full line / default / namespace imports) and remove_import_name (the inverse operation).

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?

Has explicit 'Use this when' and 'Don't use this when' sections, and names the alternative tool (add_import with the full line) plus the precondition that the module is already imported with named imports. The refusal case (no such import) is stated as a routing signal, not left to inference.

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