holonovel

Belief Management

manage_belief

Destructive

Track and reconcile per-entity evidence, beliefs, and perceptions to determine what an entity learned or believes, then query the results with event provenance.

Instructions

Manage per-entity evidence, reconciled belief stances, the perception ledger, and a one-entity knowledge query. admit records a subject/predicate/object proposition with a 0..1 weight and does not change a stance until reconcile recomputes it; retract removes the cited evidence and reconciles; the perception ledger is append-only, so correct a mistaken perception with a new record. Mutating actions persist to the Novel; reads are read-only. knowledge_query returns perceptions, beliefs, and known secrets with event provenance, optionally filtered by topic. Use when: inspecting or recording what an entity learned or believes. Do NOT use when: recording objective truth — use manage_causality; recording shared lore — use manage_lore.

Input Schema

Name	Required	Description
`topic`	No	Optional topic filter applied to knowledge_query perceptions, beliefs, and secrets.
`action`	Yes	Belief: list, get, evidence, admit, retract, conflicts, or reconcile. Perception ledger: perception_record, perception_list, perception_for_entity, or perception_for_event. Knowledge: knowledge_query.
`detail`	No	Return full belief records instead of summary entries (list).
`object`	No	Proposition object (admit).
`source`	No	Source key used to correlate duplicate evidence (admit; default the active badge).
`status`	No	active, unresolved, or suppressed (admit; default active).
`weight`	No	Evidence support weight 0..1 (admit; default 1).
`subject`	No	Proposition subject (admit).
`polarity`	No	positive or negative (admit).
`question`	No	Belief question key, or subject\|predicate\|object (get/evidence).
`entity_id`	No	Entity whose beliefs are queried or mutated.
`predicate`	No	Proposition predicate (admit).
`evidence_id`	No	Evidence record id (retract).
`source_ordinal`	No	Contributing event-log ordinal (admit; default the latest event ordinal).
`perception_kind`	No	message, scene, or observation (perception_record; default observation).
`perception_sense`	No	Sense that produced the perception (perception_record; default null; REQ-594).
`perception_room_id`	No	Room identifier for the perception (perception_record; defaults to the entity's room).
`perception_summary`	No	What was perceived (perception_record).
`perception_witness`	No	Witness kind (perception_record; default inferred; REQ-594).
`perception_entity_id`	No	Entity that perceived (perception_record/perception_for_entity).
`perception_confidence`	No	0..1 confidence (perception_record; default 0; REQ-594).
`perception_event_ordinal`	No	Contributing event-log ordinal (perception_record/perception_for_event; defaults to the latest event).
`perception_source_entity`	No	Entity the perception came from (perception_record; default null).

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

Changed9 schema fields changedv2026.10.13Oct 25, 2026

changedInput schema / properties / action / description

Previous value: -"Belief: list, get, evidence, admit, retract, conflicts, or reconcile. Perception ledger: perception_record, perception_list, perception_for_entity, or perception_for_event."New value: +"Belief: list, get, evidence, admit, retract, conflicts, or reconcile. Perception ledger: perception_record, perception_list, perception_for_entity, or perception_for_event. Knowledge: knowledge_query."

changedInput schema / properties / action / enum

Previous value: -[
-  "list",
-  "get",
-  "evidence",
-  "admit",
-  "retract",
-  "conflicts",
-  "reconcile",
-  "perception_record",
-  "perception_list",
-  "perception_for_entity",
-  "perception_for_event"
-]New value: +[
+  "list",
+  "get",
+  "evidence",
+  "admit",
+  "retract",
+  "conflicts",
+  "reconcile",
+  "knowledge_query",
+  "perception_record",
+  "perception_list",
+  "perception_for_entity",
+  "perception_for_event"
+]

addedInput schema / properties / detail

Added value: +{
+  "description": "Return full belief records instead of summary entries (list).",
+  "type": "boolean"
+}

addedInput schema / properties / perception_confidence

Added value: +{
+  "description": "0..1 confidence (perception_record; default 0; REQ-594).",
+  "maximum": 1,
+  "minimum": 0,
+  "type": "number"
+}

addedInput schema / properties / perception_room_id

Added value: +{
+  "description": "Room identifier for the perception (perception_record; defaults to the entity's room).",
+  "type": "string"
+}

addedInput schema / properties / perception_sense

Added value: +{
+  "description": "Sense that produced the perception (perception_record; default null; REQ-594).",
+  "enum": [
+    "sight",
+    "sound",
+    "telling"
+  ],
+  "type": "string"
+}

addedInput schema / properties / perception_source_entity

Added value: +{
+  "description": "Entity the perception came from (perception_record; default null).",
+  "type": "string"
+}

addedInput schema / properties / perception_witness

Added value: +{
+  "description": "Witness kind (perception_record; default inferred; REQ-594).",
+  "enum": [
+    "saw",
+    "heard",
+    "inferred",
+    "told"
+  ],
+  "type": "string"
+}

addedInput schema / properties / topic

Added value: +{
+  "description": "Optional topic filter applied to knowledge_query perceptions, beliefs, and secrets.",
+  "type": "string"
+}

Changed6 schema fields changedv1.0.5Oct 12, 2026

changedInput schema / properties / action / description

Previous value: -"list, get, evidence, admit, retract, conflicts, or reconcile."New value: +"Belief: list, get, evidence, admit, retract, conflicts, or reconcile. Perception ledger: perception_record, perception_list, perception_for_entity, or perception_for_event."

changedInput schema / properties / action / enum

Previous value: -[
-  "list",
-  "get",
-  "evidence",
-  "admit",
-  "retract",
-  "conflicts",
-  "reconcile"
-]New value: +[
+  "list",
+  "get",
+  "evidence",
+  "admit",
+  "retract",
+  "conflicts",
+  "reconcile",
+  "perception_record",
+  "perception_list",
+  "perception_for_entity",
+  "perception_for_event"
+]

addedInput schema / properties / perception_entity_id

Added value: +{
+  "description": "Entity that perceived (perception_record/perception_for_entity).",
+  "type": "string"
+}

addedInput schema / properties / perception_event_ordinal

Added value: +{
+  "description": "Contributing event-log ordinal (perception_record/perception_for_event; defaults to the latest event).",
+  "type": "number"
+}

addedInput schema / properties / perception_kind

Added value: +{
+  "description": "message, scene, or observation (perception_record; default observation).",
+  "enum": [
+    "message",
+    "scene",
+    "observation"
+  ],
+  "type": "string"
+}

addedInput schema / properties / perception_summary

Added value: +{
+  "description": "What was perceived (perception_record).",
+  "type": "string"
+}

Addedv1.0.3Sep 29, 2026

TDQS

A4.3/5.0

Behavior5/5

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

Goes well beyond the annotations by disclosing the evidence-then-reconcile dependency (admit does not change a stance until reconcile runs), that retract removes evidence and reconciles, that the perception ledger is append-only so corrections require a new record, and that mutations persist to the Novel while reads are read-only. No contradiction with destructiveHint=true / readOnlyHint=false.

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

Conciseness4/5

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

Front-loaded with the resource scope, then behavioral rules, then use/don't-use routing — a logical order. Dense but nearly every clause carries information; the opening sentence is a slightly long noun pile-up that could be trimmed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 12 actions and 23 parameters, the description covers the mutating flow, the append-only constraint, persistence, and alternative tools, and an output schema exists so return values need not be described. Missing only a mapping of which parameters belong to which of the less-mentioned actions (list/get/conflicts), which the schema partially supplies.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with per-parameter descriptions bound to specific actions, so the schema carries the parameter burden. The description adds a little semantic context (weight being a 0..1 support value, the reconcile gating) but does not explain the 23 parameters or which are required per action, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the resources clearly — evidence, reconciled belief stances, perception ledger, and knowledge query — and enumerates the key verbs (admit, retract, reconcile, knowledge_query). It omits the read verbs (list, get, evidence, conflicts, perception_list) that appear in the schema enum, so an agent must open the schema to see the full action set.

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?

Explicit 'Use when: inspecting or recording what an entity learned or believes' plus a 'Do NOT use when' clause that routes to manage_causality for objective truth and manage_lore for shared lore. This is exactly the sibling-disambiguation an agent needs for a crowded toolset.

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