ontology-atlas

Overview Schema Source Related Servers Discussions Admin

add_concepts

Batch-create up to 50 ontology concepts in a single call, with per-row error reporting and duplicate warnings. Use after reviewing proposed concepts to reduce round-trips.

Instructions

Batch-create multiple nodes in one call — same per-row shape as add_concept. Use after analyze_repo_structure or another reviewed proposal flow when the agent has K accepted candidates from the user — replaces K×add_concept round-trips. Each row is processed independently: existing-slug / invalid-kind / missing-required-fields / non-object row shape / unknown row fields surface as { slug, ok: false, error } rows whose errors include a concepts[n] row label, single unknown-field rows include receivedField plus one-row unknownFields, multi unknown-field rows report every unknown field with nearest hints and Received fields: ..., and duplicate input slugs report the later concepts[n] row plus first-seen concepts[m] with structured rowName / firstSeenAt; the rest still land. A row whose normalized title matches an earlier landed row in the same batch still lands but carries a near-duplicate warning — patch_concept the earlier node instead of forking the same concept (duplicates are the #1 growing-vault failure mode). concepts[] order in the response matches the input. Cap = 50 per call (split into multiple batches for larger sets). NO atomic rollback — if you need all-or-nothing semantics use single add_concept calls. Invalid-only batches return no row-level write metadata and no top-level postWriteMaintenance. When at least one row changes the vault, the response includes one 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. Rows whose title is a bare file path follow the same rule as add_concept above. Prefer one capability node covering a directory plus a short elements: list over one row per file, unless each file's role differs in a stated sentence.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`concepts`	Yes	Array of concept specs (max 50). Each row uses the same shape as `add_concept` input.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`concepts`	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.

Changed4 schema fields changedv1.3.0Sep 23, 2026

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"
+]

Changed8 schema fields changedv1.2.5Sep 15, 2026

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"
+]

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 (which are sparse: readOnlyHint=false etc.) by disclosing: per-row independent processing, error row shapes (including field-level details like `receivedField` and `unknownFields`), handling of duplicate slugs, near-duplicate detection with warnings, response order, the 50-cap, no atomic rollback, and the presence of `postWriteMaintenance` when at least one row changes the vault. It even provides domain-specific warnings (duplicates are the #1 failure mode). This level of disclosure is exceptional and far exceeds the annotations' minimal hints.

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 every sentence serves a purpose: it defines scope, usage, error handling, batch limit, atomicity, and maintenance output. It is front-loaded with the core purpose and alternates. However, it is arguably dense and could be trimmed, but for a complex batch operation, the length is justified and well-structured.

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 complexity, the output schema, and the 1-parameter schema that is fully documented, the description covers everything an agent needs: when to use, error handling, batch limits, post-write maintenance, and even best practices for grouping nodes. There is no significant missing guidance for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already covers 100% of the parameter (`concepts` with nested objects) and includes a description for the array indicating it uses the same shape as `add_concept` input. The tool description doesn't re-describe the parameters but does add context about row-level error handling and warns about `elements` and `labels` (e.g., fill both locales). Since schema coverage is high, baseline is 3, which is appropriate here.

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 starts with a clear verb-resource pair: 'Batch-create multiple nodes in one call' and immediately contrasts with the single-node `add_concept`. It specifies the exact use case (after `analyze_repo_structure` or similar) and the interface (same per-row shape as `add_concept`), distinguishing it from siblings. This is specific and 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 use it: 'Use after `analyze_repo_structure` or another reviewed proposal flow when the agent has K accepted candidates.' It also gives the alternative: 'replaces K×`add_concept` round-trips' and provides exclusions: 'if you need all-or-nothing semantics use single `add_concept` calls' and 'split into multiple batches for larger sets.' This is exemplary usage guidance.

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