filesystem-mcp

• create

  554354A4.4

  The description is well-crafted, clearly stating the tool's purpose and usage guidelines, including when to use alternatives. It adds valuable behavioral context beyond the annotations, such as parent directory creation and overwrite confirmation. The schema covers all parameters, so the description doesn't need to add much, but it does so effectively. The only minor gap is not explicitly mentioning the file-size limit, but that is in the schema. Overall, this is a high-quality description that would help an agent select and invoke the tool correctly.

  5

  Purpose Clarity · 25%The description clearly states the tool's purpose: 'Write whole text files (create new ones, overwrite, or append) or make empty directories.' It uses specific verbs (write, create, overwrite, append) and identifies the resources (files, directories). It also distinguishes from siblings by explicitly mentioning 'Use edit or patch to change part of a file,' which differentiates it from those tools.

  5

  Usage Guidelines · 20%The description provides explicit guidance on when to use this tool versus alternatives: 'Use edit or patch to change part of a file.' It also explains the behavior for overwriting existing files, including the need for 'overwrite: true or the user's confirmation,' which is a clear usage condition. This is more than just context; it gives actionable when-to-use and when-not-to-use instructions.

  4

  Behavioral Transparency · 20%The annotations already declare destructiveHint=true, so the description doesn't need to repeat that. However, it adds valuable behavioral details beyond the annotations: 'Missing parent directories are created' and 'Replacing an existing file needs overwrite: true or the user's confirmation.' It also explains the append behavior implicitly. The only minor gap is not detailing the exact behavior when a file exists without overwrite (e.g., the prompt), but the schema covers that. This is strong transparency for a destructive tool.

  3

  Parameter Semantics · 15%The schema description coverage is 100%, so the schema already documents all parameters (files, directories, and their properties). The description adds some context by mentioning 'Missing parent directories are created' and 'append' behavior, but it doesn't go beyond what the schema already states. For example, the schema already explains 'append' and 'overwrite' in detail. Thus, the description adds minimal extra value, but it doesn't need to compensate for any gaps, so a baseline 3 is appropriate.

  5

  Conciseness & Structure · 10%The description is concise and front-loaded. The first sentence immediately states the core purpose, followed by a key behavior (missing parent directories) and a critical constraint (overwrite requirement). The final sentence directs to alternatives. Every sentence earns its place, with no fluff or repetition. It is well-structured for quick scanning.

  4

  Contextual Completeness · 10%Given the tool's complexity (multiple modes: create, overwrite, append, directories) and the rich schema (100% coverage), the description is quite complete. It covers the main operations, the overwrite confirmation requirement, and the alternative tools. It doesn't explain return values, but there is no output schema, so that is not required. The only minor omission is not explicitly stating the file-size limit, but that is in the schema. Overall, it is sufficient for an agent to use the tool correctly.

  params

  2 (0 required, 100% described)

  annotations

  readOnly=false destructive=true openWorld=false

  output schema

  no

  cost

  0

  bytes

  1685

  hash

  92a3c6187aa683ba

• delete

  554354A4.4

  The description is well-crafted, clearly explaining the tool's purpose, usage constraints, and alternatives. It complements the annotations and schema effectively, providing necessary behavioral context for a destructive operation. Minor gaps exist in return value details, but overall it is a strong, concise description.

  5

  Purpose Clarity · 25%The description clearly states the tool deletes files, directories, or symlinks, analogous to rm or rm -r, and distinguishes it from move for relocation. It also specifies exact paths and no glob expansion, which is specific and unambiguous.

  5

  Usage Guidelines · 20%The description explicitly explains when to use this tool (delete) versus alternatives: 'Use move to relocate a path instead.' It also provides conditions for recursive deletion and mentions undo for reverting deletes, giving clear usage context.

  4

  Behavioral Transparency · 20%Annotations already declare destructiveHint=true, so the description doesn't need to restate destructiveness. It adds valuable context: exact paths, no glob expansion, recursive requirement, user confirmation for non-empty directories, and undo id availability. This goes beyond annotations, though it could mention permission requirements or irreversibility, but the undo mention helps.

  3

  Parameter Semantics · 15%Schema description coverage is 100%, so the schema already documents all parameters. The description adds context about recursive behavior and confirmation, but it doesn't add much beyond the schema's detailed parameter descriptions. Baseline 3 is appropriate.

  5

  Conciseness & Structure · 10%The description is concise, with three sentences covering purpose, constraints, and alternatives. It is front-loaded with the core action and includes no fluff. Every sentence adds value.

  4

  Contextual Completeness · 10%Given the tool's complexity (destructive, recursive, confirmation), the description covers key aspects: exact paths, recursive requirement, confirmation, undo, and move alternative. It lacks details on return values or error handling, but no output schema exists and the description is sufficient for a destructive tool with good annotations.

  params

  3 (1 required, 100% described)

  annotations

  readOnly=false destructive=true openWorld=false

  output schema

  no

  cost

  1

  bytes

  1289

  hash

  c624422e28d52440

