999 Seal · VAULT999

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

The description reinforces the annotation's destructiveHint=true by stating 'irreversible' and 'immutable append'. It adds behavioral context beyond annotations, such as authority requirements ('Authority: 888_HOLD / SOVEREIGN + ack_irreversible for seal mode') and a veto power ('Arif owns F13 veto'). There is no contradiction with annotations.

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

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

The description is a single paragraph of moderate length, front-loading the core concept of immutable append. It contains poetic language and jargon (e.g., 'civilizational memory'), which reduces conciseness. While it covers key points, it could be more efficiently structured for an AI agent.

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

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

Given the tool's complexity (12 parameters, destructive, no param descriptions), the description leaves significant gaps. It does not explain the meaning or purpose of any parameter, nor describe the output (despite an existing output schema). The mode list discrepancy further undermines completeness. An agent would struggle to use this tool correctly without additional context.

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

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

The input schema has 12 parameters with 0% description coverage, and the description does not explain any parameter in detail. It lists modes in text ('seal | verify | chain | list | dry_run | seal_card | render') but the schema's mode enum includes different values ('seal', 'verify', 'ledger', 'changelog', 'audit'), creating inconsistency. The description adds minimal helpful parameter semantics and introduces confusion instead.

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

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

The description states that the tool performs an 'immutable append' or 'seal' operation, implying irreversible creation of a record. It mentions modes like 'seal' and 'verify', and gives a condition ('Seal only after SEAL verdict path'). However, the language is esoteric and uses proprietary terms (e.g., '888_HOLD', 'F13 veto') that may confuse an AI agent. The purpose is somewhat clear but not universally understandable.

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

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

The description provides implicit usage guidance: 'Seal only after SEAL verdict path' and 'Testing → dry_run', indicating when to use the seal mode versus dry run. It distinguishes the tool from siblings by stating 'Kernel judges; vault seals', implying arif_seal is for sealing after judging. However, it does not explicitly list when to use this tool over sibling tools like arif_judge or arif_think, limiting clarity.

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