ontology-atlas

Overview Schema Source Related Servers Discussions Admin

add_concept

Create a Markdown ontology node when code analysis surfaces a new capability, element, or project. Warns on duplicate slugs and near-duplicate titles, then returns next maintenance actions.

Instructions

Create a new ontology node (.md file). Call when an AI agent finds a new capability / element / project from code analysis. Throws if the slug already exists — use patch_concept in that case. The frontmatter is normalized per kind (project gets domains/capabilities/elements empty arrays; capability gets elements: []; capability/element should also set domain: so the tree has a parent — missing extras come back as warnings in the response, not as an error. If another node already has the same title, a near-duplicate warning is included too — prefer patch_concept on the existing node over forking a duplicate. Successful 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 new node lands. For bulk creation (e.g. bootstrap flow with 5+ nodes) use add_concepts({concepts: [...]}) (batch, max 50, partial result) — saves K-1 round-trips. When kind is element: an element names a CONCEPT a capability uses (e.g. "jwt-token"), not a file. If your title is a bare path or ends in a source extension, you are describing evidence, not the concept — rename title to the role and put the path in path:, or if 3+ siblings under the same parent already look like this, call get_concept on the parent and consider patch_concept on an existing sibling instead of adding another file-mirror node. The same rule binds the slug: flat under the kind folder (elements/<role-name>), never a code path (elements/src/views/home is rejected) — path-style slugs collide the moment two files share a basename and the graph silently merges distinct nodes.

Input Schema

TableJSON Schema

Name	Required	Description
`body`	No	Markdown body (optional). When omitted a kind-specific starter body is written so the file is self-explanatory in the editor.
`kind`	Yes	project / domain / capability / element / document. (vault-readme is reserved for the auto-generated README.md and should not be set by agents.)
`path`	No	One canonical implementation entrypoint for a capability or element (repo-relative file or directory). Preserved as evidence and checked by validate_vault path drift.
`slug`	Yes	Vault-relative slug (omit the .md extension), flat under the kind folder — e.g. "elements/jwt-token", "capabilities/token-issue". A slug is the node's name, never a code path: "elements/src/views/home" is rejected (put the file location in path: instead).
`title`	Yes	Display title for the node.
`domain`	No	Parent domain slug. Strongly expected for kind=capability and kind=element — without it the node floats orphaned in the tree.
`labels`	No	Per-locale display names, e.g. { "ko": "결제", "en": "Payments" }. Written as `display_ko` / `display_en` frontmatter keys; `title` stays the single source for search/matching. Fill BOTH locales the vault serves — a single-locale entry comes back as a warning.
`elements`	No	Element slugs this node uses (project / capability).
`capabilities`	No	Capability slugs this node owns (project / domain).

Output Schema

TableJSON Schema

Name	Required	Description
`ok`	Yes
`slug`	Yes
`changed`	Yes
`filePath`	Yes
`warnings`	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.7/5.0

Behavior5/5

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

Annotations only convey readOnly=false, openWorld=false, idempotent=false, destructive=false. The description adds substantial context beyond those: 'Throws if the slug already exists', missing extras return as warnings not errors, frontmatter normalization per kind, path-style slug rejection and silent graph-merging risk, and the postWriteMaintenance response shape. All consistent with annotations (idempotent=false matches the throw-on-exists).

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

Conciseness3/5

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

Every sentence carries real information and the first sentence front-loads the core purpose, but the body is a single dense wall of text with no paragraph breaks or bullet structure. Given the 9-parameter complexity some length is justified, yet it would benefit from scannable structure for a tool this rich.

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?

Exceptionally complete for a complex tool: covers when to call, alternatives, error semantics, normalization per kind, bulk path, slug/title constraints, and the response's postWriteMaintenance queue fields. The output schema exists so return values are covered structurally. Nothing an agent needs to call this correctly is missing.

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 baseline is 3, but the description adds genuine semantic value beyond the schema: the title-vs-path rule ('a bare path or ends in a source extension' = evidence, rename to role), the slug flat-folder rule ('elements/src/views/home' rejected), and kind-specific element meaning ('names a CONCEPT a capability uses, not a file'). This materially helps correct parameter selection.

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?

Opens with a specific verb+resource: 'Create a new ontology node (.md file).' Immediately distinguishes from siblings by naming patch_concept (for existing slugs) and add_concepts (for bulk). An agent can tell what this does and how it differs from the surrounding tools without opening schemas.

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 explicit when-to-use ('Call when an AI agent finds a new capability / element / project from code analysis'), explicit exclusions ('use patch_concept' if slug exists, 'use add_concepts' for 5+ nodes), and even a near-duplicate rule (prefer patch_concept over forking a duplicate). No inference needed.

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