• diff

  544354A4.2

  The description is clear, concise, and provides valuable behavioral transparency beyond the annotations, covering edge cases like binary files and TOO_LARGE. It effectively distinguishes itself from sibling tools and leverages the schema for parameter details, making it a well-rounded tool definition.

  5

  Purpose Clarity · 25%The description clearly states the tool compares two text files and returns a unified diff, using the analogy 'like diff -u' which is immediately understandable. It distinguishes itself from siblings by focusing on comparison rather than file manipulation (create, delete, edit, etc.).

  4

  Usage Guidelines · 20%The description implies usage for comparing two files, and the 'like diff -u' analogy provides clear context. It does not explicitly state when not to use it or mention alternatives, but the sibling list shows other tools for different operations, making the purpose distinct enough.

  4

  Behavioral Transparency · 20%The description discloses key behaviors: identical files produce no hunks, binary and non-UTF-8 files are refused, and files too different give TOO_LARGE. This goes beyond the readOnlyHint annotation, which only indicates safety, and provides important edge-case handling information.

  3

  Parameter Semantics · 15%The schema already provides 100% coverage with descriptions for all parameters (a, b, context). The description adds no additional parameter-specific meaning beyond what the schema states, so the baseline of 3 is appropriate.

  5

  Conciseness & Structure · 10%The description is a single, concise sentence that packs in the core purpose and key behavioral notes without any fluff. It is front-loaded with the main action and uses the 'diff -u' analogy for immediate clarity.

  4

  Contextual Completeness · 10%Given the tool's simplicity, the description covers the essential behaviors (no hunks for identical, refusal for binary/non-UTF-8, TOO_LARGE for too different) and the schema documents parameters fully. It lacks details on return format, but the absence of an output schema and the tool's straightforward nature make this acceptable.

  params

  3 (2 required, 100% described)

  annotations

  readOnly=true openWorld=false

  output schema

  no

  cost

  2

  bytes

  800

  hash

  348459ee1f399786

• edit

  554454A4.6

  This is a well-crafted description that clearly explains the tool's purpose, usage constraints, and behavioral nuances. It effectively differentiates from sibling tools and provides actionable guidance for an AI agent. The only minor gap is a lack of detail on error handling in batch mode, but overall it scores high across all dimensions.

  5

  Purpose Clarity · 25%The description clearly states the tool edits text files by replacing exact oldText with newText, analogous to str_replace. It distinguishes itself from siblings by explicitly mentioning replace_text for every occurrence and create for new files, and the title 'Edit Files' aligns with the description.

  5

  Usage Guidelines · 20%The description provides explicit usage guidance: pass path with edits or files for batch, never both; each oldText must match exactly once; dryRun previews; undo reverts. It also names alternatives (replace_text, create) for different scenarios, making it clear when to use this tool versus others.

  4

  Behavioral Transparency · 20%Annotations already indicate destructiveHint=true, so the description doesn't need to restate that. It adds valuable behavioral details: atomicity per file (file written only if all edits match), batch files succeed/fail separately, dryRun and undo options, and the exact-match requirement. This goes beyond annotations, though it could mention permission requirements or side effects, but given the annotations, a 4 is appropriate.

  4

  Parameter Semantics · 15%Schema description coverage is 100%, so the schema already documents all parameters. The description adds key semantics: the mutual exclusivity of path/edits vs files, the exact-match-once rule, and the dryRun/undo behavior. It also clarifies that oldText should include context, which is not fully in the schema. This adds value beyond the schema, justifying a 4.

  5

  Conciseness & Structure · 10%The description is concise, with each sentence serving a purpose. It front-loads the core action, then covers usage modes, constraints, and alternatives in a logical order. No fluff or redundancy; every sentence adds critical information.

  4

  Contextual Completeness · 10%Given the tool's complexity (batch mode, atomicity, dryRun, undo) and the absence of an output schema, the description covers the essential behaviors well. It explains failure modes (exact match, per-file success) and provides alternatives. It could mention what happens on partial batch failure or how undo works in more detail, but the description is largely complete for an agent to use it correctly.

  params

  5 (0 required, 100% described)

  annotations

  readOnly=false destructive=true openWorld=false

  output schema

  no

  cost

  0

  bytes

  2848

  hash

  0cce8887f58b2838

