Deterministic navigation maps over code AND markdown — for AI agents. One MCP server, two lenses: tree-sitter for source (TypeScript / JavaScript / Python) and a markdown lens for docs. It answers "where is X and what's the shape of this project?" in one cheap call — so an agent spends context on thinking, not on browsing files.
Speaks the Model Context Protocol; works with any MCP client — Claude Code, Cursor, Codex, or your own agent.
An agent orienting in an unfamiliar repo otherwise burns tokens ls-ing,
grep-ing, and Reading whole files to find the one function or the right
doc. lens returns the map instead of the territory:
function_body reads one function — often ~99% less context than Reading
the file it lives in.
heading reads one doc section — the referenced heading and its
subsections, nothing else.
map returns the whole project's surface — every code file's structure
and every doc's outline — in a single call.
Every output is deterministic (real parsing, not a model summarizing), capped
with an honest truncated flag, and framed by one contract:
lens is a navigation map. Use it to locate, then Read the real source/section before judging or modifying it. A signature is not the body; an outline is not the section.
Related MCP server: code-analyze-mcp
Tool | What it does |
| Whole-tree surface in one call: per code file → structure; per doc → title + outline. Both families, one response. |
| Version, sandbox root, supported languages/extensions, tool list, every output cap, and the lens contract. |
| Install status, self-update ( |
.ts .tsx .mts .cts .js .jsx .mjs .cjs .py) + Prisma (.prisma)Tool | What it does |
| One file's imports, exports, classes (+ methods), top-level functions, with line ranges. |
| Every function incl. nested — signatures, params/types, |
| Verbatim source of ONE function — the focused read. |
| Comments + |
| Locate a definition by name — functions, classes, and now |
| The inverse: who uses a symbol — call sites, imports, type-refs — tree-sitter-precise, no grep false positives. |
.md .markdown .mdx)Tool | What it does |
| Full heading hierarchy (the TOC) with line numbers. |
| Read ONE section by heading text / slug / line number. |
| Extract inline / image / wikilink / autolink / reference links. |
| Case-insensitive full-text search across docs (heading hits ranked first). |
overview/find/map also cover Prisma schemas (schema.prisma → models, enums, fields, relations). JSON config/i18n isn't structurally mapped — lens says so honestly and points you to grep.
Call a code tool on a .md (or a doc tool on a .ts) and it fails with a
helpful pointer to the right tool — no silent confusion.
Never silent data loss — a file with syntax errors returns hasErrors +
parseErrors, still extracting what it can; unparseable files in map/find
appear with an inline error, never vanish.
Caps everywhere — every list is bounded (see info.limits) and every cap
is reported with the true total. A context-saving tool with unbounded output
is self-refuting.
Path sandbox — only files under the server's working directory are
readable; escaping symlinks are rejected. info reports the root.
Errors name the fix — {error, path, hint}, with isError set.
One line clones, installs, and writes a ready-to-paste MCP config with this install's absolute path:
git clone https://github.com/segentic-lab/lens-mcp && cd lens-mcp && ./install.shNo system packages and no native build — tree-sitter runs as WebAssembly, so it
works anywhere Node 18+ runs (Linux, macOS, Windows via WSL/Git Bash). The
installer checks Node, runs npm ci, builds (tsc → dist/), self-tests the full
suite (143 tests), and generates mcp-config.json.
Register it with your client — the generated mcp-config.json looks like:
{
"mcpServers": {
"lens": { "command": "node", "args": ["/abs/path/lens-mcp/dist/index.js"] }
}
}Claude Code: claude mcp add lens -- node /abs/path/lens-mcp/dist/index.js
(or copy mcp-config.json into a project as .mcp.json)
Cursor / Windsurf: merge mcp-config.json into ~/.cursor/mcp.json
Codex CLI: add [mcp_servers.lens] with the same command/args to ~/.codex/config.toml
lens reads files under its working directory — the project your client
launches it in. Point it at a project and call map("."). Nothing outside the
working directory is readable.
Update later, in place:
./update.sh # git pull --ff-only + reinstall + self-testPrefer to do it by hand? npm install && npm run build && npm test, then
run node dist/index.js.
lens-mcp supersedes the earlier split servers codelens-mcp (code) and
docslens-mcp (docs) — same engines, one server, one pipeline. Sibling of
periscope-mcp (web-app QA);
built to the same standard: honest errors, caps + truncated flags everywhere,
docs == behavior, tests before release.
Built by Segentic Lab. AGPL-3.0.
All comments in a source file with 1-based line ranges, kind (line | block | doc — doc covers /** */ and Python docstrings), and marker detection. Returns JSON {path, language, hasErrors, comments[{line, endLine, text, kind, marker}]}. marker is TODO|FIXME|FIX|BUG|HACK|NOTE|XXX when the comment contains that UPPERCASE word (case-sensitive, avoids prose false-positives), else null. markersOnly:true returns only marked comments (the debt list). Text clips at 600 chars; list caps at 500. Languages: TS/TSX/JS/JSX/Python. lens is a navigation map over code and docs: use it to LOCATE things, then Read the actual source/section before judging or modifying it. A signature is not the body; an outline is not the section.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | File path. Relative paths resolve against the server's working directory; absolute paths are allowed only inside it (outside is rejected — call info to see the root). Code: .ts .tsx .mts .cts .js .jsx .mjs .cjs .py; docs: .md .markdown .mdx. A single path, or an array of up to 20 paths (array returns {results, summary}). | |
| markersOnly | No | Return only comments carrying a TODO/FIXME/FIX/BUG/HACK/NOTE/XXX marker (default false). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: return format, marker detection case-sensitivity, text clipping at 600 chars, list cap at 500, supported languages, path resolution rules, and behavior for path arrays. No annotations exist, so description carries full burden and does so thoroughly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is information-dense but front-loaded with purpose. Could be slightly more structured with bullet points, but it efficiently covers essential details without unnecessary repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description fully explains return format, limits, and behaviors. Also includes advisory context about lens usage. Covers all relevant aspects for correct tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already provides detailed parameter descriptions (100% coverage). Description adds extra context: marker detection specifics, text limits, and language support, enhancing understanding beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool returns all comments in source files with line ranges, kind, and marker detection. Distinguishes from siblings like functions, headings, etc., which focus on different code structures.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides general advice about using lens for navigation but does not explicitly state when to use comments versus alternative tools. Usage context is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Locate a DEFINITION by name across a directory — "where is X defined?" without grepping. Finds functions, methods, classes, AND non-callable top-level symbols: const/let/var bindings, type aliases, interfaces, and enums (a codebase's source-of-truth often lives in export const …). For text inside markdown docs use search; for who USES a symbol use references. Returns JSON {query, path, matches[{file, name, kind, line, signature, parent}], filesScanned, totalSupportedFiles, truncated, skipped?}. kind is function|method|arrow|getter|setter|class|const|let|var|type|interface|enum|variable. Matching is case-insensitive substring by default; exact:true for exact-name. Unsearchable files are listed in skipped with the reason. Caps: scans up to 300 files, returns up to 100 matches (truncated:true = more exist). Definitions only, not call sites. Languages: TS/TSX/JS/JSX/Python. lens is a navigation map over code and docs: use it to LOCATE things, then Read the actual source/section before judging or modifying it. A signature is not the body; an outline is not the section.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Symbol name (function/method/class/const/type/enum/…). Substring match unless exact:true. | |
| path | No | Directory (or single file) to search. Default "." (whole workspace). | |
| exact | No | Exact, case-sensitive match instead of case-insensitive substring (default false). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full behavioral disclosure burden. It thoroughly details return format (JSON with specific fields), matching behavior (case-insensitive substring, exact option), limits (300 files, 100 matches, truncated flag), that it only finds definitions (not call sites), languages supported, and handling of unsearchable files. This is exceptionally transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy but every sentence is informative. It is front-loaded with the core purpose and then systematically details behavior, parameters, output, and limitations. While slightly verbose, it is efficiently structured for clarity and completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (3 parameters, no output schema), the description is fully complete. It explains the return value structure, field meanings, kind enum, limits, and edge cases (skipped files, truncation). No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds significant meaning: explains the exact parameter behavior (case-sensitive, exact match), default path, and the output structure including the 'kind' enum. It also clarifies that matching is substring by default. This adds value beyond the schema, justifying a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: locating definitions by name. It explicitly lists what it finds (functions, methods, classes, non-callable symbols like const/let/var/type/interface/enum) and distinguishes from siblings (search for text in docs, references for usage). This is a specific verb+resource with clear differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: 'where is X defined?' and 'Locate a DEFINITION by name'. It also gives explicit alternatives: 'For text inside markdown docs use search; for who USES a symbol use references.' This clearly defines context and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verbatim source of ONE function — the focused read. Instead of Reading a whole file, get exactly that function's source (signature + decorators + body). Returns JSON {path, name, parent, kind, signature, line, endLine, async, exported, hasErrors, body}. name matches the bare or dotted-qualified form from functions/find ('Widget.render'); if ambiguous the call FAILS listing candidates with lines — pass the qualified name or line, it never guesses. body is real source, capped at 20000 chars (truncated.bodyChars = true length — Read line..endLine for the rest). The body IS the territory for this one function (reason about its internals) — but re-Read before editing. Languages: TS/TSX/JS/JSX/Python.
| Name | Required | Description | Default |
|---|---|---|---|
| line | No | Disambiguator: the definition line (from functions/find) when a name has several definitions. | |
| name | Yes | Function/method name, bare ('render') or dotted ('Widget.render') as reported by functions/find. Default exports are 'default'. | |
| path | Yes | File path. Relative paths resolve against the server's working directory; absolute paths are allowed only inside it (outside is rejected — call info to see the root). Code: .ts .tsx .mts .cts .js .jsx .mjs .cjs .py; docs: .md .markdown .mdx |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses return format, failure mode on ambiguity, truncation at 20000 chars with truncated.bodyChars indicator, and supported languages. Does not mention auth or rate limits, but for a read-only tool this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is comprehensive yet efficient. Each sentence adds value. Front-loaded with purpose. Could be slightly more concise but remains readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description details output JSON fields. Covers failure modes, truncation, language support, and usage tips. For a focused read tool, it is complete and anticipates common questions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% but descriptions are minimal. Description adds meaning: name can be bare or dotted-qualified, default exports are 'default', path resolution rules, and line as disambiguator. Adds value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'Verbatim source of ONE function — the focused read.' clearly distinguishing from reading entire files. Contrasts with sibling tools like 'functions' and 'find' by emphasizing focused retrieval. Verb+resource+scope 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using this tool instead of reading a whole file. Mentions ambiguity handling and provides guidance on qualified names or lines. Does not explicitly name alternatives, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every addressable function in a source file — nested functions, class methods, getters/setters, class-field arrows, namespace members, object-literal methods, default-export functions — with reconstructed signatures. NOT listed: anonymous callbacks, TS overload signatures (only implementations), Python lambdas. Returns JSON {path, language, hasErrors, functions[{name, signature, params[{name,type}], returnType, line, endLine, async, exported, kind, parent}]}. kind is function|method|arrow|getter|setter; parent is the enclosing scope, dotted for nesting ('Widget.render'), null at top level; default exports are named 'default'. Caps at 500 (truncated.functions = true total). Use to pick a line range to Read or read one body with function_body. lens is a navigation map over code and docs: use it to LOCATE things, then Read the actual source/section before judging or modifying it. A signature is not the body; an outline is not the section.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | File path. Relative paths resolve against the server's working directory; absolute paths are allowed only inside it (outside is rejected — call info to see the root). Code: .ts .tsx .mts .cts .js .jsx .mjs .cjs .py; docs: .md .markdown .mdx. A single path, or an array of up to 20 paths (array returns {results, summary}). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description covers return format, caps at 500, truncation flag, and nature of output. Discloses that signatures are not bodies but omits any side effects (likely none).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Informative but somewhat verbose; front-loaded with main purpose. Could be slightly more concise without losing detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive coverage of what's included/excluded, return format, usage guidance, and limitations. No output schema but return format is fully described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema already describes path parameter fully; description adds context on relative/absolute resolution, allowed file types, and multiple path support.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists every addressable function in a source file with reconstructed signatures, specifying inclusions and exclusions. It distinguishes itself from siblings like function_body and outline.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use (to locate code before reading) and when not to use (it's not the body). Mentions alternatives like Read and function_body.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read ONE section of a markdown file instead of the whole file: the referenced heading plus everything under it (subsections included), stopping at the next heading of the same or higher level. ref accepts the exact heading text, its slug ("advanced-usage"), or ANY 1-based line number — a heading line from outline() or a content line from a search hit (resolves to its enclosing section, a note says so). Returns {file, heading, level, startLine, endLine, content}; on multiple matches a note says which was returned and how to pick another. The most token-frugal way to read docs — prefer it over reading whole files.
| Name | Required | Description | Default |
|---|---|---|---|
| ref | Yes | Heading text, slug, or line number identifying the section — from outline() or a search match. | |
| file | Yes | File path. Relative paths resolve against the server's working directory; absolute paths are allowed only inside it (outside is rejected — call info to see the root). Code: .ts .tsx .mts .cts .js .jsx .mjs .cjs .py; docs: .md .markdown .mdx |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description fully discloses behavior: reads only one section, resolves line numbers to enclosing section, returns structured data, notes about multiple matches, and token efficiency. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence adds value. Front-loaded with main purpose. No fluff. Efficiently conveys complex behavior in a compact form.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, return structure described. Parameters fully covered. With 13 sibling tools, this description stands out as complete and self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage 100% but description adds extra meaning: explains ref can be heading text, slug, or line number, and how line numbers resolve. File path resolution constraints also detailed. Goes beyond schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it reads one section of a markdown file, including subsections, stopping at next heading of same/higher level. Differentiates from reading whole files and references sibling tools like outline() and search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'prefer it over reading whole files', explains ref accepts heading text, slug, or line number, and describes behavior on multiple matches with a note on how to pick another. Provides clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Server self-description: version, working directory (the path sandbox root — every path you pass must resolve inside it), supported code languages and doc extensions, the tool list, and every output cap. Returns JSON {name, version, workingDirectory, code:{languages}, docs:{extensions}, tools[], limits, contract}. Read-only, no parameters. Call this first if a path is rejected or to learn what the server can see.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully covers behavioral traits: declares read-only nature, no parameters, and describes the return JSON structure in detail, leaving no ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and uses compact but complete sentences. Every sentence adds value, no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even without an output schema, the description explains the return format completely. It covers all necessary aspects for a self-description tool, making the agent well-informed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the description correctly adds no parameter information beyond the schema, which is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool provides server self-description including version, working directory, supported languages, doc extensions, tool list, and output caps. It distinguishes from sibling tools (comments, find, etc.) by being a meta-tool about the server itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises 'Call this first if a path is rejected or to learn what the server can see,' providing clear usage context. No explicit alternatives are mentioned, but the meta-tool nature makes this less critical.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Install status, self-update, and the current agent guide — lens's self-maintenance tool. action='status' (read-only): running vs on-disk version, git commit, install type, install directory, Node version, and whether an update is available. action='agents_md' (read-only): returns the CURRENT AGENTS.md so you can refresh a stale pasted copy of your operating guide. action='update': dry-run by default (commits behind + incoming changes); apply=true runs update.sh (git pull + npm ci + build + self-test) — new code loads only after the MCP server restarts, and the response says so. force=true stashes local edits. Managed installs (no .git) refuse with guidance. Note: this operates on the lens INSTALL directory, not your project (the code tools' sandbox). Returns JSON.
| Name | Required | Description | Default |
|---|---|---|---|
| apply | No | For action='update': actually run the update instead of the dry-run check (default false). | |
| force | No | For action='update' with apply=true: auto-stash local modifications first (recoverable via `git stash pop`). | |
| action | No | status = version/commit/update-check (default); update = check or apply an update; agents_md = fetch the current agent guide |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full burden. It thoroughly discloses behavioral traits: dry-run default for update, apply and force effects, the need for server restart after update, and handling of managed installs. It also states the return format is JSON.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but well-structured with bullet points for actions, making it scannable. It front-loads the main purpose and then details each action. A slightly more concise style could improve, but it remains clear and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description could be more specific about the return format (e.g., fields in the JSON). However, the behaviors for each action are well-documented, and the context of 'lens install directory' is clear. The tool's complexity is moderate, so the description is mostly adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, baseline is 3. The description adds value by explaining the purpose of each action (status, update, agents_md) and clarifying parameters like apply and force (e.g., dry-run, stash). This goes beyond the schema's basic descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the tool's role: self-maintenance for the lens system, covering install status, self-update, and agent guide retrieval. It distinguishes itself from sibling tools (all code-analysis focused) by being the only meta-tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Each action is described with clear context (e.g., status for version info, agents_md for current guide, update for checking/applying). It also notes that managed installs refuse the update, providing implicit when-not-to-use guidance. However, it doesn't explicitly state alternatives or exclude other use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract every link from one markdown file: inline text, images (badge constructs yield both image and outer link), [[wikilinks]], , and reference-style [text][id] resolved via their [id]: url definitions. Skips example links inside fenced code blocks. Returns {path, totalLinks, truncated, links:[{type: markdown|image|wikilink|autolink|reference, text, target, line}]} in document order, capped at 200. Map cross-references or collect URLs without reading the file.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | File path. Relative paths resolve against the server's working directory; absolute paths are allowed only inside it (outside is rejected — call info to see the root). Code: .ts .tsx .mts .cts .js .jsx .mjs .cjs .py; docs: .md .markdown .mdx |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It details what is skipped (example links in code blocks), the return structure (path, totalLinks, truncated, links array with type, text, target, line), and limits (capped at 200, document order). It does not cover error handling or permissions, but is thorough for a read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured paragraph. The first sentence states the main purpose, followed by details on link types, edge cases (badge constructs), and return format. Every sentence adds value, though it could be slightly more concise by grouping similar info.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of link types and no output schema, the description explains the return object structure clearly and lists edge cases (badge constructs, code block skipping). It does not cover all possible errors (e.g., file not found) but is complete enough for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema describes the 'path' parameter briefly. The description adds critical semantics: path resolution rules (relative vs absolute), allowed file extensions (code and docs), and a note to use 'info' to see the root. This goes beyond the schema to clarify usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool extracts every link from a markdown file, enumerating link types (inline, image, wikilinks, autolinks, reference-style). It is specific about the resource and action, but does not explicitly differentiate from sibling tools like 'references' or 'search', which could also involve link extraction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some usage context, such as 'Map cross-references or collect URLs without reading the file,' implying when to use it. However, it does not explicitly state when not to use it or compare to alternatives like 'find' or 'search', leaving the agent to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Whole-project surface in ONE call — the orientation tool over a mixed tree of code AND docs. Walks a directory recursively (skipping node_modules, .git, dist, build, venv, pycache, target, vendor, hidden dirs) and returns JSON {path, code:{files[{path, language, totalLines, classes[], functions[], hasErrors?, error?}], totalSupportedFiles, filesParsed, truncated}, docs:{docs[{path, title, headingCount, outlinePreview[], bytes}], totalDocs, truncated}, summary:{codeFiles, docFiles}}. Code files (.ts .tsx .mts .cts .js .jsx .mjs .cjs .py) report structure; doc files (.md .markdown .mdx) report title + shallow outline. Caps: 200 code files and 200 docs per call (truncated flags carry the true totals — map a subtree to go deeper). Unparseable files appear with an inline error, never vanish. Use FIRST to decide which files matter, then the drill-down tools (overview/functions for code, outline/heading for docs). lens is a navigation map over code and docs: use it to LOCATE things, then Read the actual source/section before judging or modifying it. A signature is not the body; an outline is not the section.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Directory to map, relative to the working directory (or absolute inside it). Use "." for the whole workspace. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses skipping directories (node_modules, .git, etc.), caps (200 code files and 200 docs), truncated flags, and error handling for unparseable files. No annotations provided, so description carries full burden and does so comprehensively.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is dense but well-structured, starting with purpose, then JSON structure, then caps, then usage. Every sentence adds value. Could be slightly more concise but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so description must explain return values. It details the JSON shape, fields for code and docs, caps, truncated flags, and error handling. It also explains usage context (use maps first). Complete for a complex tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has one parameter 'path' with basic description. Description adds significant context: use '.' for whole workspace, relative/absolute inside working directory, and implies recursive behavior. Schema coverage is 100%, so baseline is 3, but description adds extra value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it's an orientation tool that maps a directory recursively, returning JSON with code and docs structure. It distinguishes itself from sibling tools (e.g., overview, functions, outline) by positioning itself as the first step to locate files, then using drill-down tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use FIRST to decide which files matter, then the drill-down tools (overview/functions for code, outline/heading for docs)' and advises to use it to locate things and then read actual source before judging or modifying. Provides clear when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full heading hierarchy of one markdown file with 1-based line numbers — its table of contents. Recognizes ATX (#…) and setext (===/---) headings; skips headings inside fenced code blocks and YAML frontmatter; handles CRLF. Returns {path, totalHeadings, truncated, headings:[{depth, text, line}], totalLines}; capped at 500. For source code use overview instead. Pick a section here, then read only it with heading(). lens is a navigation map over code and docs: use it to LOCATE things, then Read the actual source/section before judging or modifying it. A signature is not the body; an outline is not the section.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | File path. Relative paths resolve against the server's working directory; absolute paths are allowed only inside it (outside is rejected — call info to see the root). Code: .ts .tsx .mts .cts .js .jsx .mjs .cjs .py; docs: .md .markdown .mdx |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and delivers: it details the types of headings recognized (ATX, setext), what is skipped (fenced blocks, YAML frontmatter), CRLF handling, return fields, and the 500-heading cap. It also clarifies what the tool does not do ('A signature is not the body...').
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is information-dense but well-structured: purpose first, then details, then usage guidance. It is slightly verbose but every sentence adds value. Could be trimmed slightly, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of markdown heading extraction (ATX, setext, fenced code blocks, YAML frontmatter, CRLF, truncation), the description covers all relevant aspects. Despite no output schema, it lists return fields. It also provides crucial context for the tool's role in the wider set of tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of the parameter, but the description adds significant meaning: how relative and absolute paths resolve, allowed file extensions, and the rejection of paths outside the root. This goes well beyond the schema's minimal type/required info.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the full heading hierarchy of a markdown file with line numbers. It distinguishes itself from siblings like 'overview' (for source code) and 'heading' (to read a section), making the purpose 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use this tool vs alternatives: 'For source code use overview instead' and 'Pick a section here, then read only it with heading().' It also provides context for the broader 'lens' navigation approach.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Structural map of a source file: imports, exports, classes (with method names, incl. class-field arrow methods), and top-level functions — each with 1-based line/endLine to jump straight to a Read. Returns JSON {path, language, totalLines, hasErrors, imports[], exports[], classes[{name,line,endLine,methods[]}], functions[{name,line,endLine,exported}]}. hasErrors:true means syntax errors and items may be missing (parseErrors lists offending ranges). Nested functions are in the functions tool. Lists cap at 500 (truncated. holds the true total). Languages: TS/TSX/JS/JSX/Python (Python exports from all). For markdown files use outline instead. Use FIRST to orient in an unfamiliar source file. lens is a navigation map over code and docs: use it to LOCATE things, then Read the actual source/section before judging or modifying it. A signature is not the body; an outline is not the section.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | File path. Relative paths resolve against the server's working directory; absolute paths are allowed only inside it (outside is rejected — call info to see the root). Code: .ts .tsx .mts .cts .js .jsx .mjs .cjs .py; docs: .md .markdown .mdx. A single path, or an array of up to 20 paths (array returns {results, summary}). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully explains behavior: it returns a JSON with specific structure, mentions error handling ('hasErrors:true means syntax errors'), caps at 500 items with truncation indicators, lists supported languages, and warns that an outline is not the full section. This is highly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is fairly long but every sentence adds value—it covers output structure, limitations, language support, and usage advice. It could be slightly more concise, but it is well-organized and front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (structural map of a file) and lack of output schema, the description is remarkably complete. It explains output format, error indicators, list caps, supported languages, and even references sibling tools for nested functions and markdown. No additional context seems missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides basic description for 'path', but the description adds significant meaning: relative vs absolute path resolution, allowed code and doc file extensions, and the ability to pass an array of paths (up to 20) returning a results summary. This goes well beyond the schema's definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool provides a structural map of a source file, listing imports, exports, classes, and top-level functions with line numbers. It distinguishes itself from sibling tools like 'outline' (markdown) and 'functions' (nested functions), making its purpose very specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use the tool ('Use FIRST to orient in an unfamiliar source file'), when not to use it ('For markdown files use outline instead'), and directs to 'functions' for nested functions. It also advises to 'Read the actual source' after locating items via this tool, providing clear guidance on usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find who USES a symbol across a directory — the inverse of find. "Who calls X", "what imports it", "where is it used as a type". The reference workflow lens otherwise sends you to grep for, but tree-sitter-backed so a same-named string or comment is never a false positive. Returns JSON {symbol, path, references[{file, line, kind, context}], byKind, filesScanned, totalSupportedFiles, truncated, skipped?}. kind is call | instantiation | import | type-ref | reference | definition (the definition site is included, labelled). context is the source line. Matching is EXACT (references need precision). Caps: scans up to 400 files, returns up to 300 references (truncated:true = more exist — narrow the path). Languages: TS/TSX/JS/JSX/Python. lens is a navigation map over code and docs: use it to LOCATE things, then Read the actual source/section before judging or modifying it. A signature is not the body; an outline is not the section.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Exact symbol name to find references for (a function/class/const/type from find or overview). | |
| path | No | Directory (or single file) to search. Default "." (whole workspace). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: exact matching, tree-sitter backing, caps (400 files, 300 results), truncation flag, languages supported, and return format. It also warns about false positives, making it highly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is informative but verbose, with several sentences that could be merged or removed (e.g., 'A signature is not the body...'). It front-loads the main purpose but could be more compact without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description thoroughly explains the return JSON structure, including fields, kinds, and context. It covers constraints, languages, and truncation behavior, leaving no significant gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds minimal extra value: it mentions the symbol name should be from 'find or overview' and that path defaults to '.'. This is helpful context but not beyond what the schema implies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds who uses a symbol across a directory, and contrasts it with sibling tools like 'find' and 'grep'. It provides concrete examples like 'Who calls X', 'what imports it', making its purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use this tool (to locate references with precision, avoiding grep false positives) and gives workflow guidance ('use it to LOCATE things, then Read the actual source'). It could more explicitly state when not to use it, but the inverse relation to 'find' is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Case-insensitive full-text substring search across MARKDOWN docs (for code symbol definitions use find). Returns matches {path, line, snippet (≤200 chars), inHeading}, heading matches ranked first, capped at max_results (default 50, max 200) with totalMatches and truncated:true when capped. Empty/whitespace queries are rejected (they would match everything). Locate the right doc, then outline/heading to read it.
| Name | Required | Description | Default |
|---|---|---|---|
| dir | No | Directory to search, relative to the working directory (default: the working directory). | |
| query | Yes | Search term — case-insensitive substring, matched per line. Must be non-empty. | |
| recursive | No | Recurse into subdirectories (default: true). | |
| max_results | No | Max matches (default 50, clamped to 1–200). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description fully discloses behavior: case-insensitive substring matching, ranking (heading matches first), result structure (path, line, snippet ≤200 chars, inHeading), capping with totalMatches and truncated flag, and rejection of empty/whitespace queries. This provides comprehensive transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (three sentences) and front-loaded: first sentence defines purpose and contrast, second details behavior, third gives usage hint. Every sentence adds unique value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 parameters, 1 required, no output schema), the description covers purpose, usage, return format, constraints, and alternatives. It provides sufficient completeness for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds meaningful context beyond the schema: it explains the default (50) and maximum (200) for max_results, and emphasizes that query must be non-empty. This enriches the parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a case-insensitive full-text substring search across MARKDOWN docs, and explicitly distinguishes itself from the sibling 'find' tool for code symbol definitions. The verb ('search') and resource ('MARKDOWN docs') are 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance: contrast with 'find' for code symbols, and advises to 'locate the right doc, then outline/heading to read it.' It also warns that empty/whitespace queries are rejected, preventing misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.2commentsfindfunction_bodyfunctionsheadinginfolens_systemlinksmapoutlineoverviewreferencessearchScored across 13 tools
Each tool targets a distinct aspect of navigation: find for symbol locations, references for usage, functions for file structure, function_body for verbatim source, comments for annotations, and separate doc tools. Descriptions clarify boundaries (e.g., find vs search vs references), leaving no ambiguity.
Tool names are lowercase, mostly single words, but mix verbs (find, search, map) and nouns (comments, overview, links). Underscore appears only in 'function_body' and 'lens_system'. Minor inconsistency but still predictable.
13 tools is well-scoped for a navigation server covering both code and documentation. Each tool serves a clear purpose, and the count feels neither sparse nor overwhelming.
The surface covers locating definitions (find), usage (references), file structure (overview, functions), code reading (function_body, comments), doc navigation (outline, heading, links), full project map (map), plus self-info and maintenance (info, lens_system). No obvious gaps for its stated mission of locating and reading.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Give your AI agent a persistent map of your project's structure, dependencies, and bugs.
Deterministic context layer for your codebase: change impact, blast radius, answers with receipts.
Project memory, semantic code search, and grounded agent context.
Shared memory for coding agents. Stop re-explaining your codebase every session.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/segentic-lab/lens-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
