ontology-atlas

Overview Schema Source Related Servers Discussions Admin

remove_relation

DestructiveIdempotent

Remove one exact typed relation and its rationale from a source node. Defaults to dry-run, requires confirm:true to write, and checks expected_mtime to avoid conflicts.

Instructions

Safely remove one exact typed relation and its relation_notes rationale from a source node. Defaults to dry-run; pass confirm:true to write. Supports expected_mtime conflict protection. Use this instead of replacing a whole frontmatter array with patch_concept.

Input Schema

TableJSON Schema

Name	Required	Description
`to`	Yes	Target slug.
`from`	Yes	Source slug.
`type`	Yes
`confirm`	No	Actually remove when true; default is dry-run.
`expected_mtime`	No

Output Schema

TableJSON Schema

Name	Required	Description
`ok`	Yes
`to`	Yes
`key`	Yes
`from`	Yes
`type`	Yes
`dryRun`	Yes
`exists`	Yes
`changed`	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.
`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.
`removedRationale`	No
`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.9/5.0

Behavior5/5

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

Annotations already signal destructive behavior, but the description adds real value: it reveals the dry-run default, the need to pass confirm:true to write, expected_mtime conflict protection, and the side effect of deleting relation_notes. This goes well beyond what the annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences with no filler. The core operation is front-loaded, safety behavior follows immediately, and the alternative-tool pointer is last. Every sentence earns its place.

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?

Given the output schema exists and annotations cover safety, the description fully covers what an agent needs: what is removed, how to make it write, conflict protection, and the preferred alternative. Nothing essential is missing for correct invocation.

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?

Schema coverage is 60%, leaving type and expected_mtime without descriptions. The description compensates by explaining confirm's dry-run semantics and expected_mtime's conflict-protection role, and by framing 'type' as the typed-relation discriminator. Minor remaining gap: exact behavior when expected_mtime mismatches.

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 action ('remove'), a specific resource ('one exact typed relation'), and the attached 'relation_notes' rationale. It also explicitly differentiates itself from patch_concept, so an agent can tell what this tool does at a glance.

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?

The description clearly says to use this tool instead of replacing a whole frontmatter array with patch_concept, and the 'Safely remove one exact typed relation' phrasing defines the triggering condition. This is explicit routing guidance, not just a vague context hint.

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