Skip to main content
Glama
chaos-xxl

Protocol Chaos reference server

by chaos-xxl
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

event_record_expression

Record a user's exact words and atomically update an event's title, state, progress, facts, refs, or metadata, returning a receipt.

Instructions

Record words together with the changes they support, atomically: set any of title, state, progress, facts (goal, constraint, plan), refs and metadata. To fold words recorded earlier into fields, pass that Account's accountId and its exact text instead of appending new words. Each supplied field replaces the stored one, so supply its complete current content and carry over what still holds; null removes a field. Mark your own inferences inside the fact text with their basis. Verbatim rule: text is the user's actual words, trimmed and otherwise unchanged, never a summary or a third-person paraphrase such as "The user confirmed…"; when a message covers several Events, pass the part about this Event, still in the user's words. Interpretation belongs in the fields. Returns a receipt.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
setNoFields to replace, each with its complete current content; null removes a field. Inside facts, each supplied key replaces that fact and the others are unchanged.
viaNoWhere the words came from when they were not said in this conversation, e.g. "example-export".
textYesThe user's actual words, verbatim. Never a summary or a third-person paraphrase.
actorYesWho is writing: your own identity, e.g. {"kind": "agent", "id": "laptop"}. Never the owner or another writer.
eventIdYesAn Event id from the directory or a receipt.
accountIdNoAn existing Account of this Event to ground the changes on.
accountSourceNoWhose words they are: user (default), agent_response (your own sentence, such as an inference) or authorized_external (relayed from an application the user authorized).
expectedVersionNoThe Event's version from your last read or receipt. On VERSION_CONFLICT, read again and reconsider.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.1

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already declare a non-read-only, non-destructive write, and the description adds genuinely important behavior beyond them: replacement semantics ('each supplied field replaces the stored one, supply its complete current content'), null-removes-a-field, atomicity, and that a receipt is returned. Version-conflict handling is left to the schema rather than the description, which keeps this from a 5.

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?

One dense paragraph, front-loaded with the atomic record-and-set purpose, followed by the fold-into-fields path, replacement semantics, and the verbatim rule. Every sentence carries an instruction; it is long but not padded, though the verbatim rule could be tightened.

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?

For an 8-parameter write with nested objects and no output schema, the description covers atomicity, replacement/removal semantics, the Account-grounding path, and that a receipt is returned. The receipt's contents are only implied, and conflict recovery is delegated to the schema, but nothing essential to calling it correctly is missing.

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 structured fields carry most of the load and the baseline is 3. The description earns above baseline by explaining the non-obvious accountId + exact-text pattern and by restating the verbatim contract for text, both of which are workflow semantics the schema does not fully convey.

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?

Names a specific verb and resource: recording the user's words together with the field changes they support, atomically, and enumerates the settable fields (title, state, progress, facts, refs, metadata). It is clear what the tool does, though it never distinguishes itself from close siblings such as event_note or event_record.

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

Usage Guidelines3/5

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

It gives one concrete usage rule: to fold earlier-recorded words into fields, pass accountId with that exact text rather than new words. That is useful, but there is no guidance on when to choose this tool over the sibling write tools (event_note, event_record), nor any when-not-to-use statement.

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

Deploy Server

Other Tools