Skip to main content
Glama

raycast

Read-only

Cast a ray through PhysX to find which collider lies along a line, returning its prim, hit point, surface normal and distance, or no hit.

Instructions

Cast a ray through PhysX and return the closest collider it hits: its prim, the hit point, the surface normal and the distance in stage units, or "No hit".

Use it to find what lies along a line, such as the ground under a point or what a robot faces; get_prim_bounds measures a prim you already know. Only colliders (the Collision API, which set_physics_properties' collision=True or create_prim's enable_physics adds) are hit, not plain meshes. PhysX needs to know the scene: play or step the simulation once first, or it may find nothing, or fail. The prim named is the rigid body hit, or a static collider itself.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "origin": "<origin>",
      "direction": "<direction>"
    },
    "name": "raycast"
  }
}

Input Schema

NameRequiredDescriptionDefault
originYes[x, y, z] start point in world space
directionYes[dx, dy, dz] direction in world space, of any length but zero
max_distanceNoThe longest the ray goes, in stage units

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.4.1
    • changedInput schema / properties / direction / description
      Previous value: -"[dx, dy, dz] direction in world space, a unit vector: PhysX takes it as given"New value: +"[dx, dy, dz] direction in world space, of any length but zero"
  2. Changed3 schema fields changedv0.2.3
    • changedInput schema / properties / direction / description
      Previous value: -"[dx, dy, dz] direction; it is normalised"New value: +"[dx, dy, dz] direction in world space, a unit vector: PhysX takes it as given"
    • changedInput schema / properties / max_distance / description
      Previous value: -"The longest the ray goes"New value: +"The longest the ray goes, in stage units"
    • changedInput schema / properties / origin / description
      Previous value: -"[x, y, z] start point"New value: +"[x, y, z] start point in world space"
  3. First observedv0.2.2

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already declare readOnlyHint=true, and the description goes well beyond them: only colliders registered with the Collision API are hit, not plain meshes, and the sim must be stepped first or the call may return no hit or fail. It also explains that the returned prim is the rigid body hit or a static collider itself.

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

Conciseness4/5

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

The description is front-loaded with the operation and return contract, then follows with alternatives and prerequisites. Three paragraphs is slightly more than needed, but each carries distinct, non-redundant information.

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

Completeness5/5

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

Given a simple three-parameter tool with an output schema, the description covers behavior, prerequisites, filtering (colliders only), and failure modes. Nothing an agent needs to call it correctly is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning by specifying that the returned distance is in stage units, tying the ray result back to max_distance semantics. It does not re-explain origin or direction, which the schema already documents fully.

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 verb+resource pair ('Cast a ray through PhysX') and enumerates the exact return values: prim, hit point, surface normal, distance, or 'No hit'. It distinguishes itself from get_prim_bounds, which is a different operation on a known prim.

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

Usage Guidelines5/5

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

It names concrete use cases ('find what lies along a line, such as the ground under a point or what a robot faces') and explicitly contrasts with the alternative get_prim_bounds. It also states the precondition that the simulation must be played or stepped once first, otherwise it may find nothing or fail.

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