holonovel

Note Management

manage_note

Destructive

Store and update Novel-scoped scratch notes for reusable caller state, scoped to game_master, player, or shared badges, with audited server-level notes and summary listing.

Instructions

Manage Novel-scoped scratch notes, badge-scoped to game_master (default), player, or shared. set replaces the note content; badge_scope defaults to game_master and controls which badge can read it; set_server stores a server-level note with an optional narrative_tag, and list_server returns summaries unless detail is set. Mutations persist to the Novel and are audited. Use when: storing scratch state the caller will reuse. Do NOT use when: recording durable world facts — use manage_lore (action: set). Revert with manage_history (action: undo).

Input Schema

Name	Required	Description
`key`	No	The note key (set/remove/set_server/remove_server).
`action`	Yes	set, remove, list, set_server, remove_server, or list_server.
`detail`	No	Return full server notes instead of summary entries (list_server).
`content`	No	The note content (set/set_server).
`badge_scope`	No	game_master, player, or shared (set).
`narrative_tag`	No	Optional narrative tag (set_server).

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.

Changed1 schema field changedv2026.10.13Oct 25, 2026

addedInput schema / properties / detail

Added value: +{
+  "description": "Return full server notes instead of summary entries (list_server).",
+  "type": "boolean"
+}

Addedv1.0.3Sep 29, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already flag destructiveHint=true and readOnlyHint=false; the description adds real context on top: mutations persist to the Novel, are audited, 'set replaces the note content', and badge_scope governs which badge can read the note. It stops short of explaining the remove/remove_server destructive paths, which is the main gap given destructiveHint=true.

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 and scope, then action semantics, then use/don't-use rules. Dense but every sentence carries information; the middle sentence is somewhat packed with several action behaviors at once.

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?

With an output schema and annotations covering safety, the description only needs to carry usage, scoping, and mutation semantics, which it does. The remove and list actions of a six-action tool are never mentioned, leaving a small completeness gap.

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 coverage is 100% so the baseline is 3, but the description adds genuine semantics beyond the schema: badge_scope defaults to game_master and controls read access, set_server takes an optional narrative_tag, and list_server returns summaries unless detail is set. Only remove/list action behavior is left to the schema.

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?

Names a concrete resource ('Novel-scoped scratch notes') plus its scoping dimension (badge-scoped to game_master/player/shared), so the agent knows exactly what this tool owns. It also distinguishes itself from manage_lore and manage_history, which is more than most siblings do.

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: storing scratch state the caller will reuse' and 'Do NOT use when: recording durable world facts — use manage_lore (action: set)', plus a revert path via manage_history (action: undo). Both the inclusion and exclusion conditions plus named alternatives are present.

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