lens-mcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.1.2
Disambiguation5/5
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.
Naming Consistency4/5
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.
Tool Count5/5
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.
Completeness5/5
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.
Average 4.6/5 across 13 of 13 tools scored. Lowest: 3.8/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 5 commits in the last 12 weeks
- Last stable release on July 6, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under AGPL 3.0.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior4/5
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.
Conciseness4/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose4/5
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.
Usage Guidelines3/5
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.
Behavior4/5
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.
Conciseness4/5
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.
Completeness4/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior5/5
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.
Conciseness3/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior5/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior5/5
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.
Conciseness4/5
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.
Completeness3/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters5/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior5/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. 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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters5/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness4/5
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.
Completeness5/5
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.
Parameters5/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines5/5
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.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![lens-mcp MCP server](https://glama.ai/mcp/servers/segentic-lab/lens-mcp/badges/card.svg)](https://glama.ai/mcp/servers/segentic-lab/lens-mcp)

Score Badge

Copy to your README.md:

[![lens-mcp MCP server](https://glama.ai/mcp/servers/segentic-lab/lens-mcp/badges/score.svg)](https://glama.ai/mcp/servers/segentic-lab/lens-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

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