spatial_scene_overview

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

With no annotations supplied, the description carries the full behavioral burden and does disclose the important traits: the operation is read-only, scope selection has precedence, and ambiguous local bounds fail closed. It does not explain default behavior for include_hidden, filter interactions, or sample inclusion, but the read-only and fail-closed guarantees are the most safety-relevant details.

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 definition front-loads the core purpose, adds a KB pointer, explains the central parameter semantics, and ends with a concrete example. It is compact and every sentence serves a purpose, though some phrasing like 'resolve explicit local content bounds' is jargon-heavy.

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?

The description covers the main scoping mechanism and failure mode, and an output schema exists, which lowers the burden of explaining return values. Given the six optional parameters and the large sibling list of spatial read tools, it leaves gaps around how filters and boolean parameters combine and when spatial_scene_overview should be chosen over spatial_query_actors or get_actors_in_level.

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?

Schema description coverage is 0%, so the description must compensate. It explains local_actor_query richly, covering labels, names, classes, paths, tags, and asset paths, and it shows limit in the example. However, the other five parameters—tag_filter, class_filter, include_hidden, include_actor_samples, and the limit default—are left to inference from their titles.

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 opening sentence states a concrete action and target: 'Summarize live level actors and resolve explicit local content bounds.' This distinguishes it as an overview/read operation rather than a mutation or spawn tool, but it does not explicitly differentiate it from sibling read tools like spatial_query_actors or get_actors_in_level.

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 gives clear scoping rules: local_actor_query establishes a read-only local scope, selection takes precedence, and absence of a query or exactly one Ghost.RoomBounds actor fails closed as ambiguous. It also includes a concrete invocation example. It does not name alternatives or state when not to use the tool, so it stops short of a 5.

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