topos-mcp

Overview Schema Source Related Servers Discussions Admin

topos_inspect_code

Instructions

Full metric breakdown for a single code unit (inline string or file). Provide exactly one of code or filepath. Use when you need the per-function detail behind a verdict; use topos_evaluate_* when the medal alone is enough. Returns an InspectionResult: the lattice evaluation, a top-N function complexity table (top_n_functions, default 10), total_functions, and entropy details. With filepath, the verdict is scored on all four generators and agrees with topos_evaluate_file: unless no_composable is set, this generates/refreshes .gitnexus (given by gitnexus_dir or auto-detected at <root>/.gitnexus) when missing or stale, then attaches the ModuleDependencyGraph — so this tool is side-effecting. With inline code there is no module to place in the graph, so only SIMPLE/SECURE/NAVIGABLE are reachable, as in topos_evaluate_code. Do not call after topos_evaluate_file already returned a passing verdict or a refactor_targets span. This is the detail view, not the next step.

Input Schema

Name	Required	Description	Default
`code`	No	Inline source code.
`allow`	No	One-off acknowledged dangerous-call patterns for this inspection.
`verbose`	No	Include raw probe metric floats under each file in the response.
`filepath`	No	Source file path inside the project root (prefer for large files).
`language`	No	Language for inline `code`; ignored for `filepath`, which is autodetected from the file extension.	python
`preferences`	No	Strict total order on the four generators; see `topos://docs/preferences`.
`gitnexus_dir`	No	`.gitnexus` store under the file root (default: `<file root>/.gitnexus`); only used with `filepath`.
`no_composable`	No	Use no dependency graph, even an existing `.gitnexus`; score SIMPLE/SECURE/NAVIGABLE only.
`top_n_functions`	No	Return at most this many functions, sorted by descending cyclomatic complexity. Keeps agent context lean on large files.

Schema Changelog

Changes observed during successful MCP inspections.

Changed10 schema fields changedv0.11.0Oct 14, 2026

addedInput schema / properties / code / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

addedInput schema / properties / code / description
```
Added value: +"Inline source code."
```

removedInput schema / properties / code / type

Removed value: -[
-  "string",
-  "null"
-]

addedInput schema / properties / filepath / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / filepath / description

Previous value: -"Path to the source file inside the project root. Prefer this for\nlarge files."New value: +"Source file path inside the project root (prefer for large files)."

removedInput schema / properties / filepath / type
```
Removed value: -[
-  "string",
-  "null"
-]
```

addedInput schema / properties / gitnexus_dir / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / gitnexus_dir / description

Previous value: -"`.gitnexus` store under the MCP file root (default:\n`<file root>/.gitnexus`). Freshness/regeneration use the file root\nas the project root; this only selects the store path. Only used\nwith `filepath` — inline `code` has no module to place in the graph."New value: +"`.gitnexus` store under the file root (default: `<file root>/.gitnexus`);\nonly used with `filepath`."

removedInput schema / properties / gitnexus_dir / type
```
Removed value: -[
-  "string",
-  "null"
-]
```

changedInput schema / properties / no_composable / description

Previous value: -"Skip GitNexus generation; score whatever `.gitnexus` is already\nthere, or SIMPLE/SECURE/NAVIGABLE only when there is none."New value: +"Use no dependency graph, even an existing `.gitnexus`; score\nSIMPLE/SECURE/NAVIGABLE only."

Changed7 schema fields changedv0.5.0Aug 9, 2026

changedInput schema / $defs / GeneratorInput / enum

Previous value: -[
-  "simple",
-  "composable",
-  "secure"
-]New value: +[
+  "simple",
+  "composable",
+  "secure",
+  "navigable"
+]

changedInput schema / $defs / LatticeElement / description

Previous value: -"The 8 elements of the free Heyting algebra H(G_qual) on the three\ngenerators SIMPLE, COMPOSABLE, SECURE, mirroring `EvaluationValue` on\nthe MCP wire."New value: +"The 16 elements of the free Heyting algebra H(G_qual) on the four\ngenerators SIMPLE, COMPOSABLE, SECURE, NAVIGABLE, mirroring\n`EvaluationValue` on the MCP wire.\n\nNote for clients pinned to the pre-v0.5.0 shape: `IDEAL` now requires\nall four pillars. The verdict that used to be `IDEAL` — the top of the\nthree-generator algebra — serializes as `SIMPLE_COMPOSABLE_SECURE`.\nVariants are declared in **bitmask order**, matching\n`EvaluationValue::ALL`, so the two enums convert by position. Serde\nkeys on variant names, so this ordering is an implementation detail\nand not part of the wire contract."

changedInput schema / $defs / LatticeElement / enum