• list

  554454A4.6

  This is a well-crafted description that clearly defines the tool's purpose, differentiates it from siblings, and provides rich usage guidelines. It effectively leverages the 100% schema coverage while adding context about default behavior for hidden/ignored files and pagination. Slight room for improvement in describing output structure, but overall high quality.

  5

  Purpose Clarity · 25%The description clearly states it lists a directory's files and subdirectories as a tree, like ls or tree, which is a specific verb and resource. It distinguishes itself from siblings by mentioning find_files and read as alternatives.

  5

  Usage Guidelines · 20%The description explicitly mentions usage contexts: it lists files/dirs, and says 'find_files searches by name pattern; read returns file contents' to differentiate. It also implies when to use includeHidden and includeIgnored for special cases.

  4

  Behavioral Transparency · 20%Annotations indicate readOnlyHint=true, which aligns with the description's listing functionality. The description adds details about hidden/ignored entries being skipped by default, pagination cursor expiration, and maxDepth behavior, going beyond annotations. It doesn't describe output format details, but with readOnlyHint already covering safety, this is sufficient.

  4

  Parameter Semantics · 15%Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the default one-level depth and the distinction between hidden and ignored entries, clarifying the path parameter's default from context. It also mentions cursor expiration, which enriches the cursor parameter meaning.

  5

  Conciseness & Structure · 10%The description is a single paragraph but efficiently packs necessary details: purpose, timestamps, depth, hidden/ignored handling, and alternative tools. Every sentence adds value, and it's front-loaded with the core purpose.

  4

  Contextual Completeness · 10%With 8 parameters, 100% schema coverage, and good annotations, the description is fairly complete. It covers pagination, filtering, sorting, and alternatives. It doesn't specify return format, but no output schema exists, so it could be more explicit about what the tree output looks like (e.g., exact structure), slight gap.

  params

  8 (0 required, 100% described)

  annotations

  readOnly=true openWorld=false

  output schema

  no

  cost

  0

  bytes

  1944

  hash

  1a02e51df1cfdeed

• move

  554354A4.4

  The description is well-crafted, providing clear purpose, usage guidance, and behavioral transparency. It effectively distinguishes itself from sibling tools and covers edge cases. Minor gap: no mention of return values, but overall it is a high-quality description.

  5

  Purpose Clarity · 25%The description clearly states the tool moves, renames, or copies files and directories, analogous to mv or cp -r. It distinguishes itself from siblings like delete and undo by explicitly mentioning 'Use delete to remove a path' and noting undo behavior.

  5

  Usage Guidelines · 20%The description provides explicit guidance on when to use this tool versus alternatives: it mentions using delete for removal and describes undo for reverting operations. It also clarifies the semantics of destination paths and overwrite behavior, which helps the agent decide when to use this tool.

  4

  Behavioral Transparency · 20%Annotations already indicate destructiveHint=true, and the description adds important behavioral details: missing parent directories are created, overwrite only applies to copies, moves onto existing files prompt, and moves onto non-empty directories are refused. It also mentions undo id generation, which is not in annotations. No contradiction with annotations.

  3

  Parameter Semantics · 15%Schema description coverage is 100%, so the schema already documents all parameters. The description adds context about destination path semantics (full new path, not folder) and overwrite behavior, but does not add much beyond what the schema provides. Baseline 3 is appropriate.

  5

  Conciseness & Structure · 10%The description is concise, with three sentences covering purpose, key behaviors, and alternatives. It is front-loaded with the main action and uses clear analogies. No wasted words.

  4

  Contextual Completeness · 10%Given the tool's complexity (multiple modes, edge cases) and the absence of an output schema, the description covers essential behaviors: destination semantics, overwrite rules, undo, and deletion alternative. It could mention return values or error handling, but the description is sufficient for an agent to use the tool correctly.

  params

  3 (1 required, 100% described)

  annotations

  readOnly=false destructive=true openWorld=false

  output schema

  no

  cost

  5

  bytes

  1379

  hash

  8c69d19916a62174

