Skip to main content
Glama
Sign In

moddl

by site.moddl
OverviewDiscussionsAdmin

Copy elements

copy_elements

Copies elements with their openings (as their source) and fills; type and material stay shared. New revision, effect report (n_changed, rejected, cloned, carried). A call that succeeds is not a job that's done. Target: guid, guids or a set from find_elements/get_selection, never a filter. Beyond the named: PLAN_REQUIRED, run its plan_id with expect_beyond. A whole takes its parts along into its own aggregation (by or to_storey). Ports go along, each copy its own, in the rel form the file holds (Nests or HasPorts); a link between two copied elements is copied per copy, one to outside stays with the source (free_ports). Other nested parts, and a port off its element's placement or nesting a port, refuse the call, nothing copied. Offset by a vector, n times, distributed between two points, or into other storeys (same plan position). The copies get new GlobalIds and stand in the report with their source. A type object (named alone, no offset) becomes a new type of the same class: own property sets, shared RepresentationMaps, its occurrences stay; a type from nothing: create_elements with the type class.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "copy_elements"
  }
}

Input Schema

NameRequiredDescriptionDefault
nNoNumber of copies, each by the offset from the previous; more: call again from the last copy
byNoOffset of the (first) copy in m
setNoA set id from find_elements or get_selection: writes exactly the elements seen there, nothing that matches later. An element changed since reading is rejected alone; the others are written
guidNoOne element (GlobalId)
noteNoYour note, stored with the new revision
guidsNoThese elements (GlobalIds)
sourceNoWhere the values you write come from: assumption (default, your own estimate, stamped in the file) or user (only what the person named word for word; it then reads as the file does)
betweenNon copies evenly between these bounds, none on them: body centres at from + k*(to-from)/(n+1), in plan; heights stay
dry_runNoPreview: the planned effect and a plan_id, nothing written
plan_idNoExecute exactly the plan a dry_run returned, all or nothing; the plan holds target and fields. Plans that clone the same shared object (type, material) run one after the other: plan the second after the first ran, else PLAN_CHANGED
to_storeyNoCopy into this storey (Name or GlobalId), height follows its Elevation; a list: one copy into each, in one revision
attributesNoIFC attributes of the created element: Name, Description, Tag ...
request_idNoYour id for this call: a repeat answers the first result and writes nothing
expect_countNoWith set: how many elements the set holds - guards against a mixed-up set id
expect_beyondNoWith plan_id: how many elements the plan reaches beyond those named (n_beyond of PLAN_REQUIRED or the dry_run)
expect_contactsNoIntended contacts: checks.contacts splits into as_expected, missing, surprises; an omitted kind is not judged

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.1/5.0
Behavior5/5

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

Annotations only declare the generic non-read-only, non-idempotent, non-destructive profile; the description adds far more: a new revision is created, the effect report shape (n_changed, rejected, cloned, carried), new GlobalIds, and exactly which structural cases cause a refusal with 'nothing copied'. It also discloses non-obvious semantics for ports, nests/rel forms, and links between copied vs outside elements (free_ports). That is substantial behavior beyond the annotation set.

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

Conciseness3/5

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

It is information-dense and largely front-loaded, but it reads as a chain of telegraphic clauses with unexplained jargon ('the rel form the file holds', 'a port off its element's placement'), and the sentence 'A call that succeeds is not a job that's done' is vague filler. Grouping the refusal cases and the offset modes into clearer statements would reduce re-reading.

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?

For a 16-parameter mutation tool with no output schema, the description covers the main behavioral axes: what is cloned vs shared, where copies land, refusals, and the dry_run/plan_id loop, plus the report field names. It leaves several secondary parameters (source, attributes, request_id, expect_contacts) undocumented, but they are adequately covered in the schema.

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 100% schema coverage the baseline is 3, but the description adds real meaning: it explains that offset can be a vector, repeated n times, 'distributed between two points', or a storey change with 'same plan position', which disambiguates the interaction of by/n/between/to_storey. It also ties expect_beyond to the PLAN_REQUIRED flow. Some parameters (attributes, request_id, expect_contacts, source) get no mention, keeping it out of 5 territory.

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

Purpose4/5

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

The first clause gives a specific verb and resource ('Copies elements with their openings ... and fills') plus the key invariant that type and material stay shared. It also routes away from a sibling ('a type from nothing: create_elements with the type class'), so it is distinguishable from create/change_class. It stops short of explicitly contrasting with move_elements/mirror_elements, which an agent could confuse with a copy.

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

Usage Guidelines4/5

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

It gives concrete targeting rules ('guid, guids or a set from find_elements/get_selection, never a filter') and a workflow rule for out-of-scope elements ('PLAN_REQUIRED, run its plan_id with expect_beyond'). It also names a specific precondition failure mode for nested parts and ports. What is missing is any explicit 'use move_elements/rotate_elements instead when you want the original gone' exclusion.

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

All moddl toolsInspect
Try in Browser
Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources