holonovel

Perception Ledger Management

manage_perception

Destructive

Record, list, or read what entities perceived—messages, scenes, observations—as an append-only ledger separate from beliefs. Use for perception tracking, not belief or lore.

Instructions

Record and read what an entity perceived — messages, scene changes, and observations — as an append-only ledger distinct from belief. Mutation (record) persists to the Novel and is audited; list/for_entity/for_event are read-only. Use when: recording that an entity perceived something (record), listing perceptions (list), or reading an entity's or an event's perceptions (for_entity/for_event). Do NOT use when: recording what an entity believes — use manage_belief; recording shared world facts — use manage_lore; recording observations for provenance — use manage_session (action: event).

Input Schema

TableJSON Schema

Name	Required	Description
`kind`	No	message, scene, or observation (record; default observation).
`action`	Yes	record, list, for_entity, or for_event.
`summary`	No	What was perceived (record).
`entity_id`	No	Entity that perceived (record/for_entity).
`event_ordinal`	No	Contributing event-log ordinal (record/for_event; defaults to the latest event).

Output Schema

TableJSON Schema

Name	Required	Description	Default
`text`	No	Human-readable text envelope mirroring the structured result (REQ-001, REQ-548a).
`status`	Yes	Machine-readable result status: OK, NEED_INPUT, WARNING, PARTIAL, or an error category (REQ-002, REQ-548c).

Schema Changelog

Changes observed during successful MCP inspections.

Addedv1.0.3Sep 29, 2026

TDQS

A4.7/5.0

Behavior4/5

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

Adds meaningful context beyond the annotations: the ledger is append-only, the record action persists to the Novel and is audited, and the read actions are side-effect free. This tells the agent which of the four actions mutate and which are safe. The only gap is a mild tension with destructiveHint=true, which an append-only ledger framing does not explain.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core purpose, then separates 'Use when' from 'Do NOT use when' in a scannable structure. The list of alternatives is dense but every clause carries routing information; no filler sentences.

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 annotations covering the safety profile and an output schema present (so return values need no explanation), the description supplies all remaining decision-critical context: scope, per-action read/write behavior, and sibling routing. Complete for an agent to select and invoke correctly.

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 description coverage is 100%, so the baseline is 3, but the description adds semantic meaning by tying the action enum values to outcomes (record persists and is audited; list/for_entity/for_event are read-only) and by characterizing the kind values. This goes beyond restating the schema field docs.

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 set (record/read) applied to a concrete resource (what an entity perceived: messages, scene changes, observations) and explicitly positions it as a ledger distinct from belief. An agent can distinguish it from manage_belief and manage_lore without opening any schema.

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

Usage Guidelines5/5

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

Provides explicit 'Use when' routing for each action (record/list/for_entity/for_event) and explicit 'Do NOT use when' clauses naming the correct alternatives (manage_belief, manage_lore, manage_session action:event). Nothing is left to inference.

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