Skip to main content
Glama
Sign In
ast-editor

ast-editor

by kambleakash0
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

add_top_level

Add a function, class, or constant at a file's top level—after the preamble or at the end inside include guards—with correct indentation and spacing.

Instructions

Add top-level code (a function, class, constant or other statement) to a source file. "bottom" appends it at the end, inside a header's include guard; "top" puts it after the preamble, before the first declaration. It is set apart by a blank line, two around a Python def or class, but one-line code added at the bottom under stacked one-line code is stacked too. In Go, or a file indented with tabs, its indentation becomes tabs.

Use this when: adding a top-level symbol or statement. Don't use this when: placing it next to a symbol (insert_sibling), in a class (add_method, add_field), in a body (insert_in_body) or in a config file (add_key).

Example: content="MAX_CONNECTIONS = 10" position="top"

Input Schema

NameRequiredDescriptionDefault
contentYesTop-level code, inserted as written; read_symbol's text of a nested symbol is moved to column 0 as a whole.
positionNo'bottom' (default) at the end of the file; 'top' after the preamble (package clause, `#!` and magic comments, module docstring, directives such as 'use strict', imports and includes). Other values are refused.bottom
file_pathYesAbsolute path to the source or config file.

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv3.2.0
    • addedInput schema / properties / content / description
      Added value: +"Top-level code, inserted as written; read_symbol's text of a nested symbol is moved to column 0 as a whole."
    • addedInput schema / properties / file_path / description
      Added value: +"Absolute path to the source or config file."
    • addedInput schema / properties / position / description
      Added value: +"'bottom' (default) at the end of the file; 'top' after the preamble (package clause, `#!` and magic comments, module docstring, directives such as 'use strict', imports and includes). Other values are refused."
  2. First observedv2.0.1

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so safety is covered; the description adds real behavioral detail beyond that — placement inside a header's include guard for 'bottom', blank-line separation rules, and tab conversion in Go or tab-indented files. It stops short of stating what happens on conflicts (e.g., duplicate symbol names) or failure modes, which keeps it at 4 rather than 5.

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 verb and resource, then positions, then use/don't-use, then an example — a sensible ordering. The blank-line and tab-indentation rules are somewhat dense, but each sentence describes observable behavior an agent would otherwise get wrong, so little is wasted.

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?

With an output schema, full annotations, and 100% parameter coverage, the description need only cover placement semantics and sibling routing — and it does both, including language-specific formatting behavior. Nothing required to invoke the tool 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, but the description adds placement nuance not fully in the schema — that 'bottom' lands inside an include guard and 'top' goes after the preamble but before the first declaration — plus a concrete example of content/position usage. The content parameter's column-0 behavior is left to the schema, which already documents it.

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 verb and resource ('Add top-level code ... to a source file') and enumerates what counts as top-level (function, class, constant, other statement). It also disambiguates from sibling tools by naming them, so an agent can distinguish it from insert_sibling or add_method without opening a schema.

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 each exclusion routed to a named alternative (insert_sibling, add_method, add_field, insert_in_body, add_key). The condition that selects this tool versus each alternative is spelled out, leaving nothing to inference.

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

Deploy Server

Other Tools