Spatial tool reference

The canonical ngram_entity integration registers 21 spatial tools. They apply to an active ngram_ar input. Calling one from an unrelated platform does not create a spatial session. This reference follows the shipped Python schemas. Download the machine-readable definitions.

A tool can queue an action before the surface renders it. Optional capture, media, or motion features still depend on the connected browser and configured backend. See capabilities.

Movement and expression

ar_move_to

queue movement in space (walk toward user, step aside, etc.). Call from tool API when the user asks you to move or reposition. Ignored outside AR.

Parameter	Type	Required	Details
`target`	`string`	Yes	Where to move in the scene. Values: `away`, `forward`, `left`, `random`, `right`, `user`.
`speed`	`string`	No	Movement speed. Values: `fast`, `walk`.

ar_gesture

queue a physical gesture (wave, nod, point, dance, …).

Parameter	Type	Required	Details
`gesture`	`string`	Yes	Physical gesture to perform. Values: `breakdancing`, `celebrate`, `cheering`, `clapping`, `coding`, `dance`, `drunkWalk`, `enteringCode`, `explain`, `greet`, `handRaising`, `hipHop`, `macarena`, `no`, `nod`, `point`, `shrug`, `terrified`, `texting`, `thinking`, `twerking`, `twistDance`, `wave`.

ar_emote

queue a bodily emotional expression.

Parameter	Type	Required	Details
`emotion`	`string`	Yes	Emotion to express bodily. Values: `attentive`, `calm`, `concerned`, `curious`, `excited`, `happy`, `thoughtful`.
`intensity`	`number`	No	0–1 intensity.

ar_look_at

queue gaze toward the user or away.

Parameter	Type	Required	Details
`target`	`string`	Yes	Gaze target. Values: `away`, `user`.

ar_go_idle

return to a relaxed idle stance.No parameters.

ar_speak

speak mid-turn (visible + TTS) before your final reply. Use for reactions while reasoning; final answer can still go in normal reply text.

Parameter	Type	Required	Details
`text`	`string`	Yes	Words to speak in the AR surface (mid-turn).

Panels and media

ar_show_panel

show a readable spatial panel for substantial information.

Parameter	Type	Required	Details
`panel_id`	`string`	Yes	Stable panel identifier.
`content`	`string`	Yes	Panel body.
`title`	`string`	No	Optional title.
`panel_type`	`string`	No	Values: `card`, `chart`, `code`, `html`, `image`, `markdown`.

ar_hide_panel

close a spatial panel by id.

Parameter	Type	Required	Details
`panel_id`	`string`	Yes	See the action behavior above.

ar_terminal

write a concise status or result to the spatial terminal.

Parameter	Type	Required	Details
`output`	`string`	Yes	Short visible terminal text.
`tool`	`string`	No	See the action behavior above.
`error`	`boolean`	No	See the action behavior above.
`clear`	`boolean`	No	See the action behavior above.

ar_open_browser

open an HTTP(S) page on the spatial browser surface.

Parameter	Type	Required	Details
`url`	`string`	Yes	HTTP(S) webpage to open. Do not use this for YouTube playback; use ar_play_youtube with a specific video instead.
`title`	`string`	No	See the action behavior above.

ar_play_youtube

play a specific YouTube video in the dedicated media player. On desktop this opens the desktop player; in immersive AR the surface uses its headset-safe playback flow. Search for a specific video first when needed.

Parameter	Type	Required	Details
`video`	`string`	Yes	A specific YouTube video ID or watch URL.
`title`	`string`	No	Song or video title.
`volume`	`number`	No	Minimum: 0. Maximum: 100.
`start_at`	`number`	No	Minimum: 0.

Objects and environment

ar_spawn_object

spawn a real 3D geometric primitive. Use for requests naming a shape such as cube, sphere, cylinder, cone, torus, or plane. Physics defaults on. Do not use ar_spawn_text as a substitute for geometry.