• patch

  554354A4.4

  The description is well-crafted, providing clear purpose, usage guidance, and behavioral transparency that complements the annotations. It effectively distinguishes itself from sibling tools like edit and explains critical matching behavior. Minor gaps in parameter semantics are offset by the high schema coverage, making this a strong, agent-friendly tool definition.

  5

  Purpose Clarity · 25%The description clearly states the tool applies a single-file unified diff to an existing text file, using the analogy 'like git apply' for immediate understanding. It distinguishes itself from siblings by explicitly contrasting with 'edit' for exact replacements, and the verb 'apply' plus resource 'single-file unified diff' is specific.

  5

  Usage Guidelines · 20%The description provides explicit guidance on when to use this tool: for applying diffs with exact context matching, and when not to use it: 'edit suits a few exact replacements.' It also explains the dryRun option for previewing without writing, giving clear context for choosing this tool over alternatives like edit or replace_text.

  4

  Behavioral Transparency · 20%Annotations already indicate destructiveHint=true, so the description's mention of 'Nothing is written unless every hunk applies' adds valuable safety context. It also discloses that hunks are found by context, so start line numbers may be off, which is critical behavioral information not covered by annotations. The dryRun behavior is also disclosed, adding transparency beyond the schema.

  3

  Parameter Semantics · 15%Schema description coverage is 100%, so the schema already documents all three parameters (path, diff, dryRun) with clear descriptions. The description adds minimal extra meaning beyond the schema, but it does clarify that the diff should be a single-file unified diff and that dryRun checks without writing, which slightly enhances understanding. Baseline 3 is appropriate.

  5

  Conciseness & Structure · 10%The description is concise, with three sentences that each add value: the first explains the core function and safety, the second explains the matching behavior, and the third covers dryRun and alternative. It is front-loaded with the primary purpose and avoids any fluff.

  4

  Contextual Completeness · 10%Given the tool's moderate complexity (3 params, no output schema), the description covers the essential aspects: what it does, safety guarantees, matching behavior, and dryRun. It could mention error handling or return values, but the lack of output schema and the clear safety disclosure make it sufficiently complete for an agent to use correctly.

  params

  3 (2 required, 100% described)

  annotations

  readOnly=false destructive=true openWorld=false

  output schema

  no

  cost

  2

  bytes

  976

  hash

  3fc66ca3084307ee

• read

  554455A4.7

  This is an excellent tool description that clearly explains the tool's purpose, usage guidelines, and behavioral nuances. It effectively complements the rich schema and annotations, providing actionable guidance for an AI agent. The description is concise yet comprehensive, making it a top-tier example.

  5

  Purpose Clarity · 25%The description clearly states the tool reads text files, like cat, with options for whole or slices via head/tail/startLine/endLine. It distinguishes from siblings by mentioning search_text for finding text and list for directories, and the name 'read' is unambiguous.

  5

  Usage Guidelines · 20%The description explicitly says when to use this tool (read files) and when not to (use search_text for finding text, list for directories). It also provides guidance on batch vs single path, binary handling, and slice vs whole file trade-offs, which helps the agent choose correctly.

  4

  Behavioral Transparency · 20%Annotations already declare readOnlyHint=true, so the description doesn't need to repeat that. It adds valuable behavioral context: images/audio return as media, binary:true for other binary files, large results may exceed inline display, and stat gives tokenEstimate. It also notes that slices cost less than whole files, which is useful for resource management. No contradiction with annotations.

  4

  Parameter Semantics · 15%Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the relationship between parameters (e.g., 'pass path, or paths for a batch, not both', 'binary: true to get any other binary file whole', 'a slice costs less than a whole file'). It also clarifies that lineNumbers is not with tail, which is not in the schema. This adds value, so a 4 is appropriate.

  5

  Conciseness & Structure · 10%The description is concise, front-loaded with the core purpose, and every sentence adds value. It covers key usage patterns, binary handling, and performance considerations without redundancy. It is well-structured and easy to parse.

  5

  Contextual Completeness · 10%Given the tool's complexity (9 parameters, no output schema), the description is remarkably complete. It covers all major usage modes, edge cases (binary, batch, slices), and provides guidance on performance and alternatives. The lack of output schema is compensated by mentioning stat for tokenEstimate and the behavior of media returns. This is a comprehensive description for a complex tool.

  params

  9 (0 required, 100% described)

  annotations

  readOnly=true openWorld=false

  output schema

  no

  cost

  0

  bytes

  1989

  hash

  d4b9e5e0e95b94e4

