Skip to main content
Glama

Physics layers and masks: who detects whom

godot_collisions
Read-onlyIdempotent

Diagnose Godot physics collision layers and masks offline: find undetected bodies, areas, rays, or TileSet layers and get the exact mask value to fix failing collisions.

Instructions

The physics layers of the project, read from its scenes, offline. Use it when something falls through the floor, a bullet or pickup is not detected, body_entered never fires, or before you set any collision_layer or collision_mask. Without arguments: per physics world (2D, 3D) every layer in use with its name and bit value, how many nodes are on it and how many scan it; every body, area, ray and TileSet physics layer with its layers and mask as numbers, names and value (instances and inherited scenes resolved); and what can never work: a mask that scans a layer nothing is on (also the classic collision_mask = 3 meant as layer 3, which is the value 4), an area or ray with mask 0, an Area with monitoring off whose body_entered is connected, a body or area without a collision shape, a CollisionShape without a shape; plus the lines of code that change layers. between: [a, b] (node names or paths, scenes, class_names or Godot classes): for each pair, whether a detects b and b detects a, why, and the exact mask value that fixes it. value says which layers a bit value means, layers the value of layer numbers. It is an error when there are problems. Read-only.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "godot_collisions"
  }
}

Input Schema

NameRequiredDescriptionDefault
pathNoproject folder, or a file or folder inside it (relative to the server's folder; default: the current project)
valueNoa collision_layer or collision_mask value: which layers it means
detailNobrief (capped lists) or full (everything); default full
layersNolayer numbers (1 to 32): the value to write
betweenNotwo names: who detects whom, e.g. ["Player", "Enemy"] or ["bullet.tscn", "Hurtbox"]

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.8.0

TDQS

A4.6/5.0
Behavior5/5

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

Goes well beyond the readOnly/idempotent annotations: it discloses that the read is offline from scenes, that inherited scenes and instances are resolved, exactly which dead-mask classes it flags (mask 0, monitoring off with body_entered connected, shape-less nodes, the mask=3-meant-as-layer-3 trap), and that problems are surfaced as an error. This is the kind of behavioral context annotations cannot carry.

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?

Front-loads the identification sentence, then the trigger symptoms, then the default output, then the parameter modes. It is long and the third sentence is a dense run-on list, but each clause carries distinct information an agent needs to predict output.

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?

With no output schema, the description takes on full responsibility for describing return values, and it does: per-world layer inventory with bit values and node counts, per-node layer/mask rendering, the list of impossible configurations, and the pairwise detection verdict. Nothing material is missing for a 5-parameter diagnostic tool.

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 real meaning: `between` accepts node names, paths, scenes, class_names or Godot classes and returns bi-directional detection plus the exact mask value that fixes it; `value` and `layers` are explained as inverse bit-value/layer-number conversions. Only `detail` and `path` are left to 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?

States a specific verb and resource ('The physics layers of the project, read from its scenes, offline') and names the exact artifacts it covers: bodies, areas, rays, TileSet physics layers, masks, and dead masks. An agent can distinguish this diagnostic tool from inspection/editing siblings like godot_check or godot_project_edit without opening the schema.

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

Usage Guidelines4/5

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

Gives concrete triggering symptoms ('something falls through the floor', 'body_entered never fires') and a preventative case ('before you set any collision_layer or collision_mask'), which is strong when-to-use guidance. It stops short of naming alternative tools or when not to use it, so it is clear context rather than full routing.

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