KSJ MCP Server

Overview Schema Source Related Servers Discussions Admin

surface_connections

Scan the Rapid Capture cluster behind a written Synthesis page, then prepare a dialogue comparing the independent scan against the page's findings.

Instructions

Independently scan the Rapid Capture cluster behind a Synthesis page you
have ALREADY written and photographed, then prepare a structured
dialogue comparing what the scan found against what the page found.

This runs AFTER a SYN page exists for the cluster — never before.
Running it before the page is written would let the AI perform the
cognitive act synthesis is meant to force (see
ksj2_documents/SYN_companion_decision_optionB_2026-08-03.md). There is
no override flag for this precondition — if no SYN page is found, the
tool declines and points to suggest_synthesis() instead.

The scan itself never reads the SYN page's own content before producing
its connection map, so the Phase 2 comparison is meaningful rather than
confirmatory. This tool does NOT write to the database — it prepares
the scan data and dialogue instructions for Claude to run in this
conversation. Call `commit_distillation()` after the user approves the
dialogue's outcome, to persist it.

Trigger phrases: "Run surface_connections on SYN-004", "Compare my
synthesis against an independent scan".

Args:
    syn_template_id: The SYN page's template ID (e.g. "SYN-004").
                     Required — the tool declines if no SYN page with
                     this ID exists.
    entry_ids:       Optional comma-separated RC template IDs (e.g.
                     "RC-001,RC-047,RC-083") to scan explicitly.
                     Required when the SYN page's RC cluster can't be
                     resolved automatically — no matching tag cluster,
                     or more than one candidate cluster.
    days:            Optional — narrow the resolved cluster to RC
                     entries created in the last N days. 0 = no filter.
    depth:           "brief" | "standard" (default) | "deep" — how many
                     follow-up questions per tier to plan for in the
                     dialogue. The user can also say "more on this one"
                     for any single connection regardless of depth.

Returns the RC cluster data, gap candidates, and full scan + dialogue
instructions for Claude to execute.

Input Schema

TableJSON Schema

Name	Required	Default
`days`	No
`depth`	No	standard
`entry_ids`	No
`syn_template_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.9/5.0

Behavior5/5

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

With no annotations provided, the description carries the full burden and does so: it discloses the read-only nature ('does NOT write to the database'), the hard precondition with no override, the decline-and-redirect behavior, and the meaningful independence guarantee (the scan never reads the SYN page before producing its map). These are non-obvious behavioral traits an agent could not infer from schema or siblings.

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 core action and then layers preconditions and params efficiently; most sentences earn their place. It is somewhat long, and the inline reference to an internal markdown filename (ksj2_documents/SYN_companion_decision_optionB_2026-08-03.md) adds little value for an agent choosing the tool.

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 gated, multi-step tool with a precondition, params, and a downstream commit step, the description covers everything an agent needs: when it may run, what it returns at a high level, and what must happen after. An output schema exists, so return-value detail is appropriately left out.

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 fully, and it does: it defines syn_template_id as required with decline behavior, entry_ids as optional comma-separated RC IDs required only when the cluster can't be auto-resolved, days as a narrowing window with 0 = no filter, and depth's three tiers plus the user's 'more on this one' escape hatch. This adds meaning well beyond the bare typed properties.

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 (scan/compare) and resource (Rapid Capture cluster behind a Synthesis page), and precisely scopes the operation as 'prepare a structured dialogue comparing what the scan found against what the page found.' It is clearly distinguishable from siblings like suggest_synthesis and commit_distillation, which it names directly.

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 an explicit precondition ('runs AFTER a SYN page exists — never before'), states there is no override flag, and names the fallback (suggest_synthesis()) when the precondition fails. It also supplies concrete trigger phrases and clarifies that commit_distillation() is the required follow-up after user approval.

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