game_physics_2d

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

No annotations are provided, so the description carries the full burden. 'Queries' and 'intersections' imply non-destructive checks, which is helpful, but the description does not disclose whether calling this tool mutates anything, whether the physics engine or scene must be running, what happens on a miss, or what the result payload looks like. For an unannotated tool this is a significant disclosure gap.

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 one front-loaded sentence with zero filler: it states the domain (2D), the target resource (Area2D), and the operation class (queries/intersections). It is genuinely concise, though borderline under-specified — it reads more like a label than an operational guide.

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 tool with 5 parameters, one free-text action field with four distinct modes, nested objects, no output schema, and no annotations, the description is too thin. It does not explain return values (critical absent an output schema), does not map which parameters are required per action (ray needs from/to, overlap needs nodePath), and does not flag the direct overlap with the game_raycast sibling.

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 100%, so the baseline is 3 and the schema already documents every parameter including the four action modes and which parameter each mode needs. The description adds no meaning beyond the schema, but it does not need to given full coverage; it merely fails to compensate for nuances like the free-text action string.

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 identifies a specific verb+resource pairing: 2D intersection/query operations against Area2D nodes, and the '2D' qualifier helps separate it from game_physics_3d. However, it is terse and does not enumerate the actual operations (overlap, point_query, shape_query, ray), which only surface in the schema, and it does not distinguish itself from the overlapping sibling game_raycast.

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?

There is no guidance on when to use this tool versus alternatives. The description never mentions game_raycast (which plausibly covers the ray case), game_physics_3d, or game_physics_body, nor does it state conditions like 'use when you need a non-mutating physics probe' or any exclusions. The agent must infer usage entirely from the name and schema.

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