• replace_text

  554455A4.7

  This is an exemplary tool description that clearly defines its purpose, provides explicit usage guidance, and transparently discloses its destructive nature with safety mechanisms. It adds significant value beyond the schema and annotations, making it highly effective for an AI agent to select and invoke correctly.

  5

  Purpose Clarity · 25%The description clearly states the tool performs find-and-replace operations on literal text or RE2 regex, similar to sed -i, across files or directories. It distinguishes itself from siblings like edit (for one unique exact match) and search_text (for searching only), making its purpose specific and non-overlapping.

  5

  Usage Guidelines · 20%The description provides explicit guidance on when to use this tool versus alternatives: 'Use edit for one unique exact match' and mentions previewing with dryRun and reverting with undo. It also advises scoping wide paths deliberately and pairing with dryRun, which is clear usage context.

  4

  Behavioral Transparency · 20%Annotations indicate destructiveHint=true, and the description reinforces this by mentioning 'revert with undo' and 'preview wide scopes with dryRun'. It also discloses that directory runs stop near 100 matches and that maxMatches sets a strict cap, adding behavioral context beyond the annotations. However, it doesn't detail what happens to files on error or partial writes, but the core destructive nature is well covered.

  4

  Parameter Semantics · 15%Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the pattern runs over the whole file (spanning lines) and that ^ and $ anchor to file start/end, which is not in the schema. It also clarifies the interaction between caseSensitive and search_text's case-insensitivity, which is a subtle semantic not obvious from the schema alone.

  5

  Conciseness & Structure · 10%The description is concise, front-loaded with the core action, and every sentence adds value. It covers key behaviors, usage guidance, and safety tips without redundancy. The structure is efficient, with no wasted words.

  5

  Contextual Completeness · 10%Given the tool's complexity (14 parameters, destructive, no output schema), the description is remarkably complete. It covers scope, regex behavior, safety (dryRun, undo), limits (maxMatches), and alternatives. The schema covers parameter details, and the description fills in behavioral and usage gaps, making it sufficient for an agent to use correctly.

  params

  14 (2 required, 100% described)

  annotations

  readOnly=false destructive=true openWorld=false

  output schema

  no

  cost

  2

  bytes

  3124

  hash

  36dc97d51e6af41e

• list_roots

  554455A4.7

  This is a well-crafted description for a simple discovery tool. It clearly states the purpose, provides explicit usage guidance, and adds behavioral context beyond the annotations. With zero parameters, it leverages the description to explain the output and implications, making it highly effective for agent selection and invocation.

  5

  Purpose Clarity · 25%The description clearly states the tool lists directories the server can access as absolute paths, including session-granted ones. It distinguishes itself from siblings by focusing on root directories, not file operations like read or edit.

  5

  Usage Guidelines · 20%Explicitly instructs to call it first when path locations are unknown, and mentions that other tools can request user grants for paths outside these roots. This provides clear when-to-use guidance and context for alternatives.

  4

  Behavioral Transparency · 20%Annotations already declare readOnlyHint=true and openWorldHint=false, so the description adds value by explaining that read-only directories are listed in readOnlyDirs and that writes/moves/deletes under them are refused. It also notes session-granted paths are included, which is beyond the annotations.

  4

  Parameter Semantics · 15%The tool has zero parameters, so the description doesn't need to explain parameter semantics. The baseline for 0 params is 4, and the description appropriately focuses on the output and usage context.

  5

  Conciseness & Structure · 10%The description is three sentences, each adding essential information: what is listed, when to call, and read-only behavior. No fluff, front-loaded with the core purpose.

  5

  Contextual Completeness · 10%Given the tool has no parameters and no output schema, the description fully covers what the agent needs: the content of the response (absolute paths, readOnlyDirs), the timing (call first), and the implications (refusals, user grants). It is complete for its simplicity.

  params

  0 (0 required, 100% described)

  annotations

  readOnly=true openWorld=false

  output schema

  no

  cost

  0

  bytes

  622

  hash

  35f3e1b511715764

