topos-mcp

Overview Schema Source Related Servers Discussions Admin

topos_inspect_code

Inspect a code unit to get its full metric breakdown: lattice evaluation, top-N function complexity, and entropy details.

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

TableJSON Schema

Name	Required	Description	Default
`code`	No
`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	Path to the source file inside the project root. Prefer this 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 MCP file root (default: `<file root>/.gitnexus`). Freshness/regeneration use the file root as the project root; this only selects the store path. Only used with `filepath` — inline `code` has no module to place in the graph.
`no_composable`	No	Skip GitNexus generation; score whatever `.gitnexus` is already there, or SIMPLE/SECURE/NAVIGABLE only when there is none.
`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.

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.7/5.0

Behavior5/5

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

Annotations only flag readOnlyHint=false and openWorldHint=true; the description supplies the crucial missing context that this is side-effecting, generating/refreshing `.gitnexus` when stale. It also discloses the divergence between the filepath path (all four generators) and inline code (only SIMPLE/SECURE/NAVIGABLE), and what the return contains.

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 purpose and the code-vs-filepath constraint are front-loaded, and most sentences earn their place. It is nonetheless a dense, long block of technically loaded prose for a 9-param tool, so a slight deduction for density rather than concision.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex 9-param tool with no output schema, the description covers the return shape (InspectionResult, evaluation lattice, top-N table, total_functions, entropy) and the side-effecting behavior. It is largely complete, though the jargon-heavy return description could be clearer for an agent.

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 already 89%, and the description still adds cross-parameter meaning: 'exactly one of `code` or `filepath`', that `language` is ignored for filepath, and the interaction of `gitnexus_dir`/`no_composable` with generation. Minor unused params (`verbose`, `allow`, `preferences`) get no description treatment, so not a full 5.

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: a 'full metric breakdown for a single code unit' distinguishing the detail view from the verdict-only view. It explicitly contrasts itself with `topos_evaluate_*` and `topos_evaluate_file`, so an agent can tell it apart from siblings without opening a 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 when-to-use ('when you need the per-function detail behind a verdict'), when-not ('use `topos_evaluate_*` when the medal alone is enough'), and an exclusion ('Do not call after `topos_evaluate_file` already returned a passing verdict or a refactor_targets span'). Routing is unambiguous.

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