@qelos/better-mcp

by qelos-io

Overview Schema Related Servers Score Discussions

TypeScript

Local

Server Quality Checklist

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

Latest release: v0.1.0
Disambiguation4/5
Most tools have distinct purposes, but 'list_directory' and 'list_directory_with_sizes' overlap significantly. Also, 'read_file' is deprecated and duplicates 'read_text_file', though the deprecation note mitigates confusion.
Naming Consistency5/5
All tools follow a consistent 'fs__' prefix with clear, descriptive snake_case names. No mixing of conventions.
Tool Count5/5
14 tools is a reasonable number for a file system server. Each tool covers a specific operation without excessive fragmentation.
Completeness3/5
Covers essential file system operations but lacks a delete or copy tool, which are common needs. Also missing append functionality. These gaps could hinder some workflows.
Average 3.9/5 across 14 of 14 tools scored. Lowest: 3/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 3 commits in the last 12 weeks
- No stable releases found
- 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.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

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

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

How is the quality score calculated?

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

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

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

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

Tool Scores

Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It describes output structure (name, type, children) and formatting (2-space indentation), and mentions directory restriction. However, lacks details on depth limits, symlink handling, or error behavior.
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?
Two sentences with clear structure: purpose first, then detail on children arrays and formatting. No redundant text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and 0% parameter coverage, the description lacks essential details about parameter usage and limitations. It covers output structure but not enough for a file system tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. Description does not mention parameters like 'path' (absolute vs relative?) or 'excludePatterns' (pattern syntax?). Adds no meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a recursive tree view of files and directories as a JSON structure', specifying a verb and resource. It distinguishes from sibling tools like fs__list_directory (non-recursive) and fs__list_directory_with_sizes (includes sizes).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. The only context is 'Only works within allowed directories', but no explicit 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the return format (base64 and MIME type) and a restriction (allowed directories), but it does not mention error handling, file size limits, or what happens if the file is not an image/audio. Since no annotations are present, the description carries the full burden, which is partially met.
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 extremely concise with two sentences, front-loading the main action and return type. Every word adds value, and it avoids redundancy.
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 simple tool with one parameter and no output schema, the description covers the essential aspects: what it reads, what it returns, and a key constraint. Missing details like error behavior and path validation are minor gaps, but overall it is fairly complete.
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 only parameter 'path' is described implicitly through the constraint 'only works within allowed directories', adding some context beyond the bare schema. However, no details about path format, absolute vs relative, or required extensions are given. With 0% schema coverage, the description should provide more, but for a single parameter it is minimally acceptable.
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 it reads image or audio files and returns base64 and MIME type, distinguishing it from sibling tools like fs__read_text_file. However, it does not explicitly exclude other file types or mention that it only supports media files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a constraint ('Only works within allowed directories') but offers no guidance on when to use this tool over similar tools like fs__read_file or fs__read_text_file. No alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden of behavioral disclosure. It conveys that edits are line-based, require exact matches, and return a git-style diff. However, it does not specify whether the operation is atomic, what happens if oldText is not found, or the file must exist, leaving gaps in expected behavior.
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 extremely concise: three sentences that first state the main function, then detail the mechanism and output, and finally note a constraint. Every sentence adds value with no redundancy or unnecessary information.
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 moderate complexity (3 parameters, no output schema), the description covers the key aspects: what it does, how it works, what it returns, and a constraint. It lacks detail on edge cases (e.g., matching failure, file type requirements) but provides sufficient context for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 33% (only dryRun and inner fields have descriptions). The description adds context that edits are line-based and exact, but does not elaborate on the 'path' parameter or provide format constraints. The schema's own description of oldText ('must match exactly') is sufficient, but the overall parameter semantics are minimally reinforced.
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 makes 'line-based edits to a text file,' specifying the verb (edit) and resource (text file). It distinguishes from siblings like fs__write_file, which overwrites entire files, by emphasizing line-level changes and exact replacement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives. It mentions a constraint ('only works within allowed directories') but lacks a direct comparison to sibling tools like fs__write_file or suggestions for when line editing is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry burden. Mentions output formatting with prefixes and directory constraint, but omits whether listing is recursive, performance notes, or error behavior.
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 sentences, front-loaded with main action, no wasted words. 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 simple one-parameter tool with no output schema or annotations, description covers purpose, output format, and constraint. Could mention recursion or sorting but not essential.
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?
Schema coverage is 0%. Description only repeats that 'path' specifies the directory to list and adds constraint of allowed directories. No examples, formats, or additional meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States 'Get a detailed listing of all files and directories in a specified path' with specific verb and resource. Distinguishes from siblings like fs__list_directory_with_sizes and fs__directory_tree by noting [FILE] and [DIR] prefixes.
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?
Implies usage: 'essential for understanding directory structure' and constraint 'Only works within allowed directories.' No explicit when-not-to-use or comparison to alternative listing tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey all behavioral traits. It claims to read 'complete contents', yet the input schema includes 'head' and 'tail' parameters that limit output to partial lines. This contradiction misleads the agent about the tool's actual behavior. No mention of encoding, file size limits, or error handling.
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 short sentences with no redundant words. It efficiently communicates the core action and deprecation status.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 parameters (one required) and no output schema. The description omits crucial context: the ability to read partial lines via head/tail, the file encoding assumed, any size restrictions, or how it differs from read_text_file beyond deprecation. The agent lacks enough information to use it correctly or decide between siblings.
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?
Schema coverage is 67% (path lacks a description; tail and head have descriptions but are not explained in the tool description). The description says 'complete contents', which contradicts the optional head/tail parameters that allow partial reads. The description adds no value beyond the schema and actually undermines parameter understanding.
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 action: 'Read the complete contents of a file as text', and immediately distinguishes it from the sibling tool by marking it as DEPRECATED and pointing to 'read_text_file' as the successor.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs the agent to avoid this tool when possible: 'DEPRECATED: Use read_text_file instead.' This directly tells when not to use it and provides a named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It states it's a listing operation (read-only) and works only within allowed directories. However, it does not disclose recursion behavior, performance implications, or whether sizes include subdirectories. Adequate but not rich.
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 sentences, front-loaded with the main action. No unnecessary words. Each sentence adds value.
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?
The description covers the basic purpose and a use case, but given no output schema, it lacks details on return format (beyond prefixes), whether subdirectories are included recursively, and how errors are handled. Adequate but not fully complete.
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?
Schema coverage is 50% (sortBy has description, path does not). The description does not add meaning to parameters: it mentions 'specified path' but no format or constraints, and does not explain sortBy options. It fails to compensate for low 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 tool lists files and directories with sizes, using [FILE] and [DIR] prefixes. It distinguishes from siblings like fs__list_directory which likely lacks sizes, fulfilling 'specific verb+resource'.
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 a use case: 'useful for understanding directory structure and finding specific files'. It provides context but does not explicitly exclude alternatives or mention when not to use it, lacking explicit when/when-not guidance.
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?
With no annotations provided, the description carries the full burden. It discloses key behaviors: complete overwrite without warning, text encoding handling, and restriction to allowed directories. This is adequate for a write operation.
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 three concise sentences. The first states the core purpose, the second adds a critical caution, and the third specifies constraints. No unnecessary words.
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 simple write tool, the description covers purpose, caution, encoding, and scope. It lacks details like whether parent directories are created (unlikely given sibling fs__create_directory), but is largely complete.
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 mentions 'text content with proper encoding' for the content parameter, adding some semantics beyond the schema. However, the path parameter is not elaborated, and schema coverage is 0%, so the description partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new file or overwrites an existing one. It implicitly distinguishes from siblings like fs__edit_file (partial modification) and fs__read_file, but does not explicitly differentiate.
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 advises caution due to overwriting without warning, implying use cases for file creation/replacement. However, it does not specify when not to use it (e.g., for appending) or mention alternative tools like fs__edit_file.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior fully. It states the tool returns metadata like size, times, permissions, and type, implying a read-only operation. It does not explicitly confirm no side effects or discuss authentication/rate limits, but the description is adequate for a simple info retrieval tool.
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?
Two sentences efficiently convey the core action, return data, use case, and constraint. The description is front-loaded with the main verb and resource, and every sentence adds value without wordiness.
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 a single parameter and no output schema, the description covers purpose, behavior, and constraints adequately. It could mention return format or error states, but the tool is simple enough that the provided information is mostly complete for an agent.
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 schema has one parameter 'path' with no description (0% coverage). The tool description does not explain the path format, absolute/relative expectations, or examples. It only mentions 'works within allowed directories,' which does not fully compensate for the lack of parameter guidance.
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 retrieves detailed metadata for files or directories, using the verb 'Retrieve' and specifying the resource. It differentiates from siblings like fs__read_file (content reading) and fs__list_directory (listing), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates when to use: 'perfect for understanding file characteristics without reading the actual content.' It also notes a constraint: 'Only works within allowed directories.' However, it does not explicitly mention when not to use or list alternative tools, but the context implies it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a read-only operation by stating it 'returns' a list, and mentions that subdirectories are accessible. No annotations are provided, so the description carries the full burden. It does not disclose details like authentication or rate limits, but for a simple listing tool, it is adequate.
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 with the core purpose first and additional context second. No unnecessary words.
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?
The description covers the tool's purpose and usage context. The missing output schema means the return format is not specified, but for this simple tool the description is largely complete.
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 tool has no parameters, so the input schema is trivially covered. Per guidelines, 0 parameters yields a baseline of 4. The description adds no parameter information, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a list of allowed directories, including subdirectories. It does not explicitly differentiate from siblings like fs__list_directory, but the unique resource 'allowed directories' makes the purpose distinct.
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 advises using this tool 'before trying to access files' to understand accessible paths. This provides clear context, though it does not mention when not to use it or suggest alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist; description carries full burden. Discloses failure on existing destination and allowed directory constraint. Does not mention atomization or side effects, but sufficient for a file move tool.
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?
Four concise sentences, no redundancy. Front-loaded with verb and object, each sentence adds distinct 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?
Covers purpose, constraints, and failure condition. Lacks return value details (no output schema), but acceptable for a simple operation.
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 has 0% description coverage; description adds meaning by stating 'both source and destination must be within allowed directories.' No format details, but provides necessary constraint.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool moves/renames files and directories. Differentiates between move (cross-directory) and rename (same directory). Distinct from sibling tools like read, write, create directory.
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?
Provides context for when to use: it can move or rename in one operation, fails if destination exists, and requires both paths within allowed directories. Lacks explicit alternatives but implies usage for relocation.
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?
With no annotations, the description discloses key behaviors: failure tolerance ('Failed reads... won't stop the entire operation'), return structure ('Each file's content is returned with its path'), and permission constraint ('Only works within allowed directories'). It lacks details on concurrency or max file limits but is otherwise transparent.
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 four sentences, front-loaded with the primary action, and each sentence adds distinct value: purpose, efficiency, return format, failure handling, and constraint. No repetition or unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately covers the output format and error handling. It provides usage context and constraints. However, it misses potential limits (max files, max size) and whether reading is sequential or parallel, which would improve completeness.
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 description coverage is 100% as the input schema fully describes the 'paths' parameter. The tool description does not add new parameter-level semantics beyond reiterating 'allowed directories' and failure handling. Per guidelines, baseline is 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reads multiple files simultaneously, highlights efficiency for analyzing/comparing multiple files, and distinguishes itself from sibling tools like fs__read_file which read single files. The verb 'read' and resource 'multiple files' are specific.
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 it is more efficient than reading files one by one and that failed reads won't stop the operation, guiding agents to use it when handling multiple files or tolerance for failures. However, it does not explicitly state when not to use it (e.g., for single file use fs__read_file).
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?
Describes recursion, full path returns, glob patterns, and allowed directory restriction. No annotations exist, so description carries full burden; missing performance or error handling but adequate.
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?
Four focused sentences, front-loaded with main action, no fluff. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema or annotations, description covers core search behavior. Could detail return format or limitations, but sufficiently complete for a search tool.
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 has no descriptions (0% coverage). Description explains pattern well but does not clarify path (starting directory) or excludePatterns, leaving gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it recursively searches files/directories matching a glob pattern, distinguishing it from sibling tools like reading or listing directories.
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?
Provides pattern examples and recommends use when exact location unknown. Lacks explicit when-not-to-use or alternatives, but gives sufficient context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses text encoding handling, detailed error messages, and that it operates on text regardless of extension. Does not mention file size limits or locking, but sufficient for a read-only tool.
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?
Five sentences, front-loaded with main purpose. Clear and organized, though could be slightly more concise by merging some sentences. No unnecessary fluff.
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?
No output schema, so description does not specify return format. However, it mentions 'complete contents' and 'detailed error messages', which is typical for read tools. Additional info on success/error structure would improve completeness, but acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% (head and tail have descriptions, path does not). Description adds meaning: head/tail read first/last N lines. Path description missing but inferred from context. Schema already provides basic info, and description compensates partially.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Read the complete contents of a file from the file system as text', specifying verb, resource, and modality. It distinguishes from siblings like fs__read_file (binary) and fs__read_multiple_files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this tool when you need to examine the contents of a single file' and explains head/tail usage. Mentions allowed directories constraint. Could briefly differentiate from fs__read_file or fs__read_media_file, but still clear.
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?
Discloses idempotent behavior (silent if exists), nested creation, and allowed directories. Lacks permission or failure details, which is acceptable for a simple creation tool.
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 sentences, front-loaded with primary action. 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?
Fully covers tool use case, behavior, and constraints. No output schema needed; return value is implicit.
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?
Only parameter 'path' is described in context (nested creation, path within allowed dirs). Adds meaning beyond schema, which only specifies type 'string'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'create' and resource 'directory', includes details like nested creation and silent success. Distinguishes from file-writing siblings.
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?
Provides explicit use case ('setting up directory structures') and constraint ('only within allowed directories'). No negative guidance or sibling alternatives, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

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

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

Card Badge

Copy to your README.md:

[![better-mcp MCP server](https://glama.ai/mcp/servers/qelos-io/better-mcp/badges/card.svg)](https://glama.ai/mcp/servers/qelos-io/better-mcp)

Score Badge

Copy to your README.md:

[![better-mcp MCP server](https://glama.ai/mcp/servers/qelos-io/better-mcp/badges/score.svg)](https://glama.ai/mcp/servers/qelos-io/better-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/qelos-io/better-mcp'

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