# Grid-agent perception tools

The grid agent exposes compact read-only projections of state that the existing
native managers have already observed. A tool call never starts a directory
search, fetches an asset, selects an object, accepts inventory, sends a packet,
or mutates the world. The snapshot boundary is enabled only after the native
event queue reports readiness and is fenced by both session generation and
region UUID.

Every result has `schema_version`, `tool`, `generation`, `region_id`,
`observed_unix_millis`, `freshness`, `trust`, and `provenance`. `freshness` is
`observed` for a new snapshot and `cached` for a snapshot reused within the
two-second TTL. Missing manager facts are structured `{ "status": "unknown",
"reason": "manager_cache_unavailable" }` values. Deterministic distances and
cardinal directions are declared as derived fields; `model_inference` is always
`none`. Names, descriptions, hover text, parcel text, and inventory paths are
marked `untrusted_observed_data`, stripped of controls and URL-shaped tokens,
and limited to 256 UTF-8 bytes.

All eight tools are registered as policy capability `Informational`, risk
`ReadOnly`, idempotent, fixed cost one tool call, with no approval. The five
world-state tools may be offered to public chat and IM. Inventory search,
received landmarks, and recent participants are owner-private projections and
are exposed only to authorized IM, authenticated local operators, or explicitly
granted scheduler runs. The interaction intent filter further narrows which
informational tools a particular conversation may see.

| Tool | Arguments | Result projection | Example |
| --- | --- | --- | --- |
| `world_location` | `{}` | region name and agent position | `{"generation":4,"region_id":"…","position":{"x":128,"y":64,"z":24}}` |
| `agent_state` | `{}` | agent UUID, position, health, sitting local ID | `{"health":100,"sitting_on_local_id":{"status":"unknown","reason":"manager_cache_unavailable"}}` |
| `nearby_avatars` | optional `radius_meters`, `page`, `page_size` | UUID, name, position, distance, direction | `{"items":[{"name":"A Resident","distance_meters":3.2,"direction":"north"}]}` |
| `visible_objects` | optional `radius_meters`, `page`, `page_size` | non-attachment UUID/local ID, safe text, position and scale | `{"items":[{"name":"Cube","local_id":12,"trust":"untrusted_observed_data"}]}` |
| `parcel_environment` | `{}` | safe current parcel fields and cached terrain/environment facts | `{"parcel":{"status":"observed","area":512},"environment":{"water_height":20,"terrain_height":24}}` |
| `inventory_search` | required `query`; optional `page`, `page_size` | cached item UUID, name, type, path and modification time | `{"items":[{"name":"Example","kind":"LSL","path":"/Scripts/Example"}]}` |
| `received_landmarks` | optional `page`, `page_size` | cached landmark inventory metadata | `{"items":[{"name":"Home","region_id":{"status":"unknown","reason":"manager_cache_unavailable"}}]}` |
| `recent_participants` | optional `page`, `page_size` | avatar UUID, channel and last-active time only | `{"items":[{"avatar_id":"…","channel":"direct_im"}]}` |

Radius is limited to 256 metres, page size to 20, page number to 1,000,
inventory queries to 128 bytes, each source collection to 2,048 entries, and
each encoded result to 32 KiB. Ordering is distance then UUID for world items,
path/name then UUID for inventory and landmarks, and last-active time then UUID
and channel for participants. Paged results set `source_truncated` when a native
cache contained more than the inspected bound, so a bounded total is never
presented as complete. Attachments are excluded. Owner identities,
permissions, sale data, asset and capability URLs, media URLs, raw assets,
inventory bodies, and all conversation content are absent by construction.

Snapshot capture has a three-second deadline and observes cancellation. A
disconnect, reconnect, region crossing, or generation change invalidates the
cache. Observability receives only authorization/call/tool identifiers, outcome,
duration, result byte count, and cache-hit status; arguments and result payloads
are never logged.