Skip to main content
Glama
Sign In
o3de-mcp

o3de-mcp

by nickschuetz
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

create_entity

Creates a new entity in the current O3DE level. Specify a name and optional parent ID to add objects and build hierarchies.

Instructions

Create a new entity in the current O3DE level.

Tries the AiCompanion gem's native create_entity request first (gem 0.5.0 or later, works in the gem's secure mode) and returns its JSON verbatim: {"entity_id": ..., "name": ..., "position": [...]}. The name is checked here with the gem's own rule (a letter first, then letters, digits, _ or -, at most 128 characters) before either path, and the gem validates the parent; a refusal is returned as an error. Older gems and the legacy transport fall back to editor Python, which prints Created entity [<id>].

Args: name: Name for the new entity. parent_id: Optional entity ID of the parent. Omit (or pass null) for root-level.

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": {
      "name": "<name>"
    },
    "name": "create_entity"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameYes
parent_idNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.6.0
    • removedInput schema / properties / parent_id / anyOf
      Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
    • changedInput schema / properties / parent_id / default
      Previous value: -nullNew value: +""
    • addedInput schema / properties / parent_id / type
      Added value: +"string"
  2. First observedv0.3.0

TDQS

A3.6/5.0
Behavior4/5

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

With no annotations provided, the description carries the full behavioral burden and does so well: it discloses the native gem path first, secure-mode support, verbatim JSON return, the exact name-validation rule, parent validation by the gem, error-on-refusal behavior, and a legacy Python fallback with its specific output string. It does not cover reversibility (undo) or any permission requirements beyond secure mode, keeping it from a 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?

The purpose is front-loaded in the first sentence, followed by the transport/validation behavior and an Args block. It is a little long for a two-parameter tool because of the gem-version history, but nearly every sentence conveys real behavioral information.

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 mutation tool with no annotations but a present output schema, the description covers validation, error behavior, and both invocation paths adequately; the return-value recap is redundant given the output schema. The remaining gap is the absence of any level/context prerequisite and reversibility note.

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 0%, so the description must compensate, and it meaningfully does: it defines parent_id's omit-or-null root-level semantics and supplies a concrete name-validation rule the schema omits. The name parameter itself is only described tautologically, and the stated null semantics sit slightly oddly against the schema's empty-string default.

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?

States a specific verb and resource ("Create a new entity in the current O3DE level") that clearly separates it from delete_entity or duplicate_entity by implication. It is easy to identify what the tool produces, but it never names or contrasts with the closest siblings, so it stops just short of full sibling differentiation.

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

Usage Guidelines2/5

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

The description explains implementation paths and transport fallbacks but gives no when-to-use guidance, no prerequisites (e.g. an active level must be loaded), and no direction toward alternatives like duplicate_entity or instantiate_prefab. The only actionable direction is the parent_id omit/null note, which is parameter-level, not usage-level.

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