Skip to main content
Glama

commit_observation

Store the confirmed observation from a bridge_dream_research dialogue as an AI extract entry linked to the DC page, preserving the original dream narrative.

Instructions

Store the confirmed outcome of a bridge_dream_research() dialogue.

Named "observation," not "inference": at journal scale (routinely a
handful of DC entries, sometimes one), what this dialogue produces is
a noticing, not a conclusion the data could support calling an
inference. Call this after the dialogue concludes and the user has
reviewed the observation. Only the observation — what the dialogue
revealed, not a restatement of the dream or an asserted symbol
meaning — is stored as the entry's text.

Never changes the bridged DC page's own dream narrative — that stays
physical-authority, exactly like commit_distillation never rewrites a
SYN page. Stores with source='ai_extract' (excluded from journal_health
KPIs) using the AIEX sequence, and links to the DC page with an
asserted 'observes' edge.

Args:
    observation_json: JSON string with fields:
      dc_template_id (required) — the DC page this observes.
      observation      (required) — 2-5 sentences: what the dialogue
                       revealed. This is the artifact.
      confirmed_echoes, symbol_notes — lists of strings (both
                       optional, default empty).
      tags             — optional list of "#topic"/"@source"/etc strings.
      date             — optional ISO date; defaults to today.

Returns a confirmation with the assigned AIEX ID and the observes edge.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
observation_jsonYes

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv3.9.0

TDQS

A4.7/5.0
Behavior4/5

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

With no annotations, the description carries the full load and does well: it discloses the mutation boundary (never changes the bridged DC page's dream narrative), the storage semantics (source='ai_extract', excluded from journal_health KPIs), the AIEX sequence, and the 'observes' edge creation. It omits risks like duplicate handling or whether prior observations are overwritten.

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 verb+resource immediately, but the middle paragraph defending 'observation' vs 'inference' is philosophically padded and could be trimmed. The remainder (behavior, args) is dense and useful.

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

Completeness5/5

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

For a mutation tool with zero annotations and an opaque single-param schema, the description supplies everything an agent needs: when to call, what gets written and where, identifiers, edge semantics, and a return summary. An output schema exists but the description's return note is supplementary, not redundant.

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

Parameters5/5

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

Schema coverage is 0% and the single parameter is an opaque JSON string, yet the description fully compensates by enumerating every field, marking required vs optional, specifying types (lists of strings), defaults, and the 2-5 sentence constraint on the core 'observation' field.

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 and resource: 'Store the confirmed outcome of a bridge_dream_research() dialogue.' It explicitly distinguishes this from what it is not ('observation,' not 'inference') and differentiates from siblings like commit_distillation, so an agent can route precisely.

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?

Gives clear timing ('Call this after the dialogue concludes and the user has reviewed the observation') and scope exclusions ('Only the observation — not a restatement of the dream or an asserted symbol meaning'). It also names the related tool bridge_dream_research() whose output it consumes.

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