Skip to main content
Glama

insert_sibling

Insert code before or after a named symbol at the symbol's indentation level to place helpers, constants, or related definitions directly above or below the target.

Instructions

Insert code next to a named symbol, at its level. "before" goes above the symbol's leading comment, decorators and export; "after" below the symbol (after the ; that ends a C/C++ class). The code is spaced like the gap it goes into: one-line code stacked without blank lines stays stacked, and next to a function or class it gets at least one blank line, two around a top-level Python def or class. A comment indented deeper than the target ends the code above, so "before" goes below it. "before" is refused when other code comes before the target on its line, "after" when code follows it. Refused in JSON, YAML and TOML files (use add_key).

Use this when: placing code relative to a symbol, such as a helper above its caller. Don't use this when: appending at the end of the file (add_top_level), or inserting into a body (insert_in_body) or a class (add_method, add_field).

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

Input Schema

NameRequiredDescriptionDefault
targetYesSymbol name as list_symbols lists it, dotted for nesting (e.g. 'LRUCache', 'A.m').
contentYesCode to insert, re-indented to the target's level (in tabs where the file indents with them); read_symbol's text goes in as a whole.
positionYes'before' or 'after' the target; other values are refused.
file_pathYesAbsolute path to the source or config file.

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv3.2.0
    • addedInput schema / properties / content / description
      Added value: +"Code to insert, re-indented to the target's level (in tabs where the file indents with them); read_symbol's text goes in 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: +"'before' or 'after' the target; other values are refused."
    • addedInput schema / properties / target / description
      Added value: +"Symbol name as list_symbols lists it, dotted for nesting (e.g. 'LRUCache', 'A.m')."
  2. First observedv2.0.1

TDQS

A4.8/5.0
Behavior5/5

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

Beyond the annotations (which only say this is a non-read-only, non-destructive local write), the description discloses exact placement semantics (above leading comments/decorators/export vs. below the terminating ';'), how blank-line spacing is derived from the surrounding gap, the deeper-indented-comment edge case, and two refusal conditions (code already on the line before/after the target). It also states format-level refusals (JSON/YAML/TOML) not captured by the schema.

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 rules, then when/when-not, then example — a sound structure. The spacing paragraph is dense and could be tightened, but every sentence carries operative information.

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 annotations covering safety, an output schema covering returns, and full schema coverage on all four parameters, the description only needs to supply placement semantics and refusals — which it does thoroughly. An agent has everything needed to call this correctly on the first attempt.

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 baseline is 3; the description adds real value by clarifying what 'before'/'after' mean positionally, which the schema only reduces to a string enum-like value. The example then demonstrates target/content/position concretely. It does not restate the dotted-nesting or re-indentation behavior already covered in the 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 first sentence states a specific verb (Insert), resource (code), and placement rule (next to a named symbol, at its level). It is immediately distinguishable from add_top_level, insert_in_body, add_method, and add_field, all of which are named as alternatives later.

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' blocks name the correct condition and route each wrong-condition case to a specific sibling (add_top_level, insert_in_body, add_method, add_field, add_key). There is also a worked example, so nothing is left to inference.

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