Skip to main content
Glama
Sign In
AIWorkhub

AIWorkhub

by shrec
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

aiworkhub_manager_session_write

Append or edit audited session events to log starts, checkpoints, handoffs, and closes, or amend and redact existing records.

Instructions

MANAGER WRITE: append one audited canonical Session Manager event, or edit one existing event.

Append actions: start, event, checkpoint, state, handoff, close (no document_id). Edit actions: amend rewrites the content of one exact existing document (FTS rebuilt, audit row recorded, context-graph mirror rewritten); redact deletes that document, its FTS row and its graph mirror (audit keeps the fact of the redaction, never the content). Both require document_id and leave the document count/id audit trail truthful.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "action": "<action>",
      "topic": "<topic>",
      "content": "<content>",
      "idempotency_key": "<idempotency_key>",
      "provenance": "<provenance>"
    },
    "name": "aiworkhub_manager_session_write"
  }
}

Input Schema

NameRequiredDescriptionDefault
topicYesSession topic the document belongs to, non-blank, at most 256 bytes.
actionYesstart, event, checkpoint, state, handoff or close appends a new document; amend rewrites one existing document and redact deletes it.
contentYesDocument text, non-blank, at most 32 KiB; optional for redact.
provenanceYesNon-blank provenance text recorded in the audit row, at most 2048 bytes.
document_idNoPositive id of the existing document to amend or redact; required for those two actions and refused for the append actions.
idempotency_keyYes8-192 characters matching ^[A-Za-z0-9][A-Za-z0-9_.:-]{7,191}$; replaying a key returns the stored result instead of writing again.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changedv0.12.67
    • addedInput schema / properties / action / description
      Added value: +"start, event, checkpoint, state, handoff or close appends a new document; amend rewrites one existing document and redact deletes it."
    • addedInput schema / properties / content / description
      Added value: +"Document text, non-blank, at most 32 KiB; optional for redact."
    • addedInput schema / properties / document_id / description
      Added value: +"Positive id of the existing document to amend or redact; required for those two actions and refused for the append actions."
    • addedInput schema / properties / idempotency_key / description
      Added value: +"8-192 characters matching ^[A-Za-z0-9][A-Za-z0-9_.:-]{7,191}$; replaying a key returns the stored result instead of writing again."
    • addedInput schema / properties / provenance / description
      Added value: +"Non-blank provenance text recorded in the audit row, at most 2048 bytes."
    • addedInput schema / properties / topic / description
      Added value: +"Session topic the document belongs to, non-blank, at most 256 bytes."
  2. First observedv0.1.0

TDQS

A4.1/5.0
Behavior3/5

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

The description adds rich behavioral context beyond annotations: amend rebuilds FTS and rewrites the graph mirror, redact deletes the document/FTS row/graph mirror but the audit retains only the fact of redaction, and idempotency is covered. However, describing a permanent content deletion under destructiveHint=false is a material mismatch that undercuts the annotation's safety signal.

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-loads the append/edit split, then details each branch. Efficient and well-organized, though a few phrases (e.g., 'truthful', 'canonical') add little and 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?

Covers append vs edit behavior, side effects, and audit handling, and an output schema exists so return values needn't be explained. What's missing is any note on failure behavior or permission/auth requirements for these mutations.

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 parameters are already documented, but the description adds meaningful semantics by mapping document_id to the amend/redact actions (required there, refused for appends) and noting content is optional for redact. This goes slightly beyond the raw schema constraints.

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 ('append'/'edit') and resource ('audited canonical Session Manager event'), then branches into the append actions (start, event, checkpoint, state, handoff, close) and the edit actions (amend, redact). An agent can tell exactly what this tool does and how it differs from the read-side session tools.

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

Usage Guidelines4/5

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

Clearly partitions the eight actions into append vs edit and states that amend/redact require document_id while appends refuse it. It gives strong intra-tool routing but never names the sibling read tools (e.g., aiworkhub_manager_session_current_state) or explicitly says 'do not use for reads', leaving cross-tool selection to inference.

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