# Wider environment state coverage and tool descriptions Issue: https://github.com/morluto/rea/issues/4933 ## Outcome The `environment-state` view backs more read tools with state, and a served environment tells agents more about each tool. Read-only paths whose responses are not entities become documents, listed items may be identified by an `…Id` or `…_id` field, an item wrapped in a one-element array is located inside it, and reads that vary by path get their own recorded reason. Each tool description says what the tool returns and which statuses were recorded, and every MCP tool carries method hints. This increment adds no tool, view kind, provider, network activity or write effect. ## Requirements - A `GET` list tool (its template does not end in a parameter) that yields no item or list plan holds its latest initial value as a `document` when its initial reads have one request line, whether or not the capture writes its path, unless its value changed between two of those reads across any recorded write (even under another root), which leaves it `fields-differ`. A value whose rendered JSON exceeds 256 KiB stays `rendered-oversize` and is replayed from the recorded body, which itself fit. More request lines give `path-varies` when they differ by path (a template with a parameter before its end) and `query-varies` when they share one path. With every such read now a document, `path-varies`, `query-varies`, `body-unusable` or `rendered-oversize`, the unreachable `not-entity` reason leaves the result schema, and `no-identity` names item tools only. A document holds the value of its one `path`. - When no path parameter proves an identity and no identity name identifies the listed items, the `field-name` identity is the first key of the first listed item, in its order, whose name ends in `Id` or `_id`, that every item carries as a distinct string or number, and that at least one initial recording shows distinct across two or more items. The last condition goes beyond "every item carries it distinctly": one item satisfies that vacuously, and a lone item's suffix-named fields are often foreign keys (a reaction keyed by its user, a comment by its post), so a list that only ever held one item stays a document. Empty recordings constrain no field. Identity names keep precedence, also when choosing among an envelope's arrays, where a suffix-named field identifies only an array of two or more items. - An item response that is a root array of exactly one object, or an object with one member holding such an array, locates its entity at `/0` or `//0` when one of the identity names in that object repeats the path value. Objects at the root or in one member keep precedence. `at` and `replaceAt` read and replace exactly these forms besides the root and one member, so the gate and renderers run unchanged. - An entity's state order is its earliest sighting on the timeline and it cites its records in timeline order, whichever plan observed it first. - Each tool description reads `METHOD template; ; recorded statuses …; replays retained records […]; evidence ev_…` after the untrusted-catalog warning. `` describes one level deep the first cited `2xx` record replay answers as JSON: an object's fields, an array of objects' fields, or an envelope whose member lists objects, where a list is an array of objects found by the state's list rule; an empty field set reads `with no fields`. Only when no `2xx` record replays as JSON does the first cited JSON record of another status give it, labelled `status returns …`; with no JSON record it is omitted. The statuses are the manifest tool's `statuses`, the one owner of that set (`no recorded status` when it is empty). Field names and statuses are sampled within the description sample budget and charged with the whole description to the catalog reservation before it is retained. One owner in the environment source classifies each retained body as none, base64, cut, JSON or text; replay answers from that classification and descriptions read only its JSON case. - MCP tools carry `readOnlyHint` (true for the safe methods `GET`, `HEAD`, `OPTIONS` and `TRACE`, and for query `POST`s), `destructiveHint: true` for `DELETE` (unset for other writes, so the MCP default applies, and for reads, where clients ignore it), `idempotentHint` (true for the safe methods, `PUT` and `DELETE`) and `openWorldHint: false`. The tool definitions own the hints and charge them to the catalog reservation; the environment card keeps its `name`, `description`, `inputSchema` tool shape. ## Acceptance and limits Synthetic captures cover read-only documents, `path-varies` and `query-varies`, suffix-named identities with their key order, their two-item proof, empty first recordings and their precedence (including the choice between an envelope's arrays), a Ghost-like `{"posts":[...]}` item under a trailing-slash path merging with its list view, a root one-element array, a one-element filtered list that stays unidentified, and the pointer forms. The Grafana-shaped fixture covers documents for its read-only paths (its one-member team list among them) and object, array and enveloped-list descriptions; synthetic sources cover the `2xx` preference over an earlier error body, the first of several JSON records, the labelled fallback, the manifest's statuses, empty, scalar and fieldless bodies, a truncated member name, a name whose JSON quoting exceeds the sample, a recorded body under 256 KiB whose rendered JSON exceeds it, non-JSON bodies and the catalog budget; the in-process and compiled MCP servers advertise the hints. A filtered list may still answer with one element whose identity name repeats the requested value; list filters, pagination, lossless big integers and cross-endpoint entity linking remain out of scope. Documents inline whole recorded values and enlarge the state result; agent tokens, CPU time and peak memory of the state and description build were not measured. ## Deferred issue criteria Serving from the state, the AgentEnv data plane and write effects remain later increments of #4933. This PR must reference rather than close the issue.