docshelf-mcp

by ignatenkofi

Overview Schema Source Related Servers Score Discussions Admin

Python

Local

Server Quality Checklist

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

Latest release: v0.4.1
Disambiguation5/5
Each tool targets a distinct operation: init, add single, add batch, read, remove, rename, rebuild index, doctor check, search, list, and standalone conversion. While add_document and convert_pdf both handle PDF conversion, the former commits to the shelf while the latter does not, making their purposes clearly separable. No two tools appear to overlap in function.
Naming Consistency5/5
All tools follow a consistent `docshelf_<verb>_<noun>` snake_case pattern, with clear, descriptive verbs like add, remove, rename, search, list, convert. The only slightly unusual verb is 'doctor', but it is intuitive for a health-check tool. The prefix is uniformly applied across all 11 tools, creating a strong, predictable convention.
Tool Count5/5
11 tools is well within the ideal 3–15 range for a domain-specific server. Each tool serves a distinct need in the document shelf lifecycle, from initialization and document ingestion to search, maintenance, and standalone conversion. No tool feels superfluous, and the surface is neither too sparse nor overloaded.
Completeness5/5
The tool set covers the full lifecycle of a document shelf: create (init), add documents (both single and batch), read, remove, rename (update metadata), list, search, and rebuild the index. Additionally, a 'doctor' tool addresses drift repair and a standalone PDF converter supports pre-shelf workflows. There are no obvious gaps or dead ends for the stated purpose.
Average 4.3/5 across 11 of 11 tools scored. Lowest: 3.7/5.
See the Tool Scores section below for per-tool breakdowns.
- 1 of 1 community issues answered or closed in the last 6 months
- 73 commits in the last 12 weeks
- Last stable release on August 24, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
View related servers

How to sync the server with GitHub?

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

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

How is the quality score calculated?

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

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

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

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

