list_entities

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

With no annotations provided, the description carries the full burden of behavioral disclosure and does state the return shape ('JSON array of objects with 'id' and 'name' fields'), which is the key behavior an agent needs. It does not address edge conditions like calling with no level open or whether hidden entities are included, but for a simple read-only list operation the core behavior is transparent.

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

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

The description is two tight, front-loaded sentences with zero filler. The action verb and scoping appear first, and the return-format note occupies a single short sentence that earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter read-only listing tool with an output schema present, the description covers the essentials: scope and return shape. Minor gaps remain around failure behavior when no level is open and how this tool relates to entity-focused siblings, but nothing blocks a correct first call.

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

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

The tool takes zero parameters, so the baseline of 4 applies — there is no parameter semantics for the description to clarify. The 'currently open O3DE level' wording functions as an execution-context constraint rather than a call argument, which is appropriate given the empty input schema.

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

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

The description uses a specific verb ('List'), names the resource ('entities'), and scopes it to 'the currently open O3DE level.' Within a large sibling set that includes create_entity, delete_entity, duplicate_entity, and list_levels, a read-only entity listing is unambiguously distinct without needing to open any schema.

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

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

The description implies its use case — enumerate all entities in the current level — but names no alternatives, exclusions, or prerequisites. An agent receives no routing guidance such as preferring get_entity_components for per-entity detail, so the context is clear but not explicit.

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