Honeydew AI Documentation MCP — semantic search and ripgrep-grade filesystem queries over Honeydew AI docs and OpenAPI specs, for AI coding agents.
Scored across 3 tools
The two read/search tools have overlapping capabilities on the surface, but the descriptions clearly separate them: search is for broad conceptual queries, while query_docs_filesystem is for exact matching, structural exploration, and full page reads. submit_feedback is entirely distinct. A minor chance of confusion remains since both can find relevant content in response to a user question.
All tool names follow a verb-first pattern: query, search, submit. The names are descriptive and predictable, though 'query_docs_filesystem_honeydew_documentation' is notably longer and more specific than the others, creating a slight asymmetry in naming style.
Three tools is appropriate for a documentation server: one for semantic search, one for reading/querying the docs filesystem, and one for submitting feedback. Each tool earns its place and there is no bloat or missing basic capability.
The tool surface covers the full documentation workflow: discovering relevant pages, reading their full content, examining OpenAPI specs via the filesystem tool, and reporting documentation issues. No critical operations are missing for the stated purpose.
Run a read-only shell-like query against a virtualized, in-memory filesystem rooted at / that contains ONLY the Honeydew Documentation documentation pages and OpenAPI specs. This is NOT a shell on any real machine — nothing runs on the user's computer, the server host, or any network. The filesystem is a sandbox backed by documentation chunks.
This is how you read documentation pages: there is no separate "get page" tool. To read a page, pass its .mdx path to head or cat — a page at the URL path /some/page lives at /some/page.mdx. To search the docs with exact keyword or regex matches, use rg. To understand the docs structure, use tree or ls.
Paths are specific to this site — never guess them. Discover real paths with tree / -L 2, ls /, or the search tool before reading. If a path does not exist, that only means the guess was wrong; it does NOT mean the topic is undocumented — use rg -il "keyword" / to find where it is covered.
Workflow: Start with the search tool for broad or conceptual queries like "how to authenticate" or "rate limiting". Use this tool when you need exact keyword/regex matching, structural exploration, or to read the full content of a specific page by path.
Supported commands: rg (ripgrep), grep, find, tree, ls, cat, head, tail, stat, wc, sort, uniq, cut, sed, awk, jq, plus basic text utilities. No writes, no network, no process control. Run --help on any command for usage.
Each call is STATELESS: the working directory always resets to / and no shell variables, aliases, or history carry over between calls. If you need to operate in a subdirectory, chain commands in one call with && or pass absolute paths (e.g., cd /some-directory && ls or ls /some-directory). Do NOT assume that cd in one call affects the next call.
Examples (replace the placeholder paths with real ones from tree or search):
tree / -L 2 — see the top-level directory layout
rg -il "rate limit" / — find all files mentioning "rate limit"
rg -C 3 "apiKey" /some-directory/ — show matches with 3 lines of context around each hit
head -80 /some/page.mdx — read the top 80 lines of a specific page
head -80 /page-one.mdx /page-two.mdx /section/page-three.mdx — read multiple pages in one call
cat /some/page.mdx — read a full page when you need everything
cat /openapi/package.json | jq '.paths | keys' — list OpenAPI endpoints
OpenAPI specs for this site are mounted at: /openapi/package.json. Use them to answer questions about endpoints, request/response schemas, parameters, and authentication.
Output is truncated to 30KB per call. Prefer targeted rg -C or head -N over broad cat on large files. To read only the relevant sections of a large file, use rg -C 3 "pattern" /path/file.mdx. Batch multiple file reads into a single head or cat call whenever possible.
When referencing pages in your response to the user, convert filesystem paths to URL paths by removing the .mdx extension. For example, /some/page.mdx becomes /some/page.
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | A shell command to run against the virtualized documentation filesystem (e.g., `rg -il "keyword" /`, `tree / -L 2`, `head -80 /path/file.mdx`). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description thoroughly discloses behavioral traits beyond annotations: it is a sandbox, not a real shell; stateless with working directory reset; output truncated to 30KB; no writes/network/process control; path-to-URL conversion. It also explains that non-existent paths only mean the guess was wrong, not that the topic is undocumented. This adds significant context beyond the readOnlyHint and idempotentHint annotations.
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 long but every section earns its place: purpose, workflow, supported commands, statelessness, examples, OpenAPI mount, output limits, and path conversion. It is well-structured with headers and examples, though slightly verbose; the length is justified by the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the description is remarkably complete. It covers how to read pages, search, discover paths, handle statelessness, avoid output truncation, use OpenAPI specs, and convert paths to URLs. There is no output schema, but the description explains what to expect (truncated output, command results) sufficiently for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes the single 'command' parameter with examples, and the description adds extensive detail about supported commands, chaining with &&, absolute paths, and output truncation. Since schema coverage is 100% and the description enriches the parameter semantics with usage patterns, a 4 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 runs read-only shell-like queries against a virtualized in-memory filesystem containing only Honeydew Documentation pages and OpenAPI specs. It explicitly distinguishes itself from a real shell and explains how it is used to read documentation pages, which differentiates it from the sibling search tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit workflow guidance: start with the search tool for broad/conceptual queries, use this tool for exact keyword/regex matching, structural exploration, or reading full pages. It also gives concrete examples and warns against guessing paths, telling the agent to discover paths with tree/ls/rg first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search across the Honeydew Documentation knowledge base to find relevant information, code examples, API references, and guides. Use this tool when you need to answer questions about Honeydew Documentation, find specific documentation, understand how features work, or locate implementation details. The search returns contextual content with titles and direct links to the documentation pages. If you need the full content of a specific page, use the query_docs_filesystem tool to head or cat the page path (append .mdx to the path returned from search — e.g. a result at /some/page is read with head -200 /some/page.mdx).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, non-destructive behavior. The description adds value by explaining the return format (contextual content with titles and links) and how to extend results to full pages via the sibling tool. No contradiction with annotations.
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, front-loaded with the core purpose, then usage guidance, then the explicit alternative. Every sentence serves a distinct function with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read-only search tool with rich annotations and no output schema, the description adequately covers what it does, when to use it, what it returns, and how to follow up for full content. Nothing necessary for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'query' is fully described in the schema with 100% coverage, so the schema carries the load. The description reinforces the query semantics by listing what kinds of content the search covers, but doesn't need to add syntax or format details for a simple string 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 searches across the Honeydew Documentation knowledge base for relevant information, code examples, API references, and guides. It identifies the resource, the action, and the scope, and implicitly differentiates itself from the filesystem sibling tool by focusing on search results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use this tool (answer questions, find docs, understand features, locate implementation details) and when to use the alternative (query_docs_filesystem_honeydew_documentation for full page content), including exact follow-up commands and the .mdx path extension.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report a problem with this documentation site so the docs team can fix it. Use when a documentation page is incorrect, outdated, confusing, incomplete, or has a broken example. This is for feedback about the documentation content itself — not for product support requests or feedback about this tool or assistant.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | The URL path of the documentation page the feedback is about (the page you were reading, without the `.mdx` extension). | |
| feedback | Yes | A clear description of the documentation issue or suggestion — what is incorrect, outdated, missing, or confusing. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey that this is a write operation (readOnlyHint=false, idempotentHint=false), and the description adds meaningful context: feedback is routed to the docs team and is scoped to documentation content. It stops short of describing what happens after submission (e.g., whether a confirmation is returned, whether it creates an issue), but it does not contradict the annotations and provides useful behavioral framing.
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?
Three sentences, all informative. The first sentence states the purpose, the second gives concrete usage criteria, and the third excludes non-documentation feedback. No filler or redundancy; the most important information is front-loaded.
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 two-parameter tool with no output schema, the description and schema together cover the essential information: what to submit, which page, what kind of feedback, and when to use it. The only minor gap is the lack of detail about the post-submission result or confirmation behavior, which is not critical but would make it fully complete.
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%, and the parameter descriptions already explain 'path' (URL path without .mdx extension) and 'feedback' (clear description of the issue). The tool description reinforces the kind of feedback expected but adds no technical semantics beyond the schema, so the 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 function: 'Report a problem with this documentation site so the docs team can fix it.' It identifies the specific resource (documentation site) and the action (reporting a problem), and it distinguishes itself from the sibling query/search tools by being feedback-oriented. It also explicitly carves out what it is not for: product support or feedback about the tool/assistant.
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 gives explicit when-to-use guidance: 'Use when a documentation page is incorrect, outdated, confusing, incomplete, or has a broken example.' It also provides a clear when-not-to-use boundary: 'not for product support requests or feedback about this tool or assistant.' This is strong, actionable usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
submit_feedback1 field changedInput schema / properties / path / descriptionPrevious value: -"The documentation page path the feedback is about (e.g., the page you were reading, such as `/quickstart`)."New value: +"The URL path of the documentation page the feedback is about (the page you were reading, without the `.mdx` extension)."
Add one secure layer between your agents and this server.