ShadowGit MCP Server

Overview Schema Source Related Servers Discussions Admin

Read a range's Lens

get_lens

Read-onlyIdempotent

Read the ShadowGit Lens for a snapshot range—default: latest AI session—to inspect steps, code, canvas components/flows, dependency changes, and rule-named links before writing session words.

Instructions

Read ShadowGit's Lens of a range of snapshots, by default the latest AI session's: its steps with their code, the cards (components) and flows on its canvas, each with an id and its words so far; what the range makes depend on what: each new, gone or two-way dependency between the project's areas and layers, with the links that make it and the steps that hold it; and each of the project's rules (.shadowgit-rules) that names a link the range adds, with its reason, links and steps, also for a range with no Lens. Read it at the end of a session, after the checkpoint, to word it with write_lens_words; your words may say why a dependency appeared, or why a link a rule names is there: say the rule names it, and quote the rule. Needs the ShadowGit app running.

Input Schema

Name	Required	Description
`base`	No	The snapshot the range starts from, with head (null: the start of the history). Leave both out for the latest AI session
`head`	No	The range's newest snapshot; leave out for the latest AI session
`repo`	No	Project name or absolute path. Defaults to the current project.

Output Schema

Name	Required	Description
`lens`	Yes
`repo`	Yes
`range`	Yes
`rules`	No	The range checked against the project's rules, also for a range with no lens; null without rules
`limits`	Yes
`rulesFailure`	No	Why the project's rules couldn't be read

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv2.5.0Oct 26, 2026

