> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ngram.space/llms.txt
> Use this file to discover all available pages before exploring further.

# Spatial tool reference

> Exact parameters for the 21 spatial tools exposed by the canonical Entity integration.

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](/assets/spatial-tools.json).

<Note>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](/spatial/capabilities).</Note>

## Movement and expression

<AccordionGroup>
  <Accordion title="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`.                                                   |
  </Accordion>

  <Accordion title="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`. |
  </Accordion>

  <Accordion title="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.                                                                                                    |
  </Accordion>

  <Accordion title="ar_look_at">
    queue gaze toward the user or away.

    | Parameter | Type     | Required | Details                              |
    | --------- | -------- | -------- | ------------------------------------ |
    | `target`  | `string` | Yes      | Gaze target. Values: `away`, `user`. |
  </Accordion>

  <Accordion title="ar_go_idle">
    return to a relaxed idle stance.

    No parameters.
  </Accordion>

  <Accordion title="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). |
  </Accordion>
</AccordionGroup>

## Panels and media

<AccordionGroup>
  <Accordion title="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`. |
  </Accordion>

  <Accordion title="ar_hide_panel">
    close a spatial panel by id.

    | Parameter  | Type     | Required | Details                        |
    | ---------- | -------- | -------- | ------------------------------ |
    | `panel_id` | `string` | Yes      | See the action behavior above. |
  </Accordion>

  <Accordion title="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. |
  </Accordion>

  <Accordion title="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.                                                                                      |
  </Accordion>

  <Accordion title="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.                               |
  </Accordion>
</AccordionGroup>

## Objects and environment

<AccordionGroup>
  <Accordion title="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.                                                                                     |
  </Accordion>

  <Accordion title="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.                                                                                                 |
  </Accordion>

  <Accordion title="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.                        |
  </Accordion>

  <Accordion title="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. |
  </Accordion>

  <Accordion title="ar_clear_objects">
    clear all spawned scene objects when the user asks to reset or clean the space.

    No parameters.
  </Accordion>

  <Accordion title="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. |
  </Accordion>

  <Accordion title="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`. |
  </Accordion>
</AccordionGroup>

## Inspection and optional backends

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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. |
  </Accordion>

  <Accordion title="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.                            |
  </Accordion>
</AccordionGroup>

## 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.