Detect the first object hit by a ray in world space, returning distance, point, and surface normal to find floors, ceilings, wall thickness, and free space.
Shoot one ray in world space. Returns the first object hit, the distance, the point and the surface normal. Use it to find floors, ceilings, wall thickness and free space.
| Name | Required | Description | Default |
|---|---|---|---|
| origin | Yes | ||
| direction | Yes | ||
| max_distance | No |
Changes observed during successful MCP inspections.
v0.4.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value by spelling out the return shape (hit object, distance, point, normal), which matters since no output schema exists, but it omits what happens on a miss and how max_distance truncation behaves.
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?
Two short sentences, return contract stated first and usage second, with no filler or repetition of the schema.
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 three-parameter query with annotations covering safety, the description covers purpose and return values adequately. Gaps remain on miss behavior, units, and max_distance semantics, but nothing critical to issuing a correct call is missing.
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 carries the load. 'In world space' usefully pins the coordinate space for origin and direction, but max_distance is never mentioned and neither parameter's expected shape (3-component vector vs other) or distance units are clarified.
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?
States a specific verb and resource ('Shoot one ray in world space') and enumerates the return payload (first hit, distance, point, normal), so the agent knows this is a single-ray intersection query. It does not differentiate from closely adjacent siblings like line_of_sight or viewshed, which likely answer overlapping visibility questions.
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?
Provides concrete use cases ('find floors, ceilings, wall thickness and free space'), giving the agent a clear sense of when this tool applies. It stops short of naming alternatives or exclusions, so the agent must infer the boundary with line_of_sight on its own.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.