godot-omni

Overview Schema Source Related Servers Discussions Admin

physics_query_manage

Perform Godot physics queries: cast 2D/3D rays, check point and shape overlaps, and simulate shape motion to detect collisions and retrieve hit results.

Instructions

Direct 2D and 3D Physics Space State Raycasts, Point Overlaps, and Shape Queries.

Ops:

intersect_ray_3d(from_pos=[0.0, 0.0, 0.0], to_pos=[0.0, -10.0, 0.0], collision_mask=0xFFFFFFFF, collide_with_bodies=True, collide_with_areas=False) Cast a ray in 3D world space and return hit position, normal, and collider.
intersect_ray_2d(from_pos=[0.0, 0.0], to_pos=[0.0, 100.0], collision_mask=0xFFFFFFFF, collide_with_bodies=True, collide_with_areas=False) Cast a ray in 2D world space and return hit position, normal, and collider.
intersect_point_3d(position=[0.0, 0.0, 0.0], max_results=32, collision_mask=0xFFFFFFFF) Query 3D colliders overlapping a point in world space.
intersect_point_2d(position=[0.0, 0.0], max_results=32, collision_mask=0xFFFFFFFF) Query 2D colliders overlapping a point in world space.
intersect_shape_3d(shape_type="sphere", radius=1.0, max_results=32) Query 3D colliders overlapping a shape in world space.
cast_motion_3d(shape_type="sphere", radius=1.0, motion=[0.0, -1.0, 0.0]) Simulate shape motion to determine safe and unsafe collision fractions.

Canonical call shape: {"op": "<verb>", "params": {...}}. Flat op parameters are accepted as a compatibility alias when the client transmits them; op and session_id remain top-level.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`op`	Yes
`params`	No
`session_id`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Addedv5.0.28Sep 23, 2026

TDQS

A4.1/5.0

Behavior3/5

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

No annotations are present, so the description carries full responsibility for disclosing behavior. It does state that these are state queries (raycasts, overlaps, shape queries) which implies read-only operations, and it describes return information ('hit position, normal, and collider'). However, it doesn't explicitly declare non-destructiveness, permission requirements, or side effects. It also notes a compatibility alias for flat parameters, which is useful. Overall, it provides moderate behavioral disclosure but leaves gaps around reversibility and error behavior.

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

Conciseness5/5

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

The description is well-organized using a bulleted list of ops, each with a compact signature and description. It front-loads the overall purpose, then enumerates ops in a structured manner, and ends with the call-shape note. There is no redundant text; every line contributes to understanding. Despite the length (six ops), it remains efficient and scannable.

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?

Given the tool's complexity (six ops, varying parameter sets), the description is quite complete. It covers all ops, their parameters, and basic purpose. The output schema exists (not shown but indicated), so the description need not detail return formats. It does not mention error handling or performance caveats, but for query operations these are less critical. The only minor gap is that it doesn't specify parameter types explicitly (e.g., array of floats), though examples strongly imply them. Overall, it provides sufficient information for an agent to call the tool correctly.

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

Parameters5/5

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

Schema description coverage is 0%, so the description is the only source for parameter meaning. It compensates thoroughly by listing each op's parameters with default values (e.g., from_pos=[0.0, 0.0, 0.0], collision_mask=0xFFFFFFFF) and a one-line explanation. This is essential for correct invocation since the schema's 'params' is a generic object. The description also explains the canonical call structure, which clarifies how parameters are passed. This is high-value semantics beyond the schema.

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

Purpose5/5

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

The description opens with a precise purpose: 'Direct 2D and 3D Physics Space State Raycasts, Point Overlaps, and Shape Queries.' It then enumerates six specific ops (intersect_ray_3d, intersect_ray_2d, etc.), each with clear verbs and targets. This fully distinguishes the tool from siblings like physics_manage (general physics management) and nav_query_manage (navigation queries) without needing to open schemas.

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

Usage Guidelines3/5

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

The description implicitly communicates usage by listing the operations it supports, but it never explicitly states when to choose this tool over alternatives or when not to use it. Sibling tools like physics_manage and nav_query_manage exist, and the description provides no comparative guidance. Usage context is implied rather than stated, which is adequate but not fully explicit.

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

Deploy Server