Skip to main content
Glama
wlsdks

ontology-atlas

by wlsdks
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

add_concept

Creates a Markdown ontology node for a newly discovered capability, element, or project, validating slug and kind while returning near-duplicate warnings and graph maintenance suggestions.

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
NameRequiredDescriptionDefault
bodyNoMarkdown body (optional). When omitted a kind-specific starter body is written so the file is self-explanatory in the editor.
kindYesproject / domain / capability / element / document. (vault-readme is reserved for the auto-generated README.md and should not be set by agents.)
pathNoOne canonical implementation entrypoint for a capability or element (repo-relative file or directory). Preserved as evidence and checked by validate_vault path drift.
slugYesVault-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).
titleYesDisplay title for the node.
domainNoParent domain slug. Strongly expected for kind=capability and kind=element — without it the node floats orphaned in the tree.
labelsNoPer-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.
elementsNoElement slugs this node uses (project / capability).
capabilitiesNoCapability slugs this node owns (project / domain).

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
okYes
slugYes
changedYes
filePathYes
warningsNo
postWriteMaintenanceNoCompact 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.

  1. Changed4 schema fields changedv1.3.0
    • changedOutput schema / properties / postWriteMaintenance / properties / actions / items / properties / kind / enum
      Previous value: -[
-  "inspect_compile_issue",
-  "break_dependency_cycle",
-  "canonicalize_graph_arrays",
-  "resolve_dangling_reference",
-  "add_missing_relation",
-  "materialize_external_element",
-  "unassigned_node",
-  "empty_domain",
-  "separate_evidence_from_concept",
-  "fold_bulk_siblings",
-  "retire_unearned_node",
-  "capability_without_evidence",
-  "rejudge_summary_membership"
-]New value: +[
+  "inspect_compile_issue",
+  "break_dependency_cycle",
+  "canonicalize_graph_arrays",
+  "resolve_dangling_reference",
+  "add_missing_relation",
+  "materialize_external_element",
+  "unassigned_node",
+  "empty_domain",
+  "separate_evidence_from_concept",
+  "fold_bulk_siblings",
+  "retire_unearned_node",
+  "capability_without_evidence",
+  "rejudge_summary_membership",
+  "definition_missing",
+  "boundary_missing",
+  "epistemic_exclusion",
+  "folder_only_evidence",
+  "slug_outside_kind_folder",
+  "uncertainty_missing",
+  "retire_starter_example"
+]
    • changedOutput schema / properties / postWriteMaintenance / properties / filters / properties / kinds / items / enum
      Previous value: -[
-  "inspect_compile_issue",
-  "break_dependency_cycle",
-  "canonicalize_graph_arrays",
-  "resolve_dangling_reference",
-  "add_missing_relation",
-  "materialize_external_element",
-  "unassigned_node",
-  "empty_domain",
-  "separate_evidence_from_concept",
-  "fold_bulk_siblings",
-  "retire_unearned_node",
-  "capability_without_evidence",
-  "rejudge_summary_membership"
-]New value: +[
+  "inspect_compile_issue",
+  "break_dependency_cycle",
+  "canonicalize_graph_arrays",
+  "resolve_dangling_reference",
+  "add_missing_relation",
+  "materialize_external_element",
+  "unassigned_node",
+  "empty_domain",
+  "separate_evidence_from_concept",
+  "fold_bulk_siblings",
+  "retire_unearned_node",
+  "capability_without_evidence",
+  "rejudge_summary_membership",
+  "definition_missing",
+  "boundary_missing",
+  "epistemic_exclusion",
+  "folder_only_evidence",
+  "slug_outside_kind_folder",
+  "uncertainty_missing",
+  "retire_starter_example"
+]
    • changedOutput schema / properties / postWriteMaintenance / properties / nextExecutableAction / properties / kind / enum
      Previous value: -[
-  "inspect_compile_issue",
-  "break_dependency_cycle",
-  "canonicalize_graph_arrays",
-  "resolve_dangling_reference",
-  "add_missing_relation",
-  "materialize_external_element",
-  "unassigned_node",
-  "empty_domain",
-  "separate_evidence_from_concept",
-  "fold_bulk_siblings",
-  "retire_unearned_node",
-  "capability_without_evidence",
-  "rejudge_summary_membership"
-]New value: +[
+  "inspect_compile_issue",
+  "break_dependency_cycle",
+  "canonicalize_graph_arrays",
+  "resolve_dangling_reference",
+  "add_missing_relation",
+  "materialize_external_element",
+  "unassigned_node",
+  "empty_domain",
+  "separate_evidence_from_concept",
+  "fold_bulk_siblings",
+  "retire_unearned_node",
+  "capability_without_evidence",
+  "rejudge_summary_membership",
+  "definition_missing",
+  "boundary_missing",
+  "epistemic_exclusion",
+  "folder_only_evidence",
+  "slug_outside_kind_folder",
+  "uncertainty_missing",
+  "retire_starter_example"
+]
    • changedOutput schema / properties / postWriteMaintenance / properties / nextReviewAction / properties / kind / enum
      Previous value: -[
-  "inspect_compile_issue",
-  "break_dependency_cycle",
-  "canonicalize_graph_arrays",
-  "resolve_dangling_reference",
-  "add_missing_relation",
-  "materialize_external_element",
-  "unassigned_node",
-  "empty_domain",
-  "separate_evidence_from_concept",
-  "fold_bulk_siblings",
-  "retire_unearned_node",
-  "capability_without_evidence",
-  "rejudge_summary_membership"
-]New value: +[
+  "inspect_compile_issue",
+  "break_dependency_cycle",
+  "canonicalize_graph_arrays",
+  "resolve_dangling_reference",
+  "add_missing_relation",
+  "materialize_external_element",
+  "unassigned_node",
+  "empty_domain",
+  "separate_evidence_from_concept",
+  "fold_bulk_siblings",
+  "retire_unearned_node",
+  "capability_without_evidence",
+  "rejudge_summary_membership",
+  "definition_missing",
+  "boundary_missing",
+  "epistemic_exclusion",
+  "folder_only_evidence",
+  "slug_outside_kind_folder",
+  "uncertainty_missing",
+  "retire_starter_example"
+]
  2. Changed8 schema fields changedv1.2.5
    • addedOutput schema / properties / postWriteMaintenance / properties / actions / items / allOf
      Added value: +[
+  {
+    "if": {
+      "properties": {
+        "executable": {
+          "const": true
+        }
+      },
+      "required": [
+        "executable"
+      ]
+    },
+    "then": {
+      "properties": {
+        "proposedAction": {
+          "additionalProperties": false,
+          "properties": {
+            "args": {
+              "oneOf": [
+                {
+                  "additionalProperties": false,
+                  "properties": {
+                    "kind": {
+                      "enum": [
+                        "project",
+                        "domain",
+                        "capability",
+                        "element",
+                        "document",
+                        "vault-readme"
+                      ],
+                      "minLength": 1,
+                      "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                      "type": "string"
+                    },
+                    "slug": {
+                      "minLength": 1,
+                      "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                      "type": "string"
+                    },
+                    "title": {
+                      "minLength": 1,
+                      "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "slug",
+                    "kind",
+                    "title"
+                  ],
+                  "type": "object"
+                },
+                {
+                  "additionalProperties": false,
+                  "properties": {
+                    "from": {
+                      "minLength": 1,
+                      "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                      "type": "string"
+                    },
+                    "to": {
+                      "minLength": 1,
+                      "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                      "type": "string"
+                    },
+                    "type": {
+                      "enum": [
+                        "depends_on",
+                        "relates",
+                        "contains",
+                        "describes",
+                        "domains",
+                        "capabilities",
+                        "elements",
+                        "domain"
+                      ],
+                      "minLength": 1,
+                      "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                      "type": "string"
+                    },
+                    "why": {
+                      "description": "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.",
+                      "maxLength": 300,
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "from",
+                    "to",
+                    "type"
+                  ],
+                  "type": "object"
+                },
+                {
+                  "additionalProperties": false,
+                  "properties": {
+                    "expected_mtime": {
+                      "minimum": 0,
+                      "type": "number"
+                    },
+                    "frontmatter": {
+                      "additionalProperties": false,
+                      "properties": {
+                        "broader": {
+                          "items": {
+                            "minLength": 1,
+                            "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                            "type": "string"
+                          },
+                          "maxItems": 500,
+                          "type": "array"
+                        },
+                        "capabilities": {
+                          "items": {
+                            "minLength": 1,
+                            "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                            "type": "string"
+                          },
+                          "maxItems": 500,
+                          "type": "array"
+                        },
+                        "contains": {
+                          "items": {
+                            "minLength": 1,
+                            "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                            "type": "string"
+                          },
+                          "maxItems": 500,
+                          "type": "array"
+                        },
+                        "dependencies": {
+                          "items": {
+                            "minLength": 1,
+                            "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                            "type": "string"
+                          },
+                          "maxItems": 500,
+                          "type": "array"
+                        },
+                        "depends_on": {
+                          "items": {
+                            "minLength": 1,
+                            "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                            "type": "string"
+                          },
+                          "maxItems": 500,
+                          "type": "array"
+                        },
+                        "describes": {
+                          "items": {
+                            "minLength": 1,
+                            "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                            "type": "string"
+                          },
+                          "maxItems": 500,
+                          "type": "array"
+                        },
+                        "domains": {
+                          "items": {
+                            "minLength": 1,
+                            "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                            "type": "string"
+                          },
+                          "maxItems": 500,
+                          "type": "array"
+                        },
+                        "elements": {
+                          "items": {
+                            "minLength": 1,
+                            "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                            "type": "string"
+                          },
+                          "maxItems": 500,
+                          "type": "array"
+                        },
+                        "relates": {
+                          "items": {
+                            "minLength": 1,
+                            "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                            "type": "string"
+                          },
+                          "maxItems": 500,
+                          "type": "array"
+                        }
+                      },
+                      "type": "object"
+                    },
+                    "slug": {
+                      "minLength": 1,
+                      "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "slug",
+                    "frontmatter",
+                    "expected_mtime"
+                  ],
+                  "type": "object"
+                }
+              ]
+            },
+            "tool": {
+              "enum": [
+                "add_concept",
+                "add_relation",
+                "patch_concept"
+              ],
+              "minLength": 1,
+              "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+              "type": "string"
+            }
+          },
+          "required": [
+            "tool",
+            "args"
+          ],
+          "type": "object"
+        }
+      },
+      "required": [
+        "proposedAction"
+      ]
+    }
+  }
+]
    • changedOutput schema / properties / postWriteMaintenance / properties / actions / items / required
      Previous value: -[
-  "id",
-  "phase",
-  "kind",
-  "severity",
-  "score",
-  "executable",
-  "reason",
-  "proposedAction"
-]New value: +[
+  "id",
+  "phase",
+  "kind",
+  "severity",
+  "score",
+  "executable",
+  "reason"
+]
    • addedOutput schema / properties / postWriteMaintenance / properties / nextExecutableAction / allOf
      Added value: +[
+  {
+    "if": {
+      "properties": {
+        "executable": {
+          "const": true
+        }
+      },
+      "required": [
+        "executable"
+      ]
+    },
+    "then": {
+      "properties": {
+        "proposedAction": {
+          "additionalProperties": false,
+          "properties": {
+            "args": {
+              "oneOf": [
+                {
+                  "additionalProperties": false,
+                  "properties": {
+                    "kind": {
+                      "enum": [
+                        "project",
+                        "domain",
+                        "capability",
+                        "element",
+                        "document",
+                        "vault-readme"
+                      ],
+                      "minLength": 1,
+                      "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                      "type": "string"
+                    },
+                    "slug": {
+                      "minLength": 1,
+                      "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                      "type": "string"
+                    },
+                    "title": {
+                      "minLength": 1,
+                      "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "slug",
+                    "kind",
+                    "title"
+                  ],
+                  "type": "object"
+                },
+                {
+                  "additionalProperties": false,
+                  "properties": {
+                    "from": {
+                      "minLength": 1,
+                      "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                      "type": "string"
+                    },
+                    "to": {
+                      "minLength": 1,
+                      "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                      "type": "string"
+                    },
+                    "type": {
+                      "enum": [
+                        "depends_on",
+                        "relates",
+                        "contains",
+                        "describes",
+                        "domains",
+                        "capabilities",
+                        "elements",
+                        "domain"
+                      ],
+                      "minLength": 1,
+                      "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                      "type": "string"
+                    },
+                    "why": {
+                      "description": "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.",
+                      "maxLength": 300,
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "from",
+                    "to",
+                    "type"
+                  ],
+                  "type": "object"
+                },
+                {
+                  "additionalProperties": false,
+                  "properties": {
+                    "expected_mtime": {
+                      "minimum": 0,
+                      "type": "number"
+                    },
+                    "frontmatter": {
+                      "additionalProperties": false,
+                      "properties": {
+                        "broader": {
+                          "items": {
+                            "minLength": 1,
+                            "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                            "type": "string"
+                          },
+                          "maxItems": 500,
+                          "type": "array"
+                        },
+                        "capabilities": {
+                          "items": {
+                            "minLength": 1,
+                            "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                            "type": "string"
+                          },
+                          "maxItems": 500,
+                          "type": "array"
+                        },
+                        "contains": {
+                          "items": {
+                            "minLength": 1,
+                            "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                            "type": "string"
+                          },
+                          "maxItems": 500,
+                          "type": "array"
+                        },
+                        "dependencies": {
+                          "items": {
+                            "minLength": 1,
+                            "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                            "type": "string"
+                          },
+                          "maxItems": 500,
+                          "type": "array"
+                        },
+                        "depends_on": {
+                          "items": {
+                            "minLength": 1,
+                            "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                            "type": "string"
+                          },
+                          "maxItems": 500,
+                          "type": "array"
+                        },
+                        "describes": {
+                          "items": {
+                            "minLength": 1,
+                            "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                            "type": "string"
+                          },
+                          "maxItems": 500,
+                          "type": "array"
+                        },
+                        "domains": {
+                          "items": {
+                            "minLength": 1,
+                            "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                            "type": "string"
+                          },
+                          "maxItems": 500,
+                          "type": "array"
+                        },
+                        "elements": {
+                          "items": {
+                            "minLength": 1,
+                            "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                            "type": "string"
+                          },
+                          "maxItems": 500,
+                          "type": "array"
+                        },
+                        "relates": {
+                          "items": {
+                            "minLength": 1,
+                            "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                            "type": "string"
+                          },
+                          "maxItems": 500,
+                          "type": "array"
+                        }
+                      },
+                      "type": "object"
+                    },
+                    "slug": {
+                      "minLength": 1,
+                      "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "slug",
+                    "frontmatter",
+                    "expected_mtime"
+                  ],
+                  "type": "object"
+                }
+              ]
+            },
+            "tool": {
+              "enum": [
+                "add_concept",
+                "add_relation",
+                "patch_concept"
+              ],
+              "minLength": 1,
+              "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+              "type": "string"
+            }
+          },
+          "required": [
+            "tool",
+            "args"
+          ],
+          "type": "object"
+        }
+      },
+      "required": [
+        "proposedAction"
+      ]
+    }
+  }
+]
    • changedOutput schema / properties / postWriteMaintenance / properties / nextExecutableAction / required
      Previous value: -[
-  "id",
-  "phase",
-  "kind",
-  "severity",
-  "score",
-  "executable",
-  "reason",
-  "proposedAction"
-]New value: +[
+  "id",
+  "phase",
+  "kind",
+  "severity",
+  "score",
+  "executable",
+  "reason"
+]
    • addedOutput schema / properties / postWriteMaintenance / properties / nextReviewAction / allOf
      Added value: +[
+  {
+    "if": {
+      "properties": {
+        "executable": {
+          "const": true
+        }
+      },
+      "required": [
+        "executable"
+      ]
+    },
+    "then": {
+      "properties": {
+        "proposedAction": {
+          "additionalProperties": false,
+          "properties": {
+            "args": {
+              "oneOf": [
+                {
+                  "additionalProperties": false,
+                  "properties": {
+                    "kind": {
+                      "enum": [
+                        "project",
+                        "domain",
+                        "capability",
+                        "element",
+                        "document",
+                        "vault-readme"
+                      ],
+                      "minLength": 1,
+                      "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                      "type": "string"
+                    },
+                    "slug": {
+                      "minLength": 1,
+                      "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                      "type": "string"
+                    },
+                    "title": {
+                      "minLength": 1,
+                      "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "slug",
+                    "kind",
+                    "title"
+                  ],
+                  "type": "object"
+                },
+                {
+                  "additionalProperties": false,
+                  "properties": {
+                    "from": {
+                      "minLength": 1,
+                      "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                      "type": "string"
+                    },
+                    "to": {
+                      "minLength": 1,
+                      "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                      "type": "string"
+                    },
+                    "type": {
+                      "enum": [
+                        "depends_on",
+                        "relates",
+                        "contains",
+                        "describes",
+                        "domains",
+                        "capabilities",
+                        "elements",
+                        "domain"
+                      ],
+                      "minLength": 1,
+                      "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                      "type": "string"
+                    },
+                    "why": {
+                      "description": "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.",
+                      "maxLength": 300,
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "from",
+                    "to",
+                    "type"
+                  ],
+                  "type": "object"
+                },
+                {
+                  "additionalProperties": false,
+                  "properties": {
+                    "expected_mtime": {
+                      "minimum": 0,
+                      "type": "number"
+                    },
+                    "frontmatter": {
+                      "additionalProperties": false,
+                      "properties": {
+                        "broader": {
+                          "items": {
+                            "minLength": 1,
+                            "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                            "type": "string"
+                          },
+                          "maxItems": 500,
+                          "type": "array"
+                        },
+                        "capabilities": {
+                          "items": {
+                            "minLength": 1,
+                            "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                            "type": "string"
+                          },
+                          "maxItems": 500,
+                          "type": "array"
+                        },
+                        "contains": {
+                          "items": {
+                            "minLength": 1,
+                            "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                            "type": "string"
+                          },
+                          "maxItems": 500,
+                          "type": "array"
+                        },
+                        "dependencies": {
+                          "items": {
+                            "minLength": 1,
+                            "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                            "type": "string"
+                          },
+                          "maxItems": 500,
+                          "type": "array"
+                        },
+                        "depends_on": {
+                          "items": {
+                            "minLength": 1,
+                            "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                            "type": "string"
+                          },
+                          "maxItems": 500,
+                          "type": "array"
+                        },
+                        "describes": {
+                          "items": {
+                            "minLength": 1,
+                            "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                            "type": "string"
+                          },
+                          "maxItems": 500,
+                          "type": "array"
+                        },
+                        "domains": {
+                          "items": {
+                            "minLength": 1,
+                            "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                            "type": "string"
+                          },
+                          "maxItems": 500,
+                          "type": "array"
+                        },
+                        "elements": {
+                          "items": {
+                            "minLength": 1,
+                            "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                            "type": "string"
+                          },
+                          "maxItems": 500,
+                          "type": "array"
+                        },
+                        "relates": {
+                          "items": {
+                            "minLength": 1,
+                            "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                            "type": "string"
+                          },
+                          "maxItems": 500,
+                          "type": "array"
+                        }
+                      },
+                      "type": "object"
+                    },
+                    "slug": {
+                      "minLength": 1,
+                      "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "slug",
+                    "frontmatter",
+                    "expected_mtime"
+                  ],
+                  "type": "object"
+                }
+              ]
+            },
+            "tool": {
+              "enum": [
+                "add_concept",
+                "add_relation",
+                "patch_concept"
+              ],
+              "minLength": 1,
+              "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+              "type": "string"
+            }
+          },
+          "required": [
+            "tool",
+            "args"
+          ],
+          "type": "object"
+        }
+      },
+      "required": [
+        "proposedAction"
+      ]
+    }
+  }
+]
    • changedOutput schema / properties / postWriteMaintenance / properties / nextReviewAction / required
      Previous value: -[
-  "id",
-  "phase",
-  "kind",
-  "severity",
-  "score",
-  "executable",
-  "reason",
-  "proposedAction"
-]New value: +[
+  "id",
+  "phase",
+  "kind",
+  "severity",
+  "score",
+  "executable",
+  "reason"
+]
    • addedOutput schema / properties / postWriteMaintenance / properties / summary / properties / capabilitiesWithoutEvidence
      Added value: +{
+  "minimum": 0,
+  "type": "integer"
+}
    • changedOutput schema / properties / postWriteMaintenance / properties / summary / required
      Previous value: -[
-  "totalActions",
-  "filteredActions",
-  "remainingActions",
-  "executableActions",
-  "reviewActions",
-  "compileIssues",
-  "dependencyCycles",
-  "canonicalizationActions",
-  "danglingReferences",
-  "relationRecommendations",
-  "externalElementRefs",
-  "externalElementRefsIgnored",
-  "unassignedNodes",
-  "emptyDomains"
-]New value: +[
+  "totalActions",
+  "filteredActions",
+  "remainingActions",
+  "executableActions",
+  "reviewActions",
+  "compileIssues",
+  "dependencyCycles",
+  "canonicalizationActions",
+  "danglingReferences",
+  "relationRecommendations",
+  "externalElementRefs",
+  "externalElementRefsIgnored",
+  "unassignedNodes",
+  "emptyDomains",
+  "capabilitiesWithoutEvidence"
+]
  3. First observedv0.13.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations say readOnlyHint=false, but the description goes far beyond that: it discloses that duplicate slugs throw, frontmatter is normalized per kind, missing extras and near-duplicate titles come back as warnings rather than errors, and successful writes return a detailed postWriteMaintenance payload. This rich behavioral detail is independent of and complementary to 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?

The description is long, but the tool is complex and the length is generally earned. It front-loads the core action and error condition, then proceeds through normalization, warnings, response shape, bulk usage, and naming constraints. There is some redundancy between the title-role rule and the slug rule, and the response details could be trimmed, but it remains logically organized and useful.

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 9-parameter mutation tool with an output schema, the description is unusually complete: it covers when to use it, when not to, duplicate handling, warning behavior, response contents, bulk alternative, parent/domain expectations, and naming rejection rules. Nothing an agent needs to invoke the tool 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 description coverage is 100%, so the baseline is 3, but the description adds meaningful context on top: slug must be flat under the kind folder and never a code path, capability/element should set domain, and title should name a role rather than a file path. This goes beyond the schema's field descriptions, though it does not deepen every parameter.

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 opens with a specific verb and resource: 'Create a new ontology node (.md file).' It immediately distinguishes add_concept from its siblings by naming patch_concept for existing slugs and add_concepts for bulk creation. This makes the tool's role unambiguous.

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 states when to call the tool ('Call when an AI agent finds a new capability / element / project from code analysis') and gives concrete alternatives: use patch_concept when the slug already exists or when a near-duplicate title is found, and use add_concepts for batch creation. This is explicit when/when-not guidance.

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

Deploy Server

Other Tools