ontology-atlas

Overview Schema Source Related Servers Discussions Admin

add_relation

Idempotent

Add a typed semantic relation between two ontology nodes, appending it to the corresponding frontmatter key and attaching a one-line rationale when provided.

Instructions

Add a semantic relation between two nodes. Appends to the matching frontmatter graph key (domains / capabilities / elements / dependencies / relates / contains / describes); domain sets the source node's inline parent domain. The relation type picks which key receives the entry. A new depends_on relation requires a nonblank why; an already-existing edge remains an idempotent read even if legacy data has no rationale. R11: optional expected_mtime — pass the source-side mtime from a prior get_concept so concurrent external edits throw VaultConflictError. Invalid relation type is rejected before endpoint slug resolution with a closest-value hint and structured valueName / receivedValue / suggestion / allowedValues repair fields in structuredContent, with no changed, alreadyExists, or postWriteMaintenance write metadata. Changed writes return compact postWriteMaintenance (maintenance_plan) with count-safe byPhase / bySeverity / byKind queue buckets, action score, executable proposedAction, and current-page nextExecutableAction / nextReviewAction pointers so agents can immediately see graph cleanup / relation suggestions after the edge lands. For multiple already-approved semantic edges use add_relations({relations: [...]}) (batch, idempotent, max 50). infer_imports.moduleEdges require exact-evidence review, a semantic rationale, and human approval first.

Input Schema

TableJSON Schema

Name	Required	Description
`to`	Yes	Target slug.
`why`	No	One-line rationale for this relation ("A leans on B because ..."). Stored in the SAME frontmatter write as the ref (relation_notes map) — write it whenever you know the reason; a graph edge without a why is a mind-map line, not an ontology claim.
`from`	Yes	Source slug.
`type`	Yes	Relation type.
`expected_mtime`	No	Optional conflict guard for the source slug. If the source mtimeMs differs at write time, the call throws.

Output Schema

TableJSON Schema

Name	Required	Description
`ok`	Yes
`to`	Yes
`key`	No
`from`	Yes
`type`	Yes
`changed`	No
`alreadyExists`	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.8/5.0

Behavior5/5

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

It goes well beyond the idempotentHint annotation by stating specifically that an existing edge remains an idempotent read even when legacy data lacks a rationale. It also discloses expected_mtime conflict behavior, VaultConflictError, rejection-before-endpoint-resolution, and rich postWriteMaintenance return behavior, while not contradicting the annotations.

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?

This is a long, dense paragraph, and it would benefit from stronger visual structure, but every sentence adds a distinct and relevant behavior. The purpose is front-loaded and the sibling routing appears near the end, after the important technical details.

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 tool's high complexity, an explicit output schema, and many sibling tools, the description covers the operation, conflict handling, failure-mode details, and batch alternatives. It even explains behavior that the output schema might not, such as the contents of `postWriteMaintenance` and the conditions for using the batch endpoint.

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 100%, so the baseline is 3, but the description adds genuine semantics: `depends_on` requires a nonblank `why`, `domain` sets the source node's inline parent domain, `type` determines the frontmatter key, and `expected_mtime` comes from a prior `get_concept` and acts as a concurrent write guard.

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 first sentence names a specific operation, 'Add a semantic relation between two nodes', and the description spells out the frontmatter keys it writes to. It also distinguishes itself from the sibling `add_relations` by naming the batch variant as the preferred tool for multiple edges.

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 explicitly says to use `add_relations` for multiple already-approved edges and that `infer_imports.moduleEdges` require human approval first, giving clear when-to and when-not-to guidance. This directly orients the agent toward the correct tool selection.

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