docsgrep is a developer tool MCP server providing 26 tools for documentation search, code quality auditing, security scanning, bug detection, and architectural analysis on local and remote codebases.
Discovery & Setup
Initialize workspaces, detect technology stacks, identify coding conventions, discover documentation files, and clone remote repositories (with auth support)
Content & Search
Read files, perform regex and semantic/natural-language searches across docs, summarize documentation, and find related content by topic
Auditing & Quality
Run enterprise-grade code quality audits (scoring, code smells, recommendations), security scans (OWASP Top 10, secrets/credentials, PII, dependency vulnerabilities), and bug detection (race conditions, memory leaks, logic flaws, performance issues)
Use interactive prompts (lint_interactive, security_interactive) to guide linting and scanning workflows
Architecture
Detect architectural patterns (MVC, Repository, etc.) and identify refactoring candidates
Documentation Maintenance & Sync
Check for stale docs, measure docblock coverage (JS, TS, Python, Go, Rust, PHP, etc.), auto-generate/update doc stubs, verify documented methods match actual code, compare doc claims against implementation, and prioritize updates based on git history
Context & Help
Surface relevant documentation based on the file currently being worked on, access comprehensive help with examples, and clear cached repositories
It is accessible via CLI or as an MCP server for AI-assisted workflows, and supports custom plugins to extend functionality.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@docsgrep search docs for 'rate limiting' with context"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
docsgrep is a developer tool for documentation search, code quality auditing, security scanning, and bug detection. Run it from the command line during development, or integrate it as an MCP server for AI-assisted coding workflows.
Related MCP server: Axon.MCP.Server
Documentation Intelligence -- Semantic search, summarization, and topic-based discovery across your docs.
Code Quality Auditing -- Enterprise-grade audits with code smell detection, convention analysis, and quality scoring.
Security Scanning -- OWASP Top 10 coverage, secret/credential detection, PII scanning, and dependency vulnerability auditing.
Bug Detection -- Runtime error detection, race condition analysis, memory leak identification, and performance issue discovery.
Architectural Analysis -- Pattern detection (MVC, Repository, etc.), dependency mapping, and refactoring candidate identification.
Documentation Integrity -- Staleness detection, coverage measurement, doc-vs-code delta analysis, and automated sync.
Remote Repository Support -- Clone and analyze remote repositories with smart caching and authentication (HTTPS, SSH).
Plugin System -- Extend docsgrep with community or custom plugins via docsgrep-plugin-* packages.
# Run without installing
npx docsgrep run analyze_code
# Or install globally
npm install -g docsgrep
docsgrep run audit_security --format jsonRun show_help for a full list of available tools:
npx docsgrep run show_helpnpm install -g docsgrepnpm install --save-dev docsgrepnpx docsgrep run <tool_name> [--param value]Node.js >= 18
pnpm (recommended), npm, or yarn
docsgrep run <tool_name> [--param value ...] [--format text|json]Flag | Description |
| Plain text output (default) |
| Pretty-printed JSON output |
| Target directory (defaults to cwd) |
| Search pattern for |
| Number of results for |
| Staleness threshold in days |
Comma-separated values | Automatically parsed as arrays (e.g., |
# Code quality audit on the current directory
npx docsgrep run analyze_code
# Security scan with JSON output
npx docsgrep run audit_security --format json
# Regex search in documentation
npx docsgrep run search_docs --pattern "authentication" --contextLines 2
# Detect bugs and potential runtime errors
npx docsgrep run catch_bugs --dirPath ./src
# Semantic search for documentation
npx docsgrep run semantic_search --query "how to handle errors" --topK 5
# Find docs related to a topic
npx docsgrep run find_related --topic "database migration"
# Measure documentation coverage
npx docsgrep run measure_coverage --publicOnly true
# Detect project technology stack
npx docsgrep run detect_stack
# Check for stale documentation
npx docsgrep run check_stale --maxAgeDays 30
# Clone and analyze a remote repo
npx docsgrep run clone_repo --repoUrl https://github.com/user/repoWhen docsgrep is installed locally, these shortcuts are available:
Script | Runs |
|
|
|
|
|
|
|
|
|
|
docsgrep functions as a Model Context Protocol (MCP) server, giving AI agents and MCP-compatible IDEs access to all 25 tools.
{
"mcpServers": {
"docsgrep": {
"command": "npx",
"args": ["-y", "docsgrep"]
}
}
}Already configured via opencode.json in this repository:
{
"mcp": {
"docsgrep": {
"type": "local",
"command": ["npx", "tsx", "src/index"]
}
}
}{
"mcpServers": {
"docsgrep": {
"command": "npx",
"args": ["tsx", "src/index"]
}
}
}On startup, docsgrep initializes the tool registry and discovers any installed plugins.
When an MCP client connects, it lists all available tools (core + plugin tools).
When a tool is called, docsgrep validates inputs, executes the handler, and returns a structured McpToolResponse.
The server communicates over stdio transport.
docsgrep ships with 25 tools organized into five categories.
Tool | Description | Key Arguments |
| Initialize a docsgrep workspace (.docsgrep/) and update .gitignore |
|
| Identify project technology stack from package manager files |
|
| Detect coding conventions and implicit patterns from codebase samples |
|
| Discover README files and documentation folders |
|
| Clone a remote git repository with caching and auth support |
|
Tool | Description | Key Arguments |
| Read a documentation file with binary detection |
|
| Regex search with relevance ranking and context lines |
|
| Natural language search across documentation |
|
| Automatic summarization of a documentation file |
|
Tool | Description | Key Arguments |
| Full code quality audit with scoring and recommendations |
|
| OWASP Top 10, secret scanning, PII analysis, dependency audit |
|
| Detect runtime errors, race conditions, memory leaks, logic flaws |
|
| Interactive prompt showing detected stack and linting options |
|
| Interactive prompt showing scan options before execution |
|
Tool | Description | Key Arguments |
| Identify documentation not updated in N days or out of sync with code |
|
| Measure docblock coverage across source code (language-agnostic) |
|
| Generate or update documentation stubs from code changes |
|
| Verify documented methods/params match actual implementation |
|
| Compare documentation claims against code reality |
|
| Prioritize documentation updates from git diff history |
|
Tool | Description | Key Arguments |
| Proactively provide relevant docs based on current file context |
|
| In-app help for all tools with examples and pro tips |
|
| Clean cached repositories older than N days |
|
docsgrep supports plugins that add custom tools to the CLI and MCP server.
Plugins are discovered automatically from node_modules:
# Install a plugin
npm install docsgrep-plugin-laravel
# It's now available as a tool
npx docsgrep run laravel_check_relationsdocsgrep-plugin-<name> -- auto-discovered
@docsgrep/plugin-<name> -- auto-discovered
Any path/package listed in docsgrep.config.json -- explicit
A plugin is an ESM module that default-exports a DocsgrepPlugin object:
import type { DocsgrepPlugin } from "docsgrep";
const plugin: DocsgrepPlugin = {
name: "my-plugin",
version: "1.0.0",
tools: {
definitions: [
{
name: "my_custom_tool",
description: "Does something custom",
inputSchema: {
type: "object",
properties: {
dirPath: { type: "string", description: "Target directory" },
},
required: ["dirPath"],
},
},
],
handlers: {
my_custom_tool: async (args) => {
return {
content: [{ type: "text", text: JSON.stringify({ result: "done" }) }],
};
},
},
},
onLoad: async () => {
console.log("My plugin loaded!");
},
};
export default plugin;See docs/PLUGIN_GUIDE.md for the full guide.
pnpm >= 9.0
Node.js >= 18
git clone https://github.com/reasvyn/docsgrep.git
cd docsgrep
pnpm installCommand | Description |
| Compile TypeScript to |
| Run from source via |
| Run all Vitest tests |
| Run tests with V8 coverage report |
| Run |
| Run |
| Run |
| Run |
| Run |
Note: The
lint,audit,bugs,docs:check, anddocs:stalescripts run docsgrep on its own source code. They requirepnpm buildfirst.
pnpm vitest run tests/unit/tools/documentation.test.tsdocsgrep/
├── src/
│ ├── index.ts # Entry point (MCP server + plugin discovery)
│ ├── cli.ts # CLI argument parsing and display
│ ├── core-tools.ts # Class-based tools (AnalyzeCodeTool, etc.)
│ ├── tools/ # Tool handlers (one module per logical group)
│ │ ├── base.ts # BaseTool<T> abstract class
│ │ ├── registry.ts # Tool registry (name → handler mapping)
│ │ ├── doc-find.ts # find_docs
│ │ ├── doc-search.ts # search_docs, semantic_search, find_related
│ │ ├── doc-inspect.ts # read_file, summarize_doc, check_stale, get_context
│ │ ├── doc-coverage.ts # measure_coverage
│ │ ├── doc-verify.ts # verify_docs, check_delta
│ │ ├── doc-sync.ts # sync_documentation, check_artefacts
│ │ ├── help.ts # show_help
│ │ ├── repo-analysis.ts # detect_stack, check_style
│ │ ├── repo.ts # clone_repo
│ │ ├── workspace.ts # init_workspace, clear_cache
│ │ ├── archetypes.ts # detect_patterns
│ │ └── audit-ask.ts # lint_interactive, security_interactive
│ ├── utils/ # Shared utilities
│ │ ├── file.ts # FileScanner, getIgnorePatterns
│ │ ├── git.ts # Git operations + repo cache
│ │ ├── validation.ts # Input validation
│ │ ├── semaphore.ts # Concurrency limiter
│ │ ├── logger.ts # Dual output: stderr + file logs
│ │ ├── workspace.ts # .docsgrep/ path resolution
│ │ ├── cache.ts # TTL-based file cache
│ │ ├── plugin-manager.ts
│ │ └── app-info.ts # AppInfo (version, name from package.json)
│ ├── types/ # TypeScript interfaces
│ │ ├── tools.ts # McpToolResponse + all tool arg interfaces
│ │ └── plugins.ts # DocsgrepPlugin interface
│ └── config/ # JSON configuration
│ ├── tools.json # MCP tool definitions (JSON Schema)
│ ├── patterns.json
│ └── *.json # Per-language configs (js, py, go, rs, etc.)
├── tests/
│ ├── unit/ # Unit tests (vi.mock for IO)
│ └── integration/ # E2E tests (StdioClientTransport)
├── docs/
│ ├── overview.md # Project overview
│ ├── architecture.md # System design
│ ├── requirements.md # Runtime prerequisites
│ ├── conventions.md # Coding standards
│ ├── index.md # Documentation index
│ ├── README.md # Tool documentation index
│ ├── PLUGIN_GUIDE.md # Plugin authoring guide
│ └── tools/ # Per-tool documentation (*.md)
├── plugins/ # Local plugin directory
├── scripts/ # Build/publish scripts
├── .agents/ # OpenCode agent skills
├── package.json
├── tsconfig.json
├── vitest.config.ts
├── AGENTS.md # AI agent instructions
└── opencode.json # OpenCode MCP configESM-only: all local imports must include the .js extension.
BaseTool pattern: tool handlers extend BaseTool<T> for concurrency control, logging, credential masking, and error wrapping.
ToolRegistry: static class mapping tool names to handler functions. Falls back to PluginManager for plugin tools.
Input validation: every handler validates dirPath with validateDirPath and string params with validateStringParam.
FileScanner: all filesystem scanning goes through FileScanner.findFiles() which respects .gitignore, includePath, and excludePath.
Concurrency: a Semaphore(5) limits parallel operations via operationLimiter in BaseTool.
App metadata: always use AppInfo from utils/app-info.ts -- never hardcode version or name.
Path traversal prevention: all file operations resolve against strict base paths.
Credential masking: BaseTool automatically redacts authToken fields in logs. New sensitive params must be added to maskSensitive.
No secret leakage: credentials are detected but never logged or included in responses.
Concurrency protection: built-in semaphore prevents system saturation from parallel tool execution.
Binary detection: binary files are automatically detected and skipped during scanning.
See CONTRIBUTING.md for setup instructions, coding conventions, and PR expectations.
pnpm install -- install dependencies
Create a feature branch
Write code + tests
pnpm build && pnpm test -- verify
Open a PR with a clear description of intent and impact
MIT -- Copyright (c) 2026 Reasvyn
Performs an enterprise-grade code quality audit (linting). Analyzes tech stack, conventions, and applies industry best practices.
| Name | Required | Description | Default |
|---|---|---|---|
| dirPath | Yes | The absolute path to the local directory to audit. | |
| filePatterns | No | Optional. Glob patterns for files to audit. | |
| focusAreas | No | Optional. 'dead_code', 'structure', 'performance', 'naming', 'all'. | |
| includePath | No | Optional. Glob patterns to include. | |
| excludePath | No | Optional. Glob patterns to exclude. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It only says the tool performs an audit/linting. It does not disclose side effects (none expected), required permissions, or performance implications. Minimal behavioral disclosure.
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?
One sentence, 18 words. Front-loaded with key term 'code quality audit'. No extraneous fluff, though it could be slightly more informative without losing brevity.
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?
With 5 parameters, 24 sibling tools, and no output schema, the description should explain output format and selection criteria. It falls short, leaving the agent without enough context to use 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% with clear parameter descriptions. The description adds minimal extra semantic value beyond 'tech stack' and 'conventions', which indirectly relate to focusAreas. Baseline 3 is appropriate.
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 states it performs a code quality audit/linting, but the verb 'analyze' is vague. It does not clearly differentiate from sibling tools like 'detect_patterns' or 'lint_interactive'. However, it specifies the resource (code quality) and scope (tech stack, conventions), so it's above average.
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?
No guidance on when to use this tool versus the many sibling tools (e.g., check_style, audit_security, measure_coverage). The description lacks any 'when to use' or 'when not to use' context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Guards your code with enterprise-grade security audit covering OWASP Top 10, ISO/IEC 27001, secrets detection, privacy (GDPR/CCPA), and dependency vulnerabilities.
| Name | Required | Description | Default |
|---|---|---|---|
| dirPath | Yes | The absolute path to the local directory to audit. | |
| filePatterns | No | Optional. Glob patterns for files to scan. | |
| includePath | No | Optional. Glob patterns to include. | |
| excludePath | No | Optional. Glob patterns to exclude. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It mentions coverage areas but does not state whether the tool is read-only, modifies files, requires permissions, or returns a report. The phrase 'Guards your code' is vague.
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?
Single sentence of 20 words, concise and to the point. No redundancy or 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?
Despite the complexity of a multi-standard security audit, the description is very brief. It lacks information about output format, result interpretation, or required permissions. No output schema is present.
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?
All four parameters have schema descriptions (100% coverage), so the baseline is 3. The description does not add additional parameter-level context beyond what the schema provides.
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 the tool performs a security audit covering OWASP Top 10, ISO/IEC 27001, secrets detection, privacy, and dependency vulnerabilities. It distinguishes from sibling tools like analyze_code, catch_bugs, and check_style by focusing specifically on security compliance.
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?
No explicit guidance on when to use this tool versus alternatives. The description implies usage for security audits but does not mention when not to use or specify prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Catches bugs, errors, warnings, and potential issues in code: race conditions, memory leaks, runtime errors, dependency coupling, and performance issues.
| Name | Required | Description | Default |
|---|---|---|---|
| dirPath | Yes | The absolute path to the local directory to analyze. | |
| filePatterns | No | Optional. Glob patterns for files to scan. | |
| includePath | No | Optional. Glob patterns to include. | |
| excludePath | No | Optional. Glob patterns to exclude. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden. It does not disclose behavioral traits such as read-only nature, performance impact, or whether the tool modifies files. Listing bug types is useful but insufficient for 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 a single, well-structured sentence that packs relevant information without fluff. It lists specific issue types, making it efficient and informative.
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?
The tool has 4 parameters and no output schema. The description fails to explain the output format or how results are returned, leaving an agent without critical information for interpretation. Behavioral gaps (e.g., read-only) also reduce completeness.
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 parameters are already well-documented. The tool description adds no extra semantic value beyond the schema, meriting the baseline score of 3.
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 catches various code issues with specific examples (race conditions, memory leaks, etc.). It distinguishes from siblings like 'analyze_code' or 'check_style' by focusing on bugs and potential issues, though it does not explicitly contrast with them.
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?
No guidance is provided on when to use this tool vs alternatives like 'analyze_code' or 'detect_patterns'. It lacks explicit when/when-not instructions, prerequisites, or context for invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyzes which documentation artifacts need updates based on recent codebase changes. Uses git diff to prioritize doc updates.
| Name | Required | Description | Default |
|---|---|---|---|
| dirPath | Yes | The absolute path to the local project. | |
| sinceCommit | No | Optional. Check changes since this commit (default: last commit). | |
| priorityMode | No | Optional. 'impact' or 'recency' (default: 'impact'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It mentions using git diff to prioritize doc updates, which is useful, but does not disclose if the tool modifies files or requires specific permissions. It implies a read-only analysis.
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?
Two sentences, no redundancy, front-loaded with the purpose. Every word is relevant 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 3 parameters, no output schema, and 25 siblings, the description is mostly complete. It explains the tool's function and how it prioritizes. However, it does not describe the return format which could aid in understanding.
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 input schema has 100% description coverage for all three parameters, so the description adds no additional meaning beyond the schema. Baseline 3 is appropriate.
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 specific verb 'analyzes' and resource 'documentation artifacts needing updates'. It distinguishes from siblings like check_delta and find_docs by mentioning the use of git diff and prioritizing doc updates based on codebase changes.
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 tells when to use it (based on recent codebase changes) but does not explicitly state when not to use it or mention alternatives among the 25 sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compares what's documented versus what's actually in the code. Shows the delta between documentation claims and implementation reality.
| Name | Required | Description | Default |
|---|---|---|---|
| dirPath | Yes | The absolute path to the local project. | |
| docPath | Yes | The path to the documentation file. | |
| includeCodeSnippets | No | Optional. Include actual code in diff (default: true). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description should disclose behavioral traits. It only states the purpose without mentioning if it's a read-only operation, any side effects, or safety profile. The description lacks transparency beyond the basic function.
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 very concise with two sentences, no extraneous information, and the purpose is front-loaded. Every sentence adds value without padding.
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 and no annotations, the description is minimal. For a comparison tool, it could mention return format or typical output, but it is not deficient. It is adequate but lacks completeness for effective selection among 24 siblings.
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 description coverage is 100%, so the schema already documents all three parameters. The description does not add any additional meaning or constraints beyond what the schema provides, so baseline score is appropriate.
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 compares documentation against code and shows the delta. The verb 'compares' and resource 'documentation vs code' are specific, and it distinguishes itself from siblings like check_stale or verify_docs.
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 implies use when wanting to compare docs and code, but does not explicitly state when to use or not, nor does it mention alternatives like sync_documentation or verify_docs. No guidance on prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sniffs out documentation that has gone stale - not updated in 30+ days or out of sync with the actual code.
| Name | Required | Description | Default |
|---|---|---|---|
| dirPath | Yes | The absolute path to the local directory to check. | |
| maxAgeDays | No | Optional. Maximum age in days (default: 30). | |
| compareWithCode | No | Optional. Also check if docs match current code (default: true). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool checks last update time and code sync, but does not detail how the sync comparison works or any potential side effects. This is adequate but could be more precise.
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?
A single, well-crafted sentence that front-loads the action and is easy to parse quickly. No wasted words.
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?
The description lacks information about the output format or structure. With no output schema, the agent cannot anticipate the result type (e.g., list of files, report). This is a significant gap for a check tool.
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 input schema already describes all three parameters (dirPath, maxAgeDays, compareWithCode) with default values. The description echoes the staleness criteria (30 days, out of sync) but adds no new semantic detail beyond what the schema provides.
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 uses a specific verb 'sniffs out' and clearly identifies the resource as 'documentation that has gone stale'. It distinguishes from sibling tools like check_style or catch_bugs by focusing on staleness criteria (30+ days or code mismatch).
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?
No explicit guidance on when to use this tool versus alternatives such as verify_docs or sync_documentation. The description implies usage for stale doc detection but does not provide criteria for choosing it over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sniffs out project style: conventions, linters, and infers implicit coding patterns from codebase samples. Combines convention detection and code pattern analysis.
| Name | Required | Description | Default |
|---|---|---|---|
| dirPath | Yes | The absolute path to the local directory to analyze. | |
| excludePath | No | Optional. Glob patterns to exclude from scanning. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It does not mention whether the tool is read-only, modifies files, requires authentication, or has rate limits. The word 'sniffs out' implies reading but is ambiguous.
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 two sentences, front-loaded with the main action ('Sniffs out project style'), and contains no superfluous words. Every sentence adds value.
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 has only two simple parameters (100% covered) and no output schema or annotations, the description is partially complete. It explains the tool's dual focus but omits details on return format or specific behavior, which is needed for full context.
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% (both 'dirPath' and 'excludePath' are described). The description does not add extra meaning beyond what the schema provides, so baseline 3 is appropriate.
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 the tool's purpose: 'sniffs out project style: conventions, linters, and infers implicit coding patterns.' It uses specific verbs and resources, and distinguishes from siblings like 'lint_interactive' and 'detect_patterns' by combining both convention detection and code pattern analysis.
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?
No explicit guidance on when to use this tool versus alternatives like 'lint_interactive' or 'detect_patterns'. The description does not provide when/when-not criteria, leaving the agent without clear selection help.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Purges old cached repositories from the .docsgrep workspace. Removes repos older than the specified max age (default 7 days).
| Name | Required | Description | Default |
|---|---|---|---|
| localProjectPath | Yes | The absolute path to the local project containing .docsgrep workspace. | |
| maxAgeDays | No | Maximum age in days for cached repos (default: 7). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose all behavioral traits. It states it removes repos older than max age, but does not mention whether removal is permanent, whether confirmation is required, or any prerequisites (e.g., workspace must exist). Lack of destructive/reversibility info is a gap.
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?
Two concise sentences that front-load the main action ('Purges old cached repositories') and then specify the condition (older than max age). No extraneous information.
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, so description should explain return value (e.g., count of removed repos, success status). Without that, agent cannot determine how to proceed after invocation. Otherwise, adequate for a simple purge operation.
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% with descriptions for both parameters. Description adds minimal value beyond schema (e.g., default for maxAgeDays), but does not provide further clarifications like format or constraints.
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 purges old cached repositories from the .docsgrep workspace, specifying the exact resource and action. Differentiates from sibling tools like 'check_stale' which checks for staleness but doesn't purge.
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?
Implies usage for cleanup after analysis (e.g., after running analysis tools), but does not explicitly state when to use this tool versus alternatives (e.g., manually deleting files) or when not to use it (e.g., if repos are still needed).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetches a remote git repository to a temporary directory and finds documentation. Supports authentication for private repos.
| Name | Required | Description | Default |
|---|---|---|---|
| repoUrl | Yes | The URL of the git repository (e.g., https://github.com/user/repo.git). | |
| branch | No | Optional. Specific branch to explore. | |
| tag | No | Optional. Specific tag or version to explore. Overrides branch. | |
| authToken | No | Optional. Authentication token for private repositories. | |
| sshKeyPath | No | Optional. Path to SSH private key. | |
| localProjectPath | No | Optional. Local project path for workspace. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions fetching to a temporary directory and finding documentation, but omits details on cleanup, side effects, error handling, or return format. Essential behavioral traits like temp directory lifecycle are unclear.
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?
Two sentences, no wasted words. The primary action is front-loaded, and the auth support is placed second. Every sentence serves a 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?
For a tool with 6 parameters, no output schema, and no annotations, the description is somewhat incomplete. It doesn't specify what 'finds documentation' returns (e.g., file paths, content excerpts) or whether the temporary directory is cleaned up. While it covers the essential purpose, an agent would need more detail for reliable 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 coverage is 100%, so all 6 parameters are documented. The description adds 'Supports authentication for private repos' which relates to authToken and sshKeyPath but doesn't provide new meaning. The 'localProjectPath' parameter's role is not clarified in relation to 'temporary directory' mentioned in the description, potentially causing confusion.
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 uses specific verbs 'Fetches' and 'finds' with clear resources: 'remote git repository' and 'documentation'. It distinguishes from sibling tools like 'find_docs' or 'search_docs' by explicitly including the cloning step.
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?
No explicit guidance on when to use this tool versus alternatives among 24 siblings. The mention of auth support for private repos gives some context but no when-to-use or when-not-to-use instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Maps project architectural patterns (MVC, Repository, etc.) and suggests refactoring candidates (Base Class, Trait, Interface).
| Name | Required | Description | Default |
|---|---|---|---|
| dirPath | Yes | The absolute path to the project directory. | |
| minSimilarity | No | Minimum similarity score (0-1) to suggest abstraction. Default: 0.8 | |
| focus | No | Optional focus area. | |
| includePath | No | Optional glob patterns to include. | |
| excludePath | No | Optional glob patterns to exclude. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must cover behavioral traits. It does not state whether the tool is read-only or performs mutations, what the output format is, or any side effects (e.g., refactoring suggestions are just suggestions, not modifications). Lacks details on error handling or performance.
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?
Single sentence that is concise and front-loaded. No unnecessary words, clearly communicates 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 complexity (5 params, no output schema), the description lacks completeness. No mention of return format, whether results are displayed or returned, or any dependencies (e.g., project must be analyzable). No annotations to supplement.
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. Description does not add extra meaning beyond what parameters already convey (e.g., dirPath, minSimilarity, focus). Parameter descriptions in schema are self-explanatory.
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 action (maps, suggests) and resource (architectural patterns, refactoring candidates). It distinguishes from siblings like analyze_code (general analysis) and catch_bugs (bug detection).
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?
No explicit guidance on when to use this tool vs alternatives. Does not mention prerequisites, conditions, or when not to use it. Among 24 sibling tools with overlapping functions, this is a significant gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Spies on the project's technology stack by reading package manager files (e.g., package.json, composer.json, go.mod, Cargo.toml).
| Name | Required | Description | Default |
|---|---|---|---|
| dirPath | Yes | The absolute path to the local directory to analyze. | |
| excludePath | No | Optional. Glob patterns to exclude from scanning. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It states it reads files (implied read-only) but does not mention side effects, permissions, rate limits, or error handling. The informal tone 'Spies' may mislead about secrecy.
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, front-loaded sentence that covers the core purpose without extraneous words. It includes examples for clarity. However, its brevity sacrifices important details, balancing conciseness with 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 has 2 parameters, no output schema, and no annotations, the description lacks information about return values, error conditions, or behavior when files are absent. The examples help but are insufficient for full agent context.
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 description coverage is 100%, so baseline is 3. The description adds context by listing example files but does not elaborate on the parameters 'dirPath' or 'excludePath' beyond their schema types. No added meaning 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?
The description uses a specific verb 'Spies' and identifies the resource 'technology stack' by reading package manager files. It lists examples, giving clarity. However, it doesn't explicitly differentiate from sibling tools like 'detect_patterns', but the focus on package manager files helps distinguish it.
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?
No guidance on when to use this tool versus alternatives like 'analyze_code' or 'audit_security'. The description does not specify prerequisites or preferred scenarios, leaving the agent without decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Hunts for README files and documentation inside docs/ folders in a local directory.
| Name | Required | Description | Default |
|---|---|---|---|
| dirPath | Yes | The absolute path to the local directory to explore. | |
| includePath | No | Optional. Glob patterns to include in scanning. | |
| excludePath | No | Optional. Glob patterns to exclude from scanning. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry full burden. It lacks details on what happens if directory doesn't exist, recursion behavior, case sensitivity, or output format. Only states the search action without behavioral nuances.
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?
Single, direct sentence with no filler. Every word adds value, achieving maximum conciseness.
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?
For a simple tool with 3 parameters and no output schema, description covers the core action but omits return format, error handling, and edge cases. Adequate but not thorough.
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 description coverage is 100%, so the schema already documents all parameters. Description adds no extra meaning beyond the schema, meeting baseline but not exceeding.
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 uses specific verb 'hunts' and clearly states resource 'README files and documentation' and location 'inside docs/ folders in a local directory'. It effectively distinguishes from sibling tools like search_docs or read_file.
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?
No guidance on when to use or avoid this tool versus alternatives. Among 23 sibling tools (e.g., search_docs, verify_docs), there is no differentiation or context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Automatically provides relevant documentation context based on what code you're currently working on. No need to ask - it just knows.
| Name | Required | Description | Default |
|---|---|---|---|
| dirPath | Yes | The absolute path to the local project. | |
| currentFilePath | Yes | The path to the file currently being worked on. | |
| contextDepth | No | Optional. 'minimal', 'standard', or 'deep' (default: 'standard'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the full burden. It fails to disclose what the tool does under the hood (e.g., how it determines context, output format, limitations). 'It just knows' is vague and provides no actionable detail.
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?
Two short sentences, front-loaded with purpose. The second sentence is slightly marketing-fluff but does not waste much space. Could be more efficient by combining ideas.
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 100% schema coverage and no output schema, the description omits what 'context' actually includes (e.g., docs, examples, type info) and how the tool determines relevance. This is insufficient for an agent to predict behavior.
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 description coverage is 100%, so the baseline is 3. The description adds no parameter details beyond the schema, but the schema is already self-explanatory for the three parameters.
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 documentation context based on current code, using specific verbs 'provides' and 'context'. It distinguishes from sibling search tools like search_docs and find_docs by emphasizing automatic inference.
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 implies usage when automatic context is needed ('No need to ask'), but does not explicitly state when to use it over alternatives or when not to use it. No sibling comparisons are made.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sets up a docsgrep base camp in the specified project directory to store temporary files, logs, and reports. Also automatically updates the .gitignore file.
| Name | Required | Description | Default |
|---|---|---|---|
| projectPath | Yes | The absolute path to the local project root. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden. It discloses side effects (creating directories, updating .gitignore) but doesn't detail potential overwrites, permissions, or whether the operation is reversible.
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?
Two sentences, no wasted words, front-loaded with the main action. Ideal length for this simple tool.
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?
For a simple initialization tool with one parameter and no output schema, the description covers the main actions and side effects. Missing details like idempotency or error handling, but 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?
Schema coverage is 100% for the single parameter. The description adds no extra meaning beyond 'specified project directory' which aligns with the 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?
The description clearly states the tool sets up a base camp directory for temporary files, logs, and reports, and updates .gitignore. It distinguishes it from sibling tools which are primarily analysis or search tools, but doesn't explicitly differentiate from clone_repo or clear_cache.
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?
No guidance on when to use this tool vs alternatives, no prerequisites or context provided. It is implied for first-time setup but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Asks what you want to lint. Generates an interactive prompt showing detected tech stack and available linting options.
| Name | Required | Description | Default |
|---|---|---|---|
| dirPath | Yes | The absolute path to the local directory. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes interactive behavior and detected tech stack but does not clarify whether linting is executed after the prompt or what the return value is. With no annotations, more detail on side effects or subsequent actions would improve 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?
Two sentences, no redundant information. Efficiently conveys core functionality.
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 only one parameter and no output schema, description provides sufficient context for an interactive tool. Lacks explicit mention of return value or subsequent actions, but sufficient for basic understanding.
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% with one param (dirPath) described as absolute path. Description adds context that directory is used for tech stack detection, but this is marginal value beyond the 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 asks about linting and generates an interactive prompt with detected tech stack and linting options. Distinguishes itself from sibling tools like catch_bugs or check_style by focusing on an interactive linting workflow.
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?
Implied usage for interactive linting when user input is desired, but no explicit guidance on when to use versus sibling tools like check_style (automated style checks) or catch_bugs (bug detection). Lacks when-not-to-use or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Measures documentation coverage (docblocks) across the codebase. Language-agnostic support for JS, TS, PHP, Python, Go, Rust, etc.
| Name | Required | Description | Default |
|---|---|---|---|
| dirPath | Yes | The absolute path to the source directory. | |
| filePatterns | No | Optional. Glob patterns to filter source files. | |
| publicOnly | No | Optional. Only count public APIs (default: true). | |
| includePath | No | Optional. Glob patterns to include. | |
| excludePath | No | Optional. Glob patterns to exclude. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description should fully disclose behavior. It states it measures coverage but does not mention whether it modifies files, requires permissions, performance impact, or that it is read-only. Insufficient transparency for a tool with 5 parameters.
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?
Two concise sentences with no redundancy. Clearly front-loaded with the key action and scope. Every word is meaningful.
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?
Tool has 5 parameters and no output schema. Description does not explain return value format (e.g., percentage, count, file list), which is important for an agent to use correctly. Also lacks performance or scope context. Incomplete for the complexity level.
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 covers all parameters (100% coverage), so baseline is 3. Description adds value by stating language-agnostic support (JS, TS, etc.) and clarifying that it measures docblocks, which goes beyond schema. Slightly above baseline.
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 verb 'measures' and resource 'documentation coverage (docblocks)' and distinguishes from siblings like verify_docs or find_docs. It also specifies language support, making the scope clear.
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?
Description implies usage for measuring docblock coverage, but lacks explicit guidance on when to use this tool versus siblings like verify_docs or find_docs. No when-not-to-use or alternative suggestions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Peeks into the contents of a specific documentation or README file.
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | The absolute path to the file to read. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It only implies a read operation ('Peeks into the contents') but does not mention permissions, side effects (e.g., no file locking), or limitations (e.g., file size, encoding).
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 very concise (single sentence) with no wasted words. However, it could be slightly more informative without sacrificing conciseness.
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?
For a simple tool with one parameter and no output schema, the description is minimally adequate. It does not specify return format or file encoding, but given the low complexity, it covers the essential function.
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 the description adds no additional meaning beyond what the input schema already provides. The parameter 'filePath' is adequately described in the schema, making the description redundant.
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 action ('Peeks into the contents') and the target resource ('specific documentation or README file'). However, it does not explicitly distinguish this from sibling tools like 'find_docs' or 'search_docs', though the action of reading a file is distinct enough.
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 no guidance on when to use this tool versus alternatives (e.g., when to read vs. search or find documents). It lacks any when-not or prerequisite information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Greps for a pattern within documentation files (README, docs/**/*.md) in a local directory. Returns matching lines with file path and line number. Results ranked by relevance.
| Name | Required | Description | Default |
|---|---|---|---|
| dirPath | Yes | The absolute path to the local directory to search. | |
| pattern | Yes | The regex pattern to search for. | |
| filePattern | No | Optional. Regex to filter which doc files to search. | |
| contextLines | No | Optional. Number of surrounding context lines (max 5). | |
| includePath | No | Optional. Glob patterns to include. | |
| excludePath | No | Optional. Glob patterns to exclude. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that it searches only documentation files, returns lines with file path and line number, and ranks results. It implies a read-only operation and does not contradict any annotations. Could be improved by explicitly stating it is read-only or mentioning regex behavior, but overall adequate for a search tool.
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 three sentences with no wasted words. The first sentence states the action and scope, the second explains the output format, and the third notes ranking. Information is front-loaded and each sentence earns its place.
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 6 parameters (2 required), no output schema, and no annotations, the description covers the core functionality well. It explains the return format and scope. Minor omissions: no explicit mention of regex support or result limits, but these are common expectations for a 'grep' tool and the schema descriptions for optional parameters provide additional detail.
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 value by specifying the default file scope (README, docs/**/*.md), which is not present in the optional filePattern parameter's schema description. This extra context helps the agent understand the intended search domain.
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 greps for a pattern within documentation files (README, docs/**/*.md) in a local directory, returning matching lines with file path and line number ranked by relevance. This specific verb+resource+scope distinguishes it from siblings like find_docs (file finding) and semantic_search (semantic 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?
The description provides clear context (searches documentation files only) but does not explicitly state when to use this tool versus alternatives like semantic_search or find_docs. No exclusions or alternative recommendations are provided, leaving the agent to infer usage based on the 'grep' mention.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Asks before guarding. Shows what will be scanned (OWASP Top 10, secrets, privacy, dependencies) and available options.
| Name | Required | Description | Default |
|---|---|---|---|
| dirPath | Yes | The absolute path to the local directory. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states it 'asks before' and 'shows options', indicating interactive behavior. However, it does not disclose what happens after the user responds (e.g., whether actions like fixes are applied), nor does it mention permissions or side effects. Given no annotations, more detail would be beneficial.
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 (two sentences) and front-loaded with the key interactive aspect. However, it could be slightly more precise without adding length.
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?
The tool has no output schema, so the description should explain what the tool returns after interaction. It mentions 'shows what will be scanned' and 'options', but does not describe the output format or how the agent should handle it. With no annotations, more completeness is expected.
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 input schema already provides a description for the only parameter (dirPath), so this is the baseline. The description does not add new meaning beyond stating it is an absolute path, which is redundant with the 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?
The description identifies the tool as interactive ('Asks before guarding') and specifies the scan scope (OWASP Top 10, secrets, privacy, dependencies), which clearly differentiates it from sibling tools like audit_security. However, the term 'guarding' is slightly vague and could better indicate that the tool performs a security scan.
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?
Usage context is implied (when an interactive security check is desired) but no explicit guidance is provided on when to use this tool over alternatives like audit_security or detect_patterns. No exclusion criteria or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Searches documentation based on meaning (semantic search), not just keyword matching. Understands natural language queries and finds relevant docs.
| Name | Required | Description | Default |
|---|---|---|---|
| dirPath | Yes | The absolute path to the local directory to search. | |
| query | Yes | Natural language query about what you're looking for. | |
| topK | No | Optional. Number of top results to return (default: 5). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does not disclose whether the tool is read-only, what happens on invalid directories, or any limitations like network access or rate limits.
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, using two sentences with the key differentiating feature front-loaded. No unnecessary words.
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 or annotations, the description leaves out important context such as return format, error handling, and usage prerequisites for a search tool.
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% with clear parameter descriptions. The tool description reinforces but does not significantly add new information beyond what the schema already provides.
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 performs semantic search on documentation, contrasting with keyword matching. However, it does not explicitly link to the local directory parameter, leaving a slight ambiguity about the resource scope.
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 implies use when meaning-based search is needed, but lacks explicit guidance on when not to use it or mention of alternative sibling tools like search_docs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Provides comprehensive help for all docsgrep tools with detailed examples, common patterns, and pro tips.
| Name | Required | Description | Default |
|---|---|---|---|
| toolName | No | Optional. Specific tool to get help for (default: all tools). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description does not disclose side effects or safety, but for a help tool it is acceptable.
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?
Single sentence that is concise and to the point, though could be slightly 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?
Adequately describes the tool's purpose for a simple help tool; no output schema needed, but could mention return format.
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 description adds minimal extra meaning beyond the schema's 'Optional. Specific tool to get help for (default: all tools).'
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 provides comprehensive help for all docsgrep tools with details like examples and patterns, which is specific and distinct from sibling 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?
Implies use for obtaining help but does not explicitly state when to use versus sibling tools or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Automatically summarizes specific documentation files into concise, digestible chunks. Gets the essence without the noise.
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | The absolute path to the documentation file to summarize. | |
| maxLength | No | Optional. Maximum summary length in characters (default: 500). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It hints at non-destructiveness and summarization behavior but lacks specifics on authentication, rate limits, or potential limitations (e.g., file size). The 'essence without noise' is vague but adequate for a simple tool.
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?
Two sentences, no unnecessary words. The purpose is front-loaded and every word contributes to understanding.
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?
For a tool with two parameters, no output schema, and no annotations, the description provides a minimal but functional overview. It lacks details on output format or default behavior for maxLength, but is likely sufficient given low complexity.
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 both parameters are well-documented in the input schema. The description adds no additional semantic value beyond 'specific documentation files' for the filePath parameter.
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 action ('summarizes'), the resource ('specific documentation files'), and the outcome ('concise, digestible chunks'). It effectively distinguishes from sibling tools like read_file or search_docs by focusing on extraction of essence.
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?
No guidance is provided on when to use this tool versus alternatives (e.g., read_file for full content, search_docs for queries). The description does not mention prerequisites or exclusions, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Automatically creates or updates documentation based on code changes. Detects new methods, changed signatures, and generates doc stubs.
| Name | Required | Description | Default |
|---|---|---|---|
| dirPath | Yes | The absolute path to the local project. | |
| filePaths | No | Optional. Specific files that changed (default: auto-detect from git). | |
| updateMode | No | Optional. 'create', 'update', or 'both' (default: 'update'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the full burden. It adequately describes the action of creating/updating documentation and the detection of code changes, but does not disclose whether changes are reversible, required permissions, or what happens to existing documentation not covered by the changes.
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?
Two sentences with no wasted words. The first sentence captures the core purpose, and the second adds specific capabilities. Front-loaded with key action.
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 does not explain return values, which is acceptable. It covers purpose and parameters well. Missing mention of git prerequisites or workspace setup, but overall sufficient for a tool with 3 params and simple output.
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%, providing baseline of 3. The description adds context beyond the schema: 'based on code changes', 'auto-detect from git' for filePaths, and explanation of updateMode. This helps agents understand parameter usage beyond dry definitions.
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 states the verb 'creates or updates' and the resource 'documentation', with a clear scope 'based on code changes'. It provides specific details like 'detects new methods, changed signatures, and generates doc stubs', which distinguishes it from sibling tools like find_docs or search_docs.
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?
No explicit guidance on when to use this tool versus alternatives. The description implies usage for code changes, but doesn't mention when not to use or provide any exclusion criteria or mention of sibling tools like verify_docs or check_delta.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Checks consistency between code and documentation. Verifies that all documented methods actually exist and that parameters match reality.
| Name | Required | Description | Default |
|---|---|---|---|
| dirPath | Yes | The absolute path to the local project. | |
| docPath | Yes | The path to the documentation file to validate. | |
| strictMode | No | Optional. Fail on warnings too (default: false). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses basic behavior (checks consistency, verifies methods and parameters) but lacks details on failure modes, whether it's read-only, permissions required, or scope of verification. It is not misleading but is incomplete.
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 (two sentences) and front-loaded with the core purpose. No unnecessary words, but could benefit from slightly more structure to separate use case from behavior.
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?
For a tool with 3 parameters, many siblings, and no output schema, the description is too minimal. It omits return value information, error handling, and advice on when to apply. More context is needed to fully understand the tool's role.
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 description coverage is 100%; each parameter has a clear description in the schema. The tool description does not add additional parameter meaning beyond what the schema already provides, so baseline score of 3 is appropriate.
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: checking consistency between code and documentation by verifying method existence and parameter matching. It distinguishes itself from sibling tools like check_stale or check_style by focusing on documentation accuracy.
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?
No explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or context that would help an agent decide between verify_docs and sibling tools like find_docs or check_stale.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Many tools have overlapping purposes, such as multiple code analysis tools (analyze_code, catch_bugs, check_style, detect_patterns, lint_interactive) and several documentation staleness checks (check_artefacts, check_delta, check_stale). This makes it difficult for an agent to select the correct tool.
Most tools follow a verb_noun pattern (e.g., clone_repo, search_docs), but a few deviate like lint_interactive and security_interactive where the second word is an adjective rather than a noun. Overall, the naming is mostly consistent but has minor inconsistencies.
With 25 tools, the set is overly large for a server named 'docsgrep'. Many tools could be consolidated (e.g., combining check_artefacts, check_delta, check_stale into one tool with parameters). The breadth suggests poor scoping.
The tool set covers a wide range of documentation and code analysis tasks, but it includes many tools that are not directly related to the core documentation grep purpose (e.g., security auditing, bug catching). This leads to a lack of focus rather than missing functionality.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
An MCP server that gives your AI access to the source code and docs of all public github repos
A MCP server built for developers enabling Git based project management with project and personal…
Augments MCP Server - A comprehensive framework documentation provider for Claude Code
MCP server for developer documentation, generated by doc2mcp.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/reasvyn/docsgrep'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