Previous value: -[
-  "SLOP",
-  "SIMPLE",
-  "COMPOSABLE",
-  "SECURE",
-  "SIMPLE_COMPOSABLE",
-  "SIMPLE_SECURE",
-  "COMPOSABLE_SECURE",
-  "IDEAL"
-]New value: +[
+  "SLOP",
+  "SIMPLE",
+  "COMPOSABLE",
+  "SIMPLE_COMPOSABLE",
+  "SECURE",
+  "SIMPLE_SECURE",
+  "COMPOSABLE_SECURE",
+  "SIMPLE_COMPOSABLE_SECURE",
+  "NAVIGABLE",
+  "SIMPLE_NAVIGABLE",
+  "COMPOSABLE_NAVIGABLE",
+  "SIMPLE_COMPOSABLE_NAVIGABLE",
+  "SECURE_NAVIGABLE",
+  "SIMPLE_SECURE_NAVIGABLE",
+  "COMPOSABLE_SECURE_NAVIGABLE",
+  "IDEAL"
+]

changedInput schema / $defs / UserPreferencesInput / description

Previous value: -"Strict ranking over simple, composable, and secure."New value: +"Strict ranking over simple, composable, secure, and navigable."

changedInput schema / $defs / UserPreferencesInput / properties / ranking / description

Previous value: -"Permutation of simple/composable/secure, best first."New value: +"Permutation of simple/composable/secure/navigable, best first."

changedInput schema / properties / no_composable / description

Previous value: -"Skip GitNexus generation; score whatever `.gitnexus` is already\nthere, or SIMPLE/SECURE only when there is none."New value: +"Skip GitNexus generation; score whatever `.gitnexus` is already\nthere, or SIMPLE/SECURE/NAVIGABLE only when there is none."

changedInput schema / properties / preferences / description

Previous value: -"Strict total order on the three generators; see\n`topos://docs/preferences`."New value: +"Strict total order on the four generators; see\n`topos://docs/preferences`."

Changed1 schema field changedv0.4.4Aug 5, 2026

changedInput schema / properties / gitnexus_dir / description

Previous value: -".gitnexus directory for COMPOSABLE scoring. When omitted, it is\nauto-detected at `<file root>/.gitnexus`; if missing or stale, this\ntool generates/refreshes it first (see `no_composable`). Only used\nwith `filepath` — inline `code` has no module to place in the graph."New value: +"`.gitnexus` store under the MCP file root (default:\n`<file root>/.gitnexus`). Freshness/regeneration use the file root\nas the project root; this only selects the store path. Only used\nwith `filepath` — inline `code` has no module to place in the graph."

Changed13 schema fields changedv0.4.0Jul 27, 2026

addedInput schema / $defs

Added value: +{
+  "GeneratorInput": {
+    "description": "Wire form of a generator name.",
+    "enum": [
+      "simple",
+      "composable",
+      "secure"
+    ],
+    "type": "string"
+  },
+  "LatticeElement": {
+    "description": "The 8 elements of the free Heyting algebra H(G_qual) on the three\ngenerators SIMPLE, COMPOSABLE, SECURE, mirroring `EvaluationValue` on\nthe MCP wire.",
+    "enum": [
+      "SLOP",
+      "SIMPLE",
+      "COMPOSABLE",
+      "SECURE",
+      "SIMPLE_COMPOSABLE",
+      "SIMPLE_SECURE",
+      "COMPOSABLE_SECURE",
+      "IDEAL"
+    ],
+    "type": "string"
+  },
+  "UserPreferencesInput": {
+    "additionalProperties": false,
+    "description": "Strict ranking over simple, composable, and secure.",
+    "properties": {
+      "ranking": {
+        "description": "Permutation of simple/composable/secure, best first.",
+        "items": {
+          "$ref": "#/$defs/GeneratorInput"
+        },
+        "type": "array"
+      },
+      "target": {
+        "anyOf": [
+          {
+            "$ref": "#/$defs/LatticeElement"
+          },
+          {
+            "type": "null"
+          }
+        ],
+        "default": null,
+        "description": "Optional explicit target verdict."
+      }
+    },
+    "required": [
+      "ranking"
+    ],
+    "type": "object"
+  }
+}

addedInput schema / $schema

Added value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / properties / allow