• search_text

  544444A4.3

  The description is well-crafted, clearly stating the tool's purpose and distinguishing it from a sibling. It provides essential behavioral transparency around pagination and output, complements the schema without redundancy, and is concise. Minor gaps include limited usage exclusions and a few redundant sentences, but overall it is a strong, effective description.

  5

  Purpose Clarity · 25%The description clearly states the purpose: 'Search file contents for literal text or an RE2 regex, like grep.' It specifies the resource (file contents) and the action (search), and distinguishes itself from find_files ('find_files matches file names') and other file tools. The mention of 'like grep' and the explicit alternative make it highly clear.

  4

  Usage Guidelines · 20%The description provides clear context on when to use this tool (search file contents) and explicitly differentiates from find_files ('find_files matches file names'). However, it does not explicitly state when not to use it or mention alternative scenarios (e.g., when to use read or list). There is a clear usage directive: pass the cursor for next page. Exclusions are implied but not exhaustive.

  4

  Behavioral Transparency · 20%The description goes beyond the readOnlyHint annotation by explaining output format (matching lines with line numbers and paths), the header behavior for named files, pagination semantics (cursor, snapshot expiration), and replacement case behavior. It does not contradict the readOnlyHint. Given the annotation, the description adds useful behavioral context, though it doesn't mention potential performance or rate limits.

  4

  Parameter Semantics · 15%The schema covers 100% of parameters, so baseline is 3. The description adds value by summarizing searchPattern ('text to find, matched within one line') and pattern ('filters files by glob'), and by noting that naming a file ignores pattern and hidden/ignored filtering. This enriches the meaning beyond the schema, but not extensively — it doesn't detail all parameter interactions, but it's sufficient.

  4

  Conciseness & Structure · 10%The description is moderately concise, with a clear first sentence stating the core function. It front-loads the key information and includes an explicit sibling distinction. However, it contains some redundancy with the schema (e.g., 'searchPattern is the text to find') and could be slightly tightened, but overall it is well-structured and not bloated.

  4

  Contextual Completeness · 10%Given the tool's complexity (11 parameters, pagination, regex, globbing), the description covers the essential behavioral details: output format, pagination, alternative tool, and note about named file behavior. With no output schema, it explains the return value sufficiently. The absence of details on specific parameter defaults (covered by schema) and the lack of comprehensive edge cases are acceptable, but there is room for more depth on path handling or regex limitations.

  params

  11 (1 required, 100% described)

  annotations

  readOnly=true openWorld=false

  output schema

  no

  cost

  1

  bytes

  2688

  hash

  011294ae96637bab

• find_files

  554454A4.6

  The description is highly effective, clearly stating the tool's purpose, usage guidelines, and key behavioral nuances while differentiating it from siblings. It complements the schema well, adding value without redundancy. Minor gaps exist in not explicitly stating pagination defaults, but overall it is a strong example of a well-crafted tool description.

  5

  Purpose Clarity · 25%The description clearly states the tool finds files by name or glob pattern, analogous to the Unix 'find' command. It distinguishes itself from siblings by explicitly mentioning 'list browses directories; search_text searches contents', which differentiates it from those tools.

  5

  Usage Guidelines · 20%The description provides explicit guidance on when to use this tool versus alternatives: it notes that 'list browses directories; search_text searches contents', and also mentions that 'read accepts either form' of paths, implying integration with other tools. It also explains the default behavior of skipping hidden and ignored files, which is a key usage consideration.

  4

  Behavioral Transparency · 20%The description adds significant behavioral context beyond the readOnlyHint annotation: it explains that hidden and ignored files are skipped by default, that patterns without '/' match at any depth, and that pagination uses a cursor that expires after ~60 seconds. While the annotation already indicates read-only, the description enriches the agent's understanding of the tool's behavior, though it could mention that results are returned in pages and the default page size.

  4

  Parameter Semantics · 15%The schema already provides detailed descriptions for all parameters (100% coverage), so the description doesn't need to repeat them. However, the description adds value by explaining the semantics of the pattern parameter (e.g., 'A pattern without / matches file names at any depth') and the cursor's behavior, which are not fully captured in the schema. This goes beyond the baseline of 3.

  5

  Conciseness & Structure · 10%The description is concise and front-loaded: it starts with the core purpose, then covers key behaviors, and ends with sibling differentiation. Every sentence adds value, and it avoids redundancy with the schema. It is well-structured for quick scanning.

  4

  Contextual Completeness · 10%Given the tool's complexity (8 parameters, pagination, glob patterns) and the absence of an output schema, the description covers the essential aspects: path handling, pattern matching, hidden/ignored defaults, and pagination. It could be more complete by mentioning the default maxResults and the fact that results are paginated, but the schema covers those details. The description is sufficient for an agent to use the tool effectively.

  params

  8 (1 required, 100% described)

  annotations

  readOnly=true openWorld=false

  output schema

  no

  cost

  1

  bytes

  1834

  hash

  a1c490a6e06d2266

