KSJ MCP Server

Overview Schema Source Related Servers Discussions Admin

commit_distillation

Store the confirmed outcome of a surface_connections() dialogue: save the distilled insights from a revised connection map and link them to the SYN page.

Instructions

Store the confirmed outcome of a surface_connections() dialogue.

Call this after the Phase 2 dialogue concludes and the user has
reviewed the revised connection map. Only the distillation — what the
comparison revealed, not the connection list or the dialogue
transcript itself — is stored as the entry's text; the four categories
are kept as supporting detail alongside it.

Never creates a SYN template ID — SYN numbers belong to physical
pages. Stores with source='ai_extract' (excluded from journal_health
KPIs, distinguishable in get_breakthroughs()/export_html()) using the
AIEX sequence, and links to the SYN page with an asserted 'distills'
edge (source: the new AIEX entry, target: the SYN page).

Args:
    distillation_json: JSON string with fields:
      syn_template_id (required) — the SYN page this distills.
      distillation     (required) — 2-5 sentences: what the comparison
                       revealed and what it means. This is the artifact.
      confirmed, retired, deferred, missed, beyond_scan — lists of
                       strings, one per connection-map entry (all
                       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 distills edge.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`distillation_json`	Yes

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv3.9.0Oct 2, 2026

TDQS

A4.7/5.0

Behavior5/5

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

With no annotations, the description carries the full burden and does so richly: it discloses that no SYN template ID is created, that the entry is stored with source='ai_extract' (excluded from journal_health KPIs, discoverable in get_breakthroughs()/export_html()), that it uses the AIEX sequence, and that it asserts a 'distills' edge to the SYN page. This is exactly the behavioral context an agent needs before writing.

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?

The purpose is front-loaded and the Args block is well-organized and necessary given the nested JSON payload. It is slightly long and includes a few soft phrases ('This is the artifact'), but nearly every sentence conveys operationally relevant detail rather than filler.

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 complex write tool with a structured payload, the description covers the source flag, ID sequencing, edge assertion, and return confirmation (AIEX ID and distills edge). With an output schema present, return values need no further unpacking, so nothing an agent needs to call it correctly is missing.

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% (the lone param is an opaque string), so the description must compensate and it fully does, enumerating every JSON field: syn_template_id (required), distillation (required, with sentence guidance), the five optional connection-map lists, tags, and date. This adds far more meaning than the schema provides.

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 surface_connections() dialogue') and immediately clarifies scope by excluding what is NOT stored (the connection list, the transcript). An agent can distinguish this from commit_assessment, commit_observation, and commit_aiex from the first two sentences.

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?

Gives an explicit trigger condition: call after the Phase 2 dialogue concludes and the user has reviewed the revised connection map. That ties it clearly to its predecessor surface_connections(). It stops short of naming alternative commit_* siblings or when NOT to use it, keeping it at a strong 4 rather than 5.

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