Parameter	Type	Required	Details
`object_id`	`string`	Yes	Stable unique id for later removal.
`shape`	`string`	Yes	The actual 3D primitive to create. Use sphere for a geometric ball. Values: `cone`, `cube`, `cylinder`, `plane`, `sphere`, `torus`.
`position`	`string`	No	Values: `above`, `front`, `here`, `left`, `right`.
`color`	`string`	No	See the action behavior above.
`size`	`number`	No	Minimum: 0.03. Maximum: 2.0.
`label`	`string`	No	Optional caption; not a substitute for the shape.
`physics`	`boolean`	No	Enable gravity and collision. Defaults to true.

ar_spawn_toy

spawn an interactive physics toy. Use this for balls, bouncy balls, beach balls, dice, and marbles; use ar_spawn_object for generic geometry.

Parameter	Type	Required	Details
`object_id`	`string`	Yes	Stable unique id for later removal.
`toy_type`	`string`	Yes	Ready-made physics toy. For requests to spawn a ball, use ball or bouncy_ball. Values: `ball`, `beach_ball`, `bouncy_ball`, `dice`, `marble`.
`position`	`string`	No	Values: `above`, `front`, `here`, `left`, `right`.
`color`	`string`	No	See the action behavior above.
`impulse`	`object`	No	Optional initial velocity for tossing the toy.

ar_spawn_text

place visible lettering in the scene. Use only when the user asks for text or a label; never use it to represent a requested physical object or shape.

Parameter	Type	Required	Details
`object_id`	`string`	Yes	See the action behavior above.
`text`	`string`	Yes	See the action behavior above.
`position`	`string`	No	Values: `above`, `front`, `here`, `left`, `right`.
`color`	`string`	No	See the action behavior above.
`size`	`number`	No	Minimum: 0.2. Maximum: 4.0.

ar_remove_object

remove one previously spawned object, toy, text, image, or model by id.

Parameter	Type	Required	Details
`object_id`	`string`	Yes	See the action behavior above.

ar_clear_objects

clear all spawned scene objects when the user asks to reset or clean the space.No parameters.

ar_draw_annotation

place a labeled callout at scene coordinates.

Parameter	Type	Required	Details
`drawing_id`	`string`	Yes	See the action behavior above.
`text`	`string`	Yes	See the action behavior above.
`x`	`number`	Yes	See the action behavior above.
`y`	`number`	Yes	See the action behavior above.
`z`	`number`	Yes	See the action behavior above.
`color`	`string`	No	See the action behavior above.

ar_set_environment

change the shell’s environment preset.

Parameter	Type	Required	Details
`preset`	`string`	Yes	Values: `cozy`, `default`, `focus`, `nature`, `night`, `party`, `space`, `workshop`.

Inspection and optional backends

ar_inspect_surface

inspect the current embodied surface contract, live context, and available spatial API tools. Use this instead of scanning workspace files when asked what the spatial body can do.No parameters.

ar_request_capture

ask the user-controlled surface for a current view image.

Parameter	Type	Required	Details
`prompt`	`string`	No	See the action behavior above.

ar_generate_motion

request a novel humanoid motion from the configured external GPU provider. Use only when generated motion adds clear value.

Parameter	Type	Required	Details
`prompt`	`string`	Yes	Physical motion to generate.
`duration_seconds`	`number`	No	Minimum: 0.5. Maximum: 30.0.
`root_target`	`string`	No	Values: `forward`, `left`, `right`, `stationary`, `user`.
`loop`	`boolean`	No	See the action behavior above.

Design for the current surface

Use primitives for geometry and text tools for lettering. Use ar_spawn_toy for prepared physics objects, and ar_play_youtube for a specific video rather than opening a YouTube search page in the browser panel. ar_terminal displays text; it does not execute a shell command. ar_request_capture requests a rendered surface frame; it does not establish access to passthrough cameras. ar_generate_motion needs a configured external motion provider.

Getting started

Build

Reference

Spatial tool reference

Movement and expression

Panels and media

Objects and environment

Inspection and optional backends

Design for the current surface

​Movement and expression

​Panels and media

​Objects and environment

​Inspection and optional backends

​Design for the current surface

Movement and expression

Panels and media

Objects and environment

Inspection and optional backends

Design for the current surface