physics_manage

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

With no annotations provided, the description carries the full burden. It discloses the actions of each operation, including return types (e.g., 'returning collision point, normal, collider path, and shape') and side effects ('Instantiate and attach a RayCast2D or RayCast3D sensor'). However, it does not mention potential pitfalls such as prerequisites (e.g., physics space must be active), error conditions, or the reversibility of layer name changes. It is moderately transparent but incomplete.

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 well-structured as a bullet-style list of operations, with each op showing default parameters and a one-line explanation. It also includes the canonical call shape, which is essential. The length is justified by the multi-operation nature, and it is front-loaded with the overall purpose. Minor waste: the backticks around params and session_id add little.

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 all the relevant operations and provides the call format. It does not elaborate on return structures for all ops (e.g., query_point_2d) but the output schema exists, so that burden is reduced. For a tool that bundles 8 operations, the description is sufficiently complete to get started, though more details about error handling and edge cases would help.

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 schema has 0% description coverage, so the description must compensate. It includes default values for parameters and brief contextual explanations per operation, but it does not define each parameter's meaning (e.g., 'collision_mask', 'hit_from_inside', 'max_results'). The operation summaries give some context (e.g., what is returned), but not enough for an agent to adjust parameters confidently without extra knowledge. It adds value but under-explains.

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 clearly enumerates multiple specific physics operations (raycast, point query, sensor scaffold, layer names), each with a clear verb and resource. It distinguishes this tool as the physics query and scaffolding manager. While there is a sibling 'physics_query_manage', the description's explicit operation list makes the purpose unambiguous.

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 a clear sense of what each operation does, but it does not explicitly discuss when to prefer this tool over alternatives like physics_query_manage, nor does it provide any exclusions or conditions. The usage context is implied by the operations but not contrasted with siblings, leaving the agent to infer the boundary.

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