changedOutput schema / properties / lens / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "components": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "context": {
-              "type": "boolean"
-            },
-            "delta": {
-              "type": "string"
-            },
-            "id": {
-              "type": "string"
-            },
-            "kind": {
-              "type": "string"
-            },
-            "name": {
-              "type": "string"
-            },
-            "path": {
-              "type": "string"
-            },
-            "role": {
-              "type": [
-                "string",
-                "null"
-              ]
-            },
-            "symbols": {
-              "items": {
-                "type": "string"
-              },
-              "type": "array"
-            }
-          },
-          "required": [
-            "id",
-            "name",
-            "kind",
-            "delta",
-            "context",
-            "role",
-            "path",
-            "symbols"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "flows": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "from": {
-              "type": "string"
-            },
-            "id": {
-              "type": "string"
-            },
-            "label": {
-              "type": "string"
-            },
-            "to": {
-              "type": "string"
-            }
-          },
-          "required": [
-            "id",
-            "from",
-            "to",
-            "label"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "layers": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "id": {
-              "type": "string"
-            },
-            "name": {
-              "type": "string"
-            }
-          },
-          "required": [
-            "id",
-            "name"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "quotes": {
-        "items": {
-          "type": "string"
-        },
-        "type": "array"
-      },
-      "steps": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "body": {
-              "type": [
-                "string",
-                "null"
-              ]
-            },
-            "components": {
-              "items": {
-                "type": "string"
-              },
-              "type": "array"
-            },
-            "diff": {
-              "type": "string"
-            },
-            "files": {
-              "items": {
-                "type": "string"
-              },
-              "type": "array"
-            },
-            "id": {
-              "type": "string"
-            },
-            "symbols": {
-              "items": {
-                "additionalProperties": false,
-                "properties": {
-                  "base": {
-                    "anyOf": [
-                      {
-                        "additionalProperties": false,
-                        "properties": {
-                          "end": {
-                            "maximum": 9007199254740991,
-                            "minimum": -9007199254740991,
-                            "type": "integer"
-                          },
-                          "start": {
-                            "maximum": 9007199254740991,
-                            "minimum": -9007199254740991,
-                            "type": "integer"
-                          }
-                        },
-                        "required": [
-                          "start",
-                          "end"
-                        ],
-                        "type": "object"
-                      },
-                      {
-                        "type": "null"
-                      }
-                    ]
-                  },
-                  "basePath": {
-                    "type": [
-                      "string",
-                      "null"
-                    ]
-                  },
-                  "head": {
-                    "anyOf": [
-                      {
-                        "additionalProperties": false,
-                        "properties": {
-                          "end": {
-                            "maximum": 9007199254740991,
-                            "minimum": -9007199254740991,
-                            "type": "integer"
-                          },
-                          "start": {
-                            "maximum": 9007199254740991,
-                            "minimum": -9007199254740991,
-                            "type": "integer"
-                          }
-                        },
-                        "required": [
-                          "start",
-                          "end"
-                        ],
-                        "type": "object"
-                      },
-                      {
-                        "type": "null"
-                      }
-                    ]
-                  },
-                  "name": {
-                    "type": "string"
-                  },
-                  "path": {
-                    "type": "string"
-                  }
-                },
-                "required": [
-                  "name",
-                  "path",
-                  "basePath",
-                  "base",
-                  "head"
-                ],
-                "type": "object"
-              },
-              "type": "array"
-            },
-            "title": {
-              "type": "string"
-            }
-          },
-          "required": [
-            "id",
-            "title",
-            "body",
-            "components",
-            "files",
-            "diff"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "summary": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "title": {
-        "type": "string"
-      },
-      "words": {
-        "additionalProperties": false,
-        "properties": {
-          "author": {
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "source": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "source",
-          "author"
-        ],
-        "type": "object"
-      }
-    },
-    "required": [
-      "title",
-      "words",
-      "summary",
-      "steps",
-      "components",
-      "layers",
-      "flows"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "components": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "context": {
+              "type": "boolean"
+            },
+            "delta": {
+              "type": "string"
+            },
+            "id": {
+              "type": "string"
+            },
+            "kind": {
+              "type": "string"
+            },
+            "name": {
+              "type": "string"
+            },
+            "path": {
+              "type": "string"
+            },
+            "role": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "symbols": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            }
+          },
+          "required": [
+            "id",
+            "name",
+            "kind",
+            "delta",
+            "context",
+            "role",
+            "path",
+            "symbols"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "dependencies": {
+        "additionalProperties": false,
+        "properties": {
+          "facts": {
+            "items": {
+              "additionalProperties": false,
+              "properties": {
+                "evidence": {
+                  "description": "The links the range added or removed that make it, at most 3",
+                  "items": {
+                    "type": "string"
+                  },
+                  "type": "array"
+                },
+                "from": {
+                  "additionalProperties": false,
+                  "properties": {
+                    "label": {
+                      "type": "string"
+                    },
+                    "path": {
+                      "type": [
+                        "string",
+                        "null"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "label",
+                    "path"
+                  ],
+                  "type": "object"
+                },
+                "kind": {
+                  "description": "new, gone, both (each now depends on the other) or count (a dependency that grew or shrank)",
+                  "type": "string"
+                },
+                "level": {
+                  "description": "area or layer",
+                  "type": "string"
+                },
+                "sentence": {
+                  "type": "string"
+                },
+                "steps": {
+                  "description": "The ids of the steps that hold it",
+                  "items": {
+                    "type": "string"
+                  },
+                  "type": "array"
+                },
+                "to": {
+                  "additionalProperties": false,
+                  "properties": {
+                    "label": {
+                      "type": "string"
+                    },
+                    "path": {
+                      "type": [
+                        "string",
+                        "null"
+                      ]
+                    }
+                  },
+                  "required": [
+                    "label",
+                    "path"
+                  ],
+                  "type": "object"
+                }
+              },
+              "required": [
+                "sentence",
+                "level",
+                "kind",
+                "from",
+                "to",
+                "evidence",
+                "steps"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "more": {
+            "description": "How many more facts past these",
+            "maximum": 9007199254740991,
+            "minimum": -9007199254740991,
+            "type": "integer"
+          }
+        },
+        "required": [
+          "facts",
+          "more"
+        ],
+        "type": "object"
+      },
+      "flows": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "from": {
+              "type": "string"
+            },
+            "id": {
+              "type": "string"
+            },
+            "label": {
+              "type": "string"
+            },
+            "to": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "id",
+            "from",
+            "to",
+            "label"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "layers": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "id": {
+              "type": "string"
+            },
+            "name": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "id",
+            "name"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "quotes": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "steps": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "body": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "components": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "dependencies": {
+              "description": "The sentences of the step's own facts",
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "diff": {
+              "type": "string"
+            },
+            "files": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "id": {
+              "type": "string"
+            },
+            "rules": {
+              "description": "The texts of the rules that name links it holds",
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "symbols": {
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "base": {
+                    "anyOf": [
+                      {
+                        "additionalProperties": false,
+                        "properties": {
+                          "end": {
+                            "maximum": 9007199254740991,
+                            "minimum": -9007199254740991,
+                            "type": "integer"
+                          },
+                          "start": {
+                            "maximum": 9007199254740991,
+                            "minimum": -9007199254740991,
+                            "type": "integer"
+                          }
+                        },
+                        "required": [
+                          "start",
+                          "end"
+                        ],
+                        "type": "object"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ]
+                  },
+                  "basePath": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "head": {
+                    "anyOf": [
+                      {
+                        "additionalProperties": false,
+                        "properties": {
+                          "end": {
+                            "maximum": 9007199254740991,
+                            "minimum": -9007199254740991,
+                            "type": "integer"
+                          },
+                          "start": {
+                            "maximum": 9007199254740991,
+                            "minimum": -9007199254740991,
+                            "type": "integer"
+                          }
+                        },
+                        "required": [
+                          "start",
+                          "end"
+                        ],
+                        "type": "object"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ]
+                  },
+                  "name": {
+                    "type": "string"
+                  },
+                  "path": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "name",
+                  "path",
+                  "basePath",
+                  "base",
+                  "head"
+                ],
+                "type": "object"
+              },
+              "type": "array"
+            },
+            "title": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "id",
+            "title",
+            "body",
+            "components",
+            "files",
+            "diff"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "summary": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "title": {
+        "type": "string"
+      },
+      "words": {
+        "additionalProperties": false,
+        "properties": {
+          "author": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "source": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "source",
+          "author"
+        ],
+        "type": "object"
+      }
+    },
+    "required": [
+      "title",
+      "words",
+      "summary",
+      "steps",
+      "components",
+      "layers",
+      "flows"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

addedOutput schema / properties / rules

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "file": {
+          "anyOf": [
+            {
+              "additionalProperties": false,
+              "properties": {
+                "added": {
+                  "items": {
+                    "type": "string"
+                  },
+                  "type": "array"
+                },
+                "removed": {
+                  "items": {
+                    "type": "string"
+                  },
+                  "type": "array"
+                }
+              },
+              "required": [
+                "added",
+                "removed"
+              ],
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "The rules the range adds to and removes from .shadowgit-rules; null when it leaves the file alone"
+        },
+        "matches": {
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "count": {
+                "description": "How many links the range adds that the rule names",
+                "maximum": 9007199254740991,
+                "minimum": -9007199254740991,
+                "type": "integer"
+              },
+              "links": {
+                "description": "The first links, in words; count has them all",
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              "rule": {
+                "additionalProperties": false,
+                "properties": {
+                  "because": {
+                    "description": "Its reason, as written after \"because\"",
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "form": {
+                    "description": "never, only or nothing",
+                    "type": "string"
+                  },
+                  "from": {
+                    "description": "The names on its first side; none for a nothing-rule",
+                    "items": {
+                      "type": "string"
+                    },
+                    "type": "array"
+                  },
+                  "line": {
+                    "maximum": 9007199254740991,
+                    "minimum": -9007199254740991,
+                    "type": "integer"
+                  },
+                  "text": {
+                    "description": "The rule as written, without its reason",
+                    "type": "string"
+                  },
+                  "to": {
+                    "items": {
+                      "type": "string"
+                    },
+                    "type": "array"
+                  }
+                },
+                "required": [
+                  "line",
+                  "text",
+                  "form",
+                  "from",
+                  "to",
+                  "because"
+                ],
+                "type": "object"
+              },
+              "steps": {
+                "description": "The ids of the steps that hold them",
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              }
+            },
+            "required": [
+              "rule",
+              "count",
+              "links",
+              "steps"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "rules": {
+          "description": "How many rules it was checked against",
+          "maximum": 9007199254740991,
+          "minimum": -9007199254740991,
+          "type": "integer"
+        }
+      },
+      "required": [
+        "rules",
+        "matches",
+        "file"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "The range checked against the project's rules, also for a range with no lens; null without rules"
+}

addedOutput schema / properties / rulesFailure

Added value: +{
+  "description": "Why the project's rules couldn't be read",
+  "type": "string"
+}

Changed1 schema field changedv2.2.0Oct 19, 2026

changedOutput schema / properties / lens / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "components": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "context": {
-              "type": "boolean"
-            },
-            "delta": {
-              "type": "string"
-            },
-            "id": {
-              "type": "string"
-            },
-            "kind": {
-              "type": "string"
-            },
-            "name": {
-              "type": "string"
-            },
-            "path": {
-              "type": "string"
-            },
-            "role": {
-              "type": [
-                "string",
-                "null"
-              ]
-            },
-            "symbols": {
-              "items": {
-                "type": "string"
-              },
-              "type": "array"
-            }
-          },
-          "required": [
-            "id",
-            "name",
-            "kind",
-            "delta",
-            "context",
-            "role",
-            "path",
-            "symbols"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "flows": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "from": {
-              "type": "string"
-            },
-            "id": {
-              "type": "string"
-            },
-            "label": {
-              "type": "string"
-            },
-            "to": {
-              "type": "string"
-            }
-          },
-          "required": [
-            "id",
-            "from",
-            "to",
-            "label"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "layers": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "id": {
-              "type": "string"
-            },
-            "name": {
-              "type": "string"
-            }
-          },
-          "required": [
-            "id",
-            "name"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "steps": {
-        "items": {
-          "additionalProperties": false,
-          "properties": {
-            "body": {
-              "type": [
-                "string",
-                "null"
-              ]
-            },
-            "components": {
-              "items": {
-                "type": "string"
-              },
-              "type": "array"
-            },
-            "diff": {
-              "type": "string"
-            },
-            "files": {
-              "items": {
-                "type": "string"
-              },
-              "type": "array"
-            },
-            "id": {
-              "type": "string"
-            },
-            "title": {
-              "type": "string"
-            }
-          },
-          "required": [
-            "id",
-            "title",
-            "body",
-            "components",
-            "files",
-            "diff"
-          ],
-          "type": "object"
-        },
-        "type": "array"
-      },
-      "summary": {
-        "type": [
-          "string",
-          "null"
-        ]
-      },
-      "title": {
-        "type": "string"
-      },
-      "words": {
-        "additionalProperties": false,
-        "properties": {
-          "author": {
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "source": {
-            "type": "string"
-          }
-        },
-        "required": [
-          "source",
-          "author"
-        ],
-        "type": "object"
-      }
-    },
-    "required": [
-      "title",
-      "words",
-      "summary",
-      "steps",
-      "components",
-      "layers",
-      "flows"
-    ],
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "components": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "context": {
+              "type": "boolean"
+            },
+            "delta": {
+              "type": "string"
+            },
+            "id": {
+              "type": "string"
+            },
+            "kind": {
+              "type": "string"
+            },
+            "name": {
+              "type": "string"
+            },
+            "path": {
+              "type": "string"
+            },
+            "role": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "symbols": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            }
+          },
+          "required": [
+            "id",
+            "name",
+            "kind",
+            "delta",
+            "context",
+            "role",
+            "path",
+            "symbols"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "flows": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "from": {
+              "type": "string"
+            },
+            "id": {
+              "type": "string"
+            },
+            "label": {
+              "type": "string"
+            },
+            "to": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "id",
+            "from",
+            "to",
+            "label"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "layers": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "id": {
+              "type": "string"
+            },
+            "name": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "id",
+            "name"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "quotes": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "steps": {
+        "items": {
+          "additionalProperties": false,
+          "properties": {
+            "body": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "components": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "diff": {
+              "type": "string"
+            },
+            "files": {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            "id": {
+              "type": "string"
+            },
+            "symbols": {
+              "items": {
+                "additionalProperties": false,
+                "properties": {
+                  "base": {
+                    "anyOf": [
+                      {
+                        "additionalProperties": false,
+                        "properties": {
+                          "end": {
+                            "maximum": 9007199254740991,
+                            "minimum": -9007199254740991,
+                            "type": "integer"
+                          },
+                          "start": {
+                            "maximum": 9007199254740991,
+                            "minimum": -9007199254740991,
+                            "type": "integer"
+                          }
+                        },
+                        "required": [
+                          "start",
+                          "end"
+                        ],
+                        "type": "object"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ]
+                  },
+                  "basePath": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "head": {
+                    "anyOf": [
+                      {
+                        "additionalProperties": false,
+                        "properties": {
+                          "end": {
+                            "maximum": 9007199254740991,
+                            "minimum": -9007199254740991,
+                            "type": "integer"
+                          },
+                          "start": {
+                            "maximum": 9007199254740991,
+                            "minimum": -9007199254740991,
+                            "type": "integer"
+                          }
+                        },
+                        "required": [
+                          "start",
+                          "end"
+                        ],
+                        "type": "object"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ]
+                  },
+                  "name": {
+                    "type": "string"
+                  },
+                  "path": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "name",
+                  "path",
+                  "basePath",
+                  "base",
+                  "head"
+                ],
+                "type": "object"
+              },
+              "type": "array"
+            },
+            "title": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "id",
+            "title",
+            "body",
+            "components",
+            "files",
+            "diff"
+          ],
+          "type": "object"
+        },
+        "type": "array"
+      },
+      "summary": {
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "title": {
+        "type": "string"
+      },
+      "words": {
+        "additionalProperties": false,
+        "properties": {
+          "author": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "source": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "source",
+          "author"
+        ],
+        "type": "object"
+      }
+    },
+    "required": [
+      "title",
+      "words",
+      "summary",
+      "steps",
+      "components",
+      "layers",
+      "flows"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

Addedv2.1.1Oct 15, 2026

TDQS

A3.8/5.0

Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds genuinely new behavioral context — a runtime prerequisite ("Needs the ShadowGit app running") and the edge case that it still returns something meaningful for a range with no Lens. It also previews the shape of the payload (ids plus "words so far"), which is unusual enough to warrant description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The verb and resource are front-loaded, but the body is a single semicolon-chained sentence dense with domain jargon ("cards," "flows," "words," "links") that is hard to parse on first read. Every clause carries information, but the packaging costs comprehension.

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?

An output schema exists, yet the description still sketches the return contents enough to set expectations for an idiosyncratic payload, and it flags the app-running prerequisite. For a zero-required-parameter read tool this is close to complete; only the alternative-tool routing 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 coverage is 100% and the base/head descriptions already explain the 'leave both out for the latest AI session' default, so the description's "by default the latest AI session's" largely restates structured data. It adds no format, boundary, or interaction detail for the range parameters beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: "Read ShadowGit's Lens of a range of snapshots," then enumerates the contents (steps with code, cards, flows, dependencies, rules). This distinguishes it from read-only siblings like get_map and get_code_context by content scope, though it never names those siblings to sharpen the contrast.

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?

Explicitly situates the call: "Read it at the end of a session, after the checkpoint, to word it with write_lens_words," naming the sibling that consumes the output and the timing constraint. It also notes it works "also for a range with no Lens." It stops short of stating when to prefer get_map or get_code_context instead.

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

Deploy Server