ontology-atlas

Overview Schema Source Related Servers Discussions Admin

merge_concepts

Destructive

Merge one concept into another by redirecting every backlink to the survivor and deleting the source, preserving identity history. Use dry-run to preview before confirming.

Instructions

⚠ DESTRUCTIVE MULTI-FILE WRITE — fold one node into another. Every backlink to fromSlug is redirected to intoSlug (frontmatter array entries + body links), then fromSlug is deleted. The survivor keeps its UID while the source UID/history is recorded in canonical merged_uids. The intoSlug prose and non-identity frontmatter are preserved as-is — they are not merged automatically (use patch_concept after if you want to combine descriptions). Tail-only references are also redirected. Two-stage safety:

Without confirm: true the call is a dry-run — returns the redirect plan + list of deletions without writing.
With confirm: true the rewrites and the delete happen in one pass. Throws if either slug is missing. Confirmed writes return compact postWriteMaintenance (maintenance_plan) with count-safe byPhase / bySeverity / byKind queue buckets, action score, executable proposedAction, and current-page nextExecutableAction / nextReviewAction pointers for the final graph.

Input Schema

TableJSON Schema

Name	Required	Description
`confirm`	No	Actually perform the merge when true. Omit or false for a dry-run.
`fromSlug`	Yes	Slug to dissolve. Its file is deleted after backlinks redirect.
`intoSlug`	Yes	Slug to keep. Receives every redirected backlink.
`expected_mtime`	No	Optional conflict guard for fromSlug. Throws if the source has been modified externally.
`expected_into_mtime`	No	Optional conflict guard for intoSlug. Pass the survivor mtime from get_concept so a concurrent edit or identity-history change is never overwritten.

Output Schema

TableJSON Schema

Name	Required	Description
`ok`	Yes
`dryRun`	Yes
`changed`	No
`deleted`	Yes
`fromUid`	Yes
`intoUid`	Yes
`message`	No
`fromPath`	Yes
`fromSlug`	Yes
`intoSlug`	Yes
`canConfirm`	Yes	True only when repeating the call with confirm:true can perform the previewed change without another explicit safety opt-in.
`wouldChange`	Yes	True only when the dry-run predicts a disk or Git change.
`absorbedUids`	Yes
`capturedFrom`	Yes
`previewReady`	Yes	True only when this response is a complete dry-run preview that an agent can review.
`blockedReasons`	Yes	Machine-readable human explanations for every condition currently blocking confirmation.
`backlinkUpdates`	Yes
`postWriteMaintenance`	No	Compact maintenance_plan summary for post-write follow-up. Bucket maps describe the remaining queue after the write.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.13.0Sep 11, 2026

TDQS

A4.6/5.0

Behavior5/5

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

The description goes far beyond the annotations. While annotations already indicate destructiveHint, the description details exactly what is destroyed (fromSlug deleted after redirecting), what is preserved (intoSlug prose and non-identity frontmatter), and the two-stage execution model (dry-run vs confirm). It also discloses failure conditions (throws if slug missing), conflict guards, and the structure of the output (postWriteMaintenance with byPhase/bySeverity/byKind). This is exemplary behavioral transparency.

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 description is long but information-dense. It front-loads the critical destructive warning and organizes the two-stage safety into a numbered list. Each sentence contributes useful details (redirects, preserved fields, conflict guards, output structure). While some output details might duplicate what's in the output schema, the description is still tightly written and avoids fluff. The length is justified given the tool's complexity.

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 destructive, multi-file mutation tool, the description covers all essential context: preconditions (slugs exist), side effects (redirects, deletion), safety mechanisms (dry-run, confirm), conflict guards, and output expectations. It also mentions exception behavior and the preservation of the survivor's identity. Given the output schema exists, the tool is complete enough for an agent to invoke correctly without additional information.

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?

The schema already has 100% description coverage for all parameters, with clear descriptions for confirm, fromSlug, intoSlug, expected_mtime, and expected_into_mtime. The description adds valuable context beyond the schema, particularly the dry-run/confirm behavior and the conflict-guard purpose of the mtime parameters ('so a concurrent edit or identity-history change is never overwritten'). This enriches the agent's understanding without repeating the schema verbatim.

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 and resource ('fold one node into another') and explicitly lists the core actions: redirecting all backlinks and deleting fromSlug. This clearly distinguishes it from siblings like rename_concept (which renames a node) and delete_concept (which removes without redirecting). The use of 'DESTRUCTIVE MULTI-FILE WRITE' upfront also signals its unique purpose.

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?

The description provides clear guidance on when to use the tool: to merge concepts, with a two-stage safety mechanism (dry-run vs confirmed). It also mentions using patch_concept after if combining descriptions is desired, which routes the agent to an alternative action. However, it doesn't explicitly state when to choose a different tool (e.g., rename_concept for simple renaming) or list exclusions. The context is clear but not exhaustive.

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