KSJ MCP Server

Overview Schema Source Related Servers Discussions Admin

assert_connection

Assert a typed, directional relationship between two captures to record how one supersedes, refutes, narrows, supports, distills, assesses, observes, or develops the other.

Instructions

Assert a typed, directional relationship between two captures by hand.

Relations (source → target):
  supersedes — source replaces target. Target is closed out (kept in
               history, hidden from current-slice search — never deleted).
  refutes    — source contradicts target.
  narrows    — source restricts target's claim without overturning it.
  supports   — source is evidence for target.
  distills   — source (an AIEX distillation entry) is derived from
               target (a SYN page). Normally set automatically by
               commit_distillation(); asserting it by hand is for
               fixing or adding a link that tool didn't create.
  assesses   — source (an AIEX assessment entry) audits target (a REV
               page)'s claimed knowledge status. Normally set
               automatically by commit_assessment().
  observes   — source (an AIEX observation entry) notes target (a DC
               page)'s cross-domain echo or confirmed symbol meaning.
               Normally set automatically by commit_observation().
  develops   — source (a journal entry, e.g. a SYN page) develops the
               idea first scribbled in target (typically a loose Wild Art
               capture — a napkin sketch or sticky note). The scribble
               stays as the source; nothing is closed out.

Automatic contradiction detection is deliberately not offered — it
cannot be done reliably. Supersession is either asserted here by a
human or not recorded. Re-asserting between the same pair replaces the
previous assertion.

Args:
    source_id: The newer / asserting capture (numeric ID).
    target_id: The capture being superseded / refuted / supported / distilled / assessed / observed / developed.
    relation:  supersedes | refutes | narrows | supports | distills | assesses | observes | develops
    note:      Optional one-line reason, stored on the edge.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`note`	No
`relation`	Yes
`source_id`	Yes
`target_id`	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

Behavior4/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 well: it discloses that supersedes closes the target out (kept in history, hidden from search, never deleted), that re-asserting between the same pair replaces the prior assertion, and that automatic contradiction detection is deliberately absent. It stops short of permissions/auth or concurrency details, but the side-effect profile is unusually well covered.

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?

It is long, but the length is justified by eight relation types that each require distinct semantics, and the purpose is front-loaded in the first sentence. Minor verbosity in the repeated 'normally set automatically by ...' phrasing, but nothing is wasted.

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 domain-complex, annotation-free mutation tool with an output schema, the description supplies the relation taxonomy, directionality, manual-vs-automatic guidance, and side effects. Return values are covered by the output schema, so nothing essential 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 description coverage is 0%, so the description must compensate, and it does: the Args block defines all four parameters and gives a full semantic breakdown of every relation enum value beyond the bare string list. An agent knows exactly what source_id and target_id mean relative to the chosen relation.

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?

The description states a specific verb (assert) and resource (a typed, directional relationship between two captures), and immediately clarifies the directionality (source → target). This clearly distinguishes it from siblings like assert_entity, find_connections, or rebuild_connections.

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?

It spells out exactly when each relation applies, and crucially notes which relations (distills, assesses, observes) are normally set automatically by commit_distillation/commit_assessment/commit_observation and that manual assertion is for fixing or adding missing links. It also explicitly rules out automatic contradiction detection, telling the agent that a human must assert supersession.

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