Tool Scores

Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only, idempotent, and non-destructive nature. The description adds the grouping-by-category behavior and the 'list everything' default. However, it does not disclose pagination, ordering, or what 'grouped' looks like in the response.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, with no wasted words. The filter behavior is stated in a single clear sentence after the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with an output schema, the description covers the main filtering behavior. But the omission of shelf_path and lack of any note about result grouping details make the definition incomplete for an agent that needs to call it correctly in all cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description usefully explains the category parameter's behavior, which helps given low schema coverage. However, shelf_path appears in the schema with no description and is never addressed in the tool description, leaving a potentially important scoping parameter unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('documents') and adds distinctive grouping behavior ('grouped by category'). It does not explicitly differentiate itself from siblings like docshelf_search, so it stops short of a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage context: pass a category to filter, omit it to list everything. This is clear and actionable, though it does not mention alternatives or exclusions relative to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true and destructiveHint=false. The description adds behavioral detail: creates directory layout, pre-creates categories, stores remote URL, and notes that it never overwrites an existing manifest. This sufficiently explains its behavior beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with three sentences covering purpose, actions, and idempotency. It front-loads the key action. No extraneous information, though it could be slightly tighter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool complexity (initialization with multiple files and options) and the presence of an output schema (not shown but noted), the description adequately lists created artifacts and guarantees idempotency. It covers key edge cases (existing shelf, manifest non-overwrite) but omits details like permission handling or error states, which are acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already contains detailed descriptions for all properties of InitShelfInput, such as name, branch, provider, etc. The tool description adds minimal parameter context (e.g., mentions default_categories and github_remote). Given the schema coverage is stated as 0% (likely a misrepresentation), but the descriptions in the schema are thorough, the description adds some but not significant value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Bootstrap a new document shelf at `shelf_path`' with specific actions (creates directory layout, INDEX.md, .docshelf.json, .gitignore). It unambiguously distinguishes from sibling tools like docshelf_add_document by focusing on initializing the shelf itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it is used to set up a shelf and is idempotent ('safe to call on an existing shelf to update metadata'). However, it does not explicitly state when not to use it or mention alternatives among siblings, though the specialized purpose makes it obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds context beyond annotations by clarifying that this is standalone and does not update a shelf or the INDEX. It also mentions optional H2 splitting. Annotations already provide idempotent/destructive hints, so the bar is lower; the description covers the main side-effect boundary well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, purposeful sentences. The main action and exclusions are front-loaded, followed by usage guidance and the optional split behavior. There is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a conversion tool with a rich schema and output schema, the description is largely complete: it states purpose, scope, and when to use it. It could slightly improve by naming the sibling to use when committing to a shelf is desired, but the schema covers invocation details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The nested input schema fully documents all parameters: pdf_path, out_dir, split, and quality, including defaults, enums, and output filename behavior. The tool description adds no parameter-level detail, but the schema already carries that weight, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Standalone PDF → Markdown conversion'. It immediately scopes the tool by stating '(no shelf, no INDEX update)', which clearly distinguishes it from shelf-management siblings without needing to inspect them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Use when you want the converted file but don't yet want to commit it to a shelf' gives an explicit condition for use. It implies the alternative is a shelf-committing operation, but it does not name a specific sibling tool, so the routing is clear but slightly less direct than it could be.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide idempotentHint=true and destructiveHint=false, indicating safe reuse. The description adds context by noting it regenerates from on-disk state, which is consistent with annotations. It does not contradict annotations and provides useful behavioral insight beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two concise sentences. The first sentence states the action and target, and the second provides a use case. No unnecessary words or repetition; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of the tool and the presence of an output schema, the description adequately covers purpose and usage. It could optionally mention that INDEX.md is overwritten, but the idempotent and non-destructive annotations imply this is safe. The description is complete enough for an AI agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already contains a description for 'shelf_path' ('Path to the shelf root directory.'), which fully explains the parameter. The tool description does not add any extra meaning to this parameter. Since schema coverage is 0% (description does not mention parameters), but the schema itself is descriptive, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool regenerates INDEX.md from the current on-disk shelf state. The verb 'Regenerate' and the resource 'INDEX.md' are specific and unambiguous. It distinguishes itself from siblings like docshelf_add_document and docshelf_search by focusing on index reconstruction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Useful after manual edits to docs/ or .docshelf.json', providing a clear scenario for when to use the tool. It does not explicitly state when not to use it, but the implied context is sufficient given the tool's specific purpose. No alternative is needed as it's the only index rebuild tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly, idempotent, and non-destructive annotations, the description discloses case-insensitive token matching, all-token vs. any-token fallback with match_mode, heading-priority ranking, section-file behavior for split documents, and the remote fetch URL. These are substantive behavioral details that materially affect how an agent interprets results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence, and every subsequent sentence contributes operational detail. It is thorough without being bloated or repetitive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only search tool with an output schema and strong annotations, the description covers scope, matching, fallback, ranking, split-document behavior, and result fields. The sole notable gap is the lack of explanation for the optional shelf_path parameter, which prevents a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain the shelf_path parameter at all and does not mention max_results. Since schema description coverage is reported as 0%, the description was expected to compensate for parameter-level meaning, but it only covers query semantics and result shape, leaving the optional parameters ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Plain-text search across every Markdown file in the shelf.' It clearly distinguishes this tool from sibling read, list, and write tools, and the detailed matching semantics make its purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the intended use clear: keyword search over the whole shelf, with explicit fallback and ranking behavior. It does not explicitly name alternatives or state when to prefer docshelf_read_document, but the search-versus-read distinction is strongly implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses behaviors such as PDF-to-Markdown conversion, automatic splitting of large documents, slug collision handling with overwrite flag, regeneration of INDEX.md, and warnings for suspicious sections. This goes well beyond the annotations (idempotentHint, destructiveHint) by explaining exactly what happens under various conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a lead sentence and bullet points. It is informative but somewhat lengthy; however, every sentence adds value. The information could be condensed without loss, but it is not overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multiple parameters, conversion, splitting, collision handling), the description covers most important aspects: conversion options, splitting criteria, overwrite behavior, warnings, and INDEX.md regeneration. However, it only mentions 'PDF or Markdown file' at the start, while the input schema supports additional formats (DOCX, HTML, EPUB) – this omission could mislead users.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning beyond the input schema's property descriptions. For example, it explains the effect of split (based on size and H2 headings), the quality options with 'fast' and 'high' alternatives, and the overwrite behavior with error vs replacement. It also clarifies the slug parameter's purpose and the file formats supported (though schema lists more).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Add a PDF or Markdown file to the shelf and refresh INDEX.md' which clearly states the action (add) and resource (shelf). It distinguishes from sibling tools like docshelf_add_directory by focusing on a single file, and from docshelf_remove_document by the operation type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides details on parameters (split, overwrite, quality) but does not explicitly guide when to use this tool versus alternatives like docshelf_add_directory or docshelf_rename_document. It implicitly states use for adding a single file, but lacks explicit exclusions or comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool is read-only by default, that fix=true applies only safe fixes (prune, delete, rebuild), and that other findings remain report-only. This aligns with annotations (idempotentHint=true, destructiveHint=false) and adds valuable context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose, list of findings, and separated behavior for read-only vs fix mode. It is concise but could be slightly more compact; still efficient at about 100 words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description adequately covers what the tool checks (six categories) and the fix behavior. It also mentions sorting for stable diffing, adding useful context without needing to describe return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the input schema has 0% description coverage, the description explains the 'fix' parameter's effect and implicitly mentions 'shelf_path'. It adds meaning beyond the schema by detailing which fixes are applied.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks the shelf for drift and optionally applies safe fixes, listing specific findings (stale meta, orphaned splits, etc.). It distinguishes from sibling tools like rebuild_index by covering both diagnosis and selective fixes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (read-only by default, pass fix=true to apply) but does not explicitly state when to use this tool over siblings like docshelf_rebuild_index. No when-not or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (idempotentHint=true, destructiveHint=false), the description adds key behaviors: non-recursive scan, single INDEX rebuild, default patterns, error reporting without aborting. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus a bullet-like list. It is front-loaded with the main purpose, and every sentence contributes necessary context. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, the description covers scanning scope, default patterns, INDEX behavior, error handling, and parameter defaults. An output schema exists, so return values are not needed. The description fully contextualizes usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for each parameter (e.g., split, quality, patterns). The description adds minimal extra meaning, like default patterns and non-recursive scanning, but mostly restates what the schema covers. Baseline is 3 due to high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'add', the resource 'every matching file in a directory', and the side-effect 'rebuilding INDEX.md once'. It distinguishes from siblings like docshelf_add_document by focusing on a directory scan.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the tool scans a directory non-recursively for matching patterns, which tells when to use it. It implicitly contrasts with single-file siblings, but lacks explicit when-not or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true. The description adds significant context: removes file, split sections, metadata entry, regenerates INDEX.md, and offers dry_run for safe preview. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise: three sentences with front-loaded purpose, no unnecessary words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's destructive nature and the presence of an output schema (not shown), the description covers effects, dry-run, and post-step responsibilities. It is complete for safe agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions already cover all parameters thoroughly (e.g., document accepts filename/slug/title, dry_run effect). The description repeats some of this but adds no new meaning beyond the schema, resulting in baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb 'Remove' and the resource 'document', including what is removed (file, split sections, metadata). It distinguishes from siblings like add, rename, rebuild by the specific action and side effects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains acceptable inputs (filename, slug, title) and mentions dry_run for preview. It also notes that the caller must commit/push. However, it does not provide explicit when-to-use vs alternatives, but context is clear for a removal tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, and the description adds detailed behavioral context: it moves files, changes slugs, regenerates INDEX.md, and refuses to overwrite existing targets. This goes beyond the annotations to give a clear picture of side effects and safety mechanisms.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, with a clear summary in the first sentence. Each additional sentence provides necessary details like required parameters, conflict handling, dry-run, and ownership of git step. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the destructiveHint annotation and presence of an output schema, the description fully covers the tool's behavior, constraints, and prerequisites. It explains side effects, dry-run capability, and the caller's responsibility for git commits, making it complete for an AI agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has detailed descriptions for each parameter. The tool description adds value by explaining the relationship between new_title and slug changes, and new_category and directory moves, but this is more behavioral than semantic. Given high schema coverage, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear verb and resource: 'Retitle, recategorize, or re-describe a document — no re-conversion.' It explicitly states the tool's primary purpose and distinguishes it from siblings like docshelf_add_document (adding) and docshelf_remove_document (removing).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tells the agent which parameters are at least one required ('Give at least one of new_title / new_category / new_description'), explains behavior on conflict ('Refuses to clobber'), and provides a dry-run option. It also mentions post-invocation steps. However, it does not explicitly list when not to use this tool or compare it to alternatives like docshelf_read_document.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false (safe read-only). The description adds crucial behavioral details: truncation via max_bytes with truncated flag, paging using next_offset (with UTF-8 boundary explanation), and rejection of paths escaping docs/. No contradictions 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured, starting with the core purpose, adding use-case context, then detailing parameters and behavior. It is slightly long (8 lines) but every sentence adds value. There is no wasted text, and the front-loading is effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers essential aspects: purpose, when to use, parameter guidance, security (path rejection), and paging behavior. Since an output schema exists (context signal), the description does not need to detail return values. The coverage is thorough given the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has descriptions for offset and max_bytes, but shelf_path lacks a description. The description adds significant value by explaining the paging mechanism, how next_offset works, and the role of max_bytes. This goes beyond the schema's information, but shelf_path remains undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read a document or section file from inside the shelf's docs/.' This is a specific verb-resource combination that uniquely identifies the tool's purpose. It is immediately distinguished from sibling tools like docshelf_add_document (write) and docshelf_remove_document (delete).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool: 'useful for private or purely-local shelves where the raw.githubusercontent.com fetch trick doesn't apply.' It also instructs to pass a relative_path from search/list_documents. However, it does not explicitly state when not to use this tool versus alternatives, though the use-case context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

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

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

Card Badge

docshelf-mcp MCP server – quality and maintenance score on Glama

Copy to your README.md:

[![docshelf-mcp MCP server – quality and maintenance score on Glama](https://glama.ai/mcp/servers/ignatenkofi/docshelf-mcp/badges/card.svg)](https://glama.ai/mcp/servers/ignatenkofi/docshelf-mcp)

Score Badge

Copy to your README.md:

[![docshelf-mcp MCP server – quality and maintenance score on Glama](https://glama.ai/mcp/servers/ignatenkofi/docshelf-mcp/badges/score.svg)](https://glama.ai/mcp/servers/ignatenkofi/docshelf-mcp)

Latest Blog Posts

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

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ignatenkofi/docshelf-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server