• stat

  554344A4.3

  This is a well-crafted description that clearly explains the tool's purpose, usage, and behavioral nuances, distinguishing it from siblings. It leverages the readOnlyHint annotation and adds valuable context about return fields and platform-specific behavior. The only minor weakness is that parameter semantics are largely covered by the schema, but the description still adds useful batch-mode and existence-checking details. Overall, it is a high-quality description that would help an agent select and invoke the tool correctly.

  5

  Purpose Clarity · 25%The description clearly states the tool's purpose: 'Get metadata without reading contents, like ls -ld.' It specifies the resource (files/directories) and the action (stat), and distinguishes it from siblings like 'read' and 'list' by explicitly noting that it does not read contents and that 'read returns contents; list lists a directory.'

  5

  Usage Guidelines · 20%The description provides explicit usage guidance: it explains when to use this tool (to get metadata without reading contents), and contrasts with alternatives ('read returns contents; list lists a directory'). It also clarifies the batch mode and the mutual exclusivity of 'path' and 'paths', and notes that stat can be used to check existence because missing paths get NOT_FOUND entries.

  4

  Behavioral Transparency · 20%Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds valuable behavioral details beyond annotations: it explains that directories return entryCount (excluding secret files), that permissions may be readOnly on Windows, that MIME type is guessed from extension, and that on Windows a rewrite resets created unless hard links exist. This is rich context that helps the agent understand side effects and edge cases.

  3

  Parameter Semantics · 15%Schema description coverage is 100%, so the schema already documents both parameters (path and paths) with descriptions and mutual exclusivity. The description adds a bit of extra meaning by explaining batch mode and the NOT_FOUND behavior, but it does not add significant new parameter-level semantics beyond what the schema provides. Baseline 3 is appropriate.

  4

  Conciseness & Structure · 10%The description is concise and front-loaded with the core purpose. It packs a lot of useful information into a few sentences, but it is slightly dense and could be better structured with bullet points for the fields and behaviors. However, every sentence earns its place, and there is no fluff.

  4

  Contextual Completeness · 10%Given the tool's moderate complexity (two parameters, batch mode, multiple return fields, platform-specific behavior), the description is quite complete. It covers the return fields, the existence-checking behavior, and platform nuances. There is no output schema, so the description carries the burden of explaining return values, which it does well. Minor gaps: it doesn't explicitly state the return format (e.g., JSON structure) or how errors are represented beyond NOT_FOUND, but it is sufficient for an agent to use the tool effectively.

  params

  2 (0 required, 100% described)

  annotations

  readOnly=true openWorld=false

  output schema

  no

  cost

  0

  bytes

  1162

  hash

  f4b65afd16faa372

• undo

  544454A4.4

  The description is well-crafted, providing clear purpose, usage constraints, and behavioral details that complement the annotations. It effectively guides the agent on when and how to use the tool, with no contradictions. Minor gaps exist in explicit alternative tool references, but overall it is a strong description.

  5

  Purpose Clarity · 25%The description clearly states the tool reverts earlier calls that changed files, specifying two modes (by undo id or last N steps) and the constraint that they cannot be used together. It distinguishes itself from siblings like delete and edit by focusing on reverting previous operations, not direct file changes.

  4

  Usage Guidelines · 20%The description provides clear context on when to use the tool (to revert changes) and includes important exclusions: 'not both' for id/steps, 'not over HTTP' for steps, and 'dryRun' for previewing. It does not explicitly name alternative tools for reverting, but the context is sufficient for an agent to decide.

  4

  Behavioral Transparency · 20%Annotations already declare destructiveHint=true, and the description adds valuable behavioral details: a file is restored only if unchanged since, results list file outcomes, and large undos are cut short. It also explains dryRun behavior in detail, including the caveat about previewing the whole history. This goes beyond the annotation's simple destructive flag.

  4

  Parameter Semantics · 15%Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining the relationship between id and steps (mutually exclusive), the HTTP restriction for steps, and the dryRun preview semantics, which are not fully captured in the schema descriptions. This adds value beyond the schema.

  5

  Conciseness & Structure · 10%The description is concise, with three sentences that cover the core functionality, constraints, and dryRun behavior. It is front-loaded with the main purpose and avoids redundancy. Every sentence adds value, and the structure is clear.

  4

  Contextual Completeness · 10%Given the tool's moderate complexity (3 params, no output schema, destructive action), the description covers the key aspects: usage modes, constraints, file restoration condition, result summary, and dryRun behavior. It does not detail the exact format of the result list, but that is acceptable without an output schema. The description is complete enough for an agent to use the tool correctly.

  params

  3 (0 required, 100% described)

  annotations

  readOnly=false destructive=true openWorld=false

  output schema

  no

  cost

  0

  bytes

  1028

  hash

  044645919b9b6912