Added value: +{
+  "default": [],
+  "description": "One-off acknowledged dangerous-call patterns for this inspection.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / code

Added value: +{
+  "default": null,
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedInput schema / properties / filepath

Added value: +{
+  "default": null,
+  "description": "Path to the source file inside the project root. Prefer this for\nlarge files.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedInput schema / properties / gitnexus_dir

Added value: +{
+  "default": null,
+  "description": ".gitnexus directory for COMPOSABLE scoring. When omitted, it is\nauto-detected at `<file root>/.gitnexus`; if missing or stale, this\ntool generates/refreshes it first (see `no_composable`). Only used\nwith `filepath` — inline `code` has no module to place in the graph.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedInput schema / properties / language

Added value: +{
+  "default": "python",
+  "description": "Language for inline `code`; ignored for `filepath`, which is\nautodetected from the file extension.",
+  "type": "string"
+}

addedInput schema / properties / no_composable

Added value: +{
+  "default": false,
+  "description": "Skip GitNexus generation; score whatever `.gitnexus` is already\nthere, or SIMPLE/SECURE only when there is none.",
+  "type": "boolean"
+}

removedInput schema / properties / params

Removed value: -{
-  "additionalProperties": false,
-  "description": "Arguments for ``topos_inspect_code``.",
-  "properties": {
-    "allow": {
-      "description": "One-off acknowledged dangerous-call patterns for this inspection. Mirrors CLI --allow and is fully disclosed in the evaluation.",
-      "items": {
-        "type": "string"
-      },
-      "type": "array"
-    },
-    "code": {
-      "anyOf": [
-        {
-          "minLength": 1,
-          "type": "string"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null
-    },
-    "filepath": {
-      "anyOf": [
-        {
-          "minLength": 1,
-          "type": "string"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "description": "Path to the source file inside the project root. Prefer this for large files."
-    },
-    "language": {
-      "default": "python",
-      "description": "Language for inline `code`; ignored for `filepath`, which is autodetected from the file extension.",
-      "type": "string"
-    },
-    "preferences": {
-      "anyOf": [
-        {
-          "additionalProperties": false,
-          "description": "Strict ranking over simple, composable, and secure.",
-          "properties": {
-            "ranking": {
-              "description": "Permutation of simple/composable/secure, best first.",
-              "items": {
-                "description": "The three quality generators of ``G_qual``.",
-                "enum": [
-                  "simple",
-                  "composable",
-                  "secure"
-                ],
-                "type": "string"
-              },
-              "maxItems": 3,
-              "minItems": 3,
-              "type": "array"
-            },
-            "target": {
-              "anyOf": [
-                {
-                  "description": "The 8 quality verdicts, from SLOP (none) to IDEAL (simple+composable+secure).",
-                  "enum": [
-                    "SLOP",
-                    "SIMPLE",
-                    "COMPOSABLE",
-                    "SECURE",
-                    "SIMPLE_COMPOSABLE",
-                    "SIMPLE_SECURE",
-                    "COMPOSABLE_SECURE",
-                    "IDEAL"
-                  ],
-                  "type": "string"
-                },
-                {
-                  "type": "null"
-                }
-              ],
-              "default": null,
-              "description": "Optional explicit target verdict."
-            }
-          },
-          "required": [
-            "ranking"
-          ],
-          "type": "object"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "description": "Strict total order on the three generators; see ``topos://docs/preferences``."
-    },
-    "top_n_functions": {
-      "default": 10,
-      "description": "Return at most this many functions, sorted by descending cyclomatic complexity. Keeps agent context lean on large files.",
-      "maximum": 200,
-      "minimum": 1,
-      "type": "integer"
-    },
-    "verbose": {
-      "default": false,
-      "description": "Include raw probe metric floats under each file in the response.",
-      "type": "boolean"
-    }
-  },
-  "type": "object"
-}

addedInput schema / properties / preferences

Added value: +{
+  "anyOf": [
+    {
+      "$ref": "#/$defs/UserPreferencesInput"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Strict total order on the three generators; see\n`topos://docs/preferences`."
+}

addedInput schema / properties / top_n_functions

Added value: +{
+  "default": 10,
+  "description": "Return at most this many functions, sorted by descending cyclomatic\ncomplexity. Keeps agent context lean on large files.",
+  "format": "uint",
+  "minimum": 0,
+  "type": "integer"
+}

addedInput schema / properties / verbose

Added value: +{
+  "default": false,
+  "description": "Include raw probe metric floats under each file in the response.",
+  "type": "boolean"
+}

removedInput schema / required
```
Removed value: -[
-  "params"
-]
```

First observedv0.3.6Jul 2, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations only say readOnlyHint=false/idempotentHint=false; the description adds the crucial behavioral detail beyond them — that filepath mode generates/refreshes `.gitnexus` and attaches a ModuleDependencyGraph, so the call is side-effecting, and that inline code can only reach SIMPLE/SECURE/NAVIGABLE. It also sketches the return shape (InspectionResult, lattice evaluation, top-N table, total_functions, entropy).

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?

Long but dense and front-loaded: the core purpose and the code/filepath rule come first, and the alternatives/exclusion come next. Nearly every sentence carries a distinct fact (generator reachability, side-effect, sibling routing); a little could be tightened but nothing is padding.

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-param, no-output-schema tool this covers the essentials: input exclusivity, side effects, which generators apply per mode, and the return payload. Nothing an agent needs to invoke it correctly or avoid misusing it 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 real meaning: the code-vs-filepath exclusivity, top_n_functions' default of 10 as a context-lean measure, gitnexus_dir's auto-detection path, and no_composable's effect on scoring. It stops short of documenting allow/language/verbose/preferences beyond the schema.

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+resource ('Full metric breakdown for a single code unit') and explicitly contrasts itself with the sibling family: detail view vs. the medal-only topos_evaluate_*. An agent can tell it apart from topos_evaluate_file and topos_evaluate_code without opening any schema.

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 selection criteria ('use when you need the per-function detail behind a verdict; use topos_evaluate_* when the medal alone is enough') and a hard exclusion ('Do not call after topos_evaluate_file already returned a passing verdict or a refactor_targets span'). Also states the code/filepath mutual-exclusivity constraint.

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

Deploy Server

topos_inspect_code

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools