ontology-atlas

Overview Schema Source Related Servers Discussions Admin

index_project

Read-only

Create a read-only, resumable ontology indexing plan that combines structure analysis, import inference, and validation, returning review-ready candidates and checkpoints before any writes.

Instructions

Project ontology indexing plan — run analyze_repo_structure + infer_imports + validate_vault in one read-only call. Use for large or already-existing projects where the agent needs a resumable ontology indexing checkpoint before writing. Its extractionContract treats source facts as observed evidence, README/folder meanings as proposals, and only persisted ontology meanings as shared; it also returns competency questions, uncertainty, approval gates, and whether active-vault validation actually applies to the analyzed project. The plan distinguishes raw candidates into existing, ambiguous-alias review, and genuinely new buckets, then returns exact reviewCalls for retrieving full rows. side effect 0: this tool never writes markdown. CLI index --apply may write analyzer-proposed concepts and containment, but inferred imports remain review-only and are never auto-promoted to depends_on.

Input Schema

Name	Required	Description
`maxDepth`	No	Forwarded to analyze_repo_structure, which ignores it, so no value changes the analysis. When given, it must be an integer from 0 to 10.
`maxFiles`	No	File cap forwarded to infer_imports (default 5000, max 50000).
`rootPath`	No	Repository root to index. Defaults to the active resolved repository root from connection_info.
`threshold`	No	Optional module-edge count threshold for the returned import relation plan.
`skipImports`	No	When true, skip infer_imports and return an analyze + validate plan only.

Output Schema

Name	Required	Description	Default
`mode`	Yes
`next`	Yes
`plan`	Yes
`analyze`	Yes
`imports`	Yes
`rootPath`	Yes
`vaultRoot`	Yes
`sideEffect`	Yes
`validation`	Yes
`meaningGate`	Yes
`semanticEvidence`	Yes
`extractionContract`	Yes
`configurationEvidence`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.8.0Oct 24, 2026

addedOutput schema / properties / semanticEvidence / items / properties / excerptInfo

Added value: +{
+  "additionalProperties": false,
+  "description": "Coverage of selected authored prose only, not the complete document. Replay nextSourceRead through analyze_repo_structure with sourceOnly:true; existing read bounds and refusals still apply.",
+  "properties": {
+    "firstOmittedLine": {
+      "minimum": 1,
+      "type": [
+        "integer",
+        "null"
+      ]
+    },
+    "nextSourceRead": {
+      "additionalProperties": false,
+      "properties": {
+        "expectedSha256": {
+          "pattern": "^[a-f0-9]{64}$",
+          "type": "string"
+        },
+        "maxLines": {
+          "maximum": 200,
+          "minimum": 1,
+          "type": "integer"
+        },
+        "path": {
+          "minLength": 1,
+          "pattern": "^(?!\\s)(?!.*\\s$)(?!.*\\u0000).+$",
+          "type": "string"
+        },
+        "startLine": {
+          "minimum": 1,
+          "type": "integer"
+        }
+      },
+      "required": [
+        "path",
+        "startLine",
+        "maxLines",
+        "expectedSha256"
+      ],
+      "type": [
+        "object",
+        "null"
+      ]
+    },
+    "scope": {
+      "enum": [
+        "selected_prose"
+      ],
+      "type": "string"
+    },
+    "truncated": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "scope",
+    "truncated",
+    "firstOmittedLine",
+    "nextSourceRead"
+  ],
+  "type": "object"
+}

changedOutput schema / properties / semanticEvidence / items / properties / riskFlags / items / enum

Previous value: -[
-  "instruction-injection",
-  "ontology-write-instruction",
-  "future-state-claim",
-  "negated-claim",
-  "deprecated-state"
-]New value: +[
+  "instruction-injection",
+  "ontology-write-instruction",
+  "future-state-claim",
+  "negated-claim",
+  "deprecated-state",
+  "excerpt-truncated"
+]

Changed1 schema field changedv1.4.0Oct 1, 2026

changedInput schema / properties / maxDepth / description

Previous value: -"Folder walk depth forwarded to analyze_repo_structure (default 2, max 10)."New value: +"Forwarded to analyze_repo_structure, which ignores it, so no value changes the analysis. When given, it must be an integer from 0 to 10."

First observedv0.13.0Sep 11, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Despite annotations, the description adds substantial behavioural context the annotations cannot: side effect 0, never writes markdown, the CLI apply variant does write analyzer-proposed concepts but inferred imports stay review-only, and the extractionContract's evidence-tier policy for source facts vs README meanings vs persisted ontology. This is exactly the kind of caveat an agent needs before trusting the plan as a write-free checkpoint.

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?

Front-loaded with the composite nature and read-only guarantee, then the evidence-tier and side-effect caveats. Dense but each sentence carries substantive information; the long middle sentence about extractionContract is heavy but earns its place. Minor jargon (reviewCalls, extractionContract) assumes familiarity.

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 an output schema exists, the description need not enumerate return fields, yet it still names the important outputs (competency questions, uncertainty, approval gates, candidate buckets, reviewCalls, validation applicability). Combined with annotations covering safety and full schema coverage on parameters, nothing needed to invoke correctly is missing.

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?

Schema description coverage is 100%, so the schema already documents all five parameters including maxDepth being ignored. The description adds no parameter-level detail (skipImports, maxFiles, threshold are only in the schema), so baseline 3 applies.

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 verb and resource ('Project ontology indexing plan') and defines it precisely as a composite of analyze_repo_structure + infer_imports + validate_vault in one read-only call. An agent can distinguish it from the individual sibling tools without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear condition for use ('large or already-existing projects where the agent needs a resumable ontology indexing checkpoint before writing') and contrasts it with the CLI `index --apply` write path. It does not explicitly say when to prefer the sibling primitives (analyze_repo_structure, infer_imports) instead, so it falls short of full routing guidance.

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