• warningmove shadow-candidatemove (invocation cost 5) may be shadowed by delete (cost 1): if both can answer the same question, an agent tends toward the cheaper call. Only the coherence evaluation can confirm the purposes overlap; if they do, make them disjoint and say so in both descriptions, or collapse the pair.
• infocreate no-output-schemacreate has no output schema, so the description has to explain return values itself. Providing one lets the description spend those words elsewhere.
• infodelete no-output-schemadelete has no output schema, so the description has to explain return values itself. Providing one lets the description spend those words elsewhere.
• infodiff no-output-schemadiff has no output schema, so the description has to explain return values itself. Providing one lets the description spend those words elsewhere.
• infoedit no-output-schemaedit has no output schema, so the description has to explain return values itself. Providing one lets the description spend those words elsewhere.
• infolist no-output-schemalist has no output schema, so the description has to explain return values itself. Providing one lets the description spend those words elsewhere.
• infomove no-output-schemamove has no output schema, so the description has to explain return values itself. Providing one lets the description spend those words elsewhere.
• infopatch no-output-schemapatch has no output schema, so the description has to explain return values itself. Providing one lets the description spend those words elsewhere.
• inforead no-output-schemaread has no output schema, so the description has to explain return values itself. Providing one lets the description spend those words elsewhere.
• inforeplace_text no-output-schemareplace_text has no output schema, so the description has to explain return values itself. Providing one lets the description spend those words elsewhere.
• infolist_roots no-output-schemalist_roots has no output schema, so the description has to explain return values itself. Providing one lets the description spend those words elsewhere.
• infosearch_text no-output-schemasearch_text has no output schema, so the description has to explain return values itself. Providing one lets the description spend those words elsewhere.
• infofind_files no-output-schemafind_files has no output schema, so the description has to explain return values itself. Providing one lets the description spend those words elsewhere.
• infostat no-output-schemastat has no output schema, so the description has to explain return values itself. Providing one lets the description spend those words elsewhere.
• infoundo no-output-schemaundo has no output schema, so the description has to explain return values itself. Providing one lets the description spend those words elsewhere.

The badge shows the overall tier and score, and links here. The JSON is the same report the CLI's hosted mode prints.

[![TDQS](https://tdqs.dev/reports/zce37la3mf/badge.svg)](https://tdqs.dev/reports/zce37la3mf)

The same check from a terminal, a CI job or a script, with an API key from your account. Submitting spends one of the account's daily calls; reading the result spends nothing.

export TDQS_API_KEY=tdqs_...

# exit code 1 below B, so the command is the gate; uvx runs the same command from PyPI
npx mcp-tdqs score --file tools.json --hosted https://tdqs.dev --fail-under B

curl https://tdqs.dev/api/v1/reports \
  -H 'Authorization: Bearer tdqs_...' \
  -H 'Content-Type: application/json' \
  -d @tools.json

# poll the report it names until "status" is "completed"; this one is
curl https://tdqs.dev/api/v1/reports/zce37la3mf \
  -H 'Authorization: Bearer tdqs_...'

import { requestHostedReport } from 'mcp-tdqs';

const report = await requestHostedReport({
  apiKey: 'tdqs_...',
  hostedUrl: 'https://tdqs.dev',
  serverName: 'filesystem-mcp',
  tools, // the tools/list result
});

if (report.score === null || !['A', 'B'].includes(report.score.serverScore.overallTier)) {
  throw new Error(`TDQS ${report.score?.serverScore.overallTier ?? 'failed'}: ${report.url}`);
}

from tdqs import parse_tool_definitions, request_hosted_report

parsed = parse_tool_definitions(tools_list)  # the tools/list result
report = request_hosted_report(
    api_key="tdqs_...",
    hosted_url="https://tdqs.dev",
    server_name="filesystem-mcp",
    tools=parsed.tools,
)
tier = report.score.server_score.overall_tier if report.score is not None else None

if tier not in ("A", "B"):
    raise SystemExit(f"TDQS {tier or 'failed'}: {report.url}")