filesystem-mcp

• create

  554354A4.4

  The description is well-crafted, clearly stating the tool's purpose and usage guidelines, and effectively differentiating it from siblings. It leverages the schema for parameter details while adding behavioral context like overwrite confirmation and parent directory creation. Minor gaps in completeness are covered by the schema, making this a strong description overall.

  5

  Purpose Clarity · 25%The description clearly states the tool's purpose: writing whole text files (create, overwrite, append) and creating empty directories. It distinguishes from siblings by explicitly mentioning 'edit or patch' for partial changes, which differentiates it from those tools.

  5

  Usage Guidelines · 20%The description provides explicit guidance on when to use this tool (whole file operations) and when not to (use edit or patch for partial changes). It also explains the overwrite behavior and the need for user confirmation, which is crucial for correct usage.

  4

  Behavioral Transparency · 20%Annotations already indicate destructiveHint=true, so the description doesn't need to repeat that. It adds valuable context: missing parent directories are created, overwrite requires confirmation, and append behavior. It doesn't mention potential side effects like file size limits, but the schema covers that. No contradiction with annotations.

  3

  Parameter Semantics · 15%Schema description coverage is 100%, so the schema already documents all parameters. The description adds some context (e.g., 'overwrite: true or user's confirmation') but mostly reiterates what's in the schema. Baseline 3 is appropriate.

  5

  Conciseness & Structure · 10%The description is concise, with three sentences that each add value: purpose, behavior, and alternative tools. It is front-loaded with the main action and avoids redundancy.

  4

  Contextual Completeness · 10%Given the tool's complexity (multiple operations, overwrite logic, directory creation) and the rich schema, the description covers the key aspects. It doesn't explain return values, but there is no output schema, and the tool's side effects are clear. Slight gap: no mention of file size limits, but that's in the schema.

  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

  This is a well-crafted description that clearly defines the tool's purpose, provides explicit usage guidance, and adds behavioral context beyond the annotations. It is concise and complete, with only minor gaps in parameter semantics that are already covered by the schema. Overall, it scores high across all dimensions.

  5

  Purpose Clarity · 25%The description clearly states the tool deletes files, directories, or symlinks, analogous to rm or rm -r, and explicitly distinguishes it from move for relocation. It also specifies that paths are exact and globs are not expanded, which adds precision beyond the name.

  5

  Usage Guidelines · 20%The description provides explicit guidance on when to use this tool (for deletion) and when not to (use move to relocate instead). It also explains the requirement for recursive: true and user confirmation for non-empty directories, and mentions undo for reverting deletions, giving clear context for usage.

  4

  Behavioral Transparency · 20%Annotations already declare destructiveHint: true, so the destructive nature is known. The description adds valuable context: exact paths, no glob expansion, recursive deletion requires confirmation, and undo is possible via an undo id. It does not contradict annotations, and the added details go beyond what annotations provide.

  3

  Parameter Semantics · 15%The schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal extra parameter semantics, but it does clarify the recursive behavior and the need for confirmation, which is not fully explicit in the schema. Baseline 3 is appropriate.

  5

  Conciseness & Structure · 10%The description is concise, with three sentences that each add essential information: what it deletes, the recursive requirement, and the alternative to move. It is front-loaded with the core purpose and avoids redundancy.

  4

  Contextual Completeness · 10%Given the tool's complexity (handles files, directories, symlinks, recursive deletes, undo) and the rich schema, the description covers the key behaviors. It does not detail return values, but no output schema exists, and the description mentions undo ids, which is sufficient. Minor gap: it doesn't mention error handling for invalid paths beyond ignoreIfNotExists, but that is covered in the schema.

  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 highly effective: it clearly states the tool's purpose, adds useful behavioral details about edge cases, and is concise. It slightly lacks explicit usage guidelines but the context is clear from the sibling tools. Overall, it is a well-crafted description that scores high across all dimensions.

  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 also specifies the direction (from a to b) and distinguishes itself from siblings like 'read' or 'edit' by focusing on comparison rather than content access or modification.

  4

  Usage Guidelines · 20%The description implies when to use this tool: when you need to compare two text files and see differences. It does not explicitly mention alternatives or when not to use it, but the sibling list includes 'read' and 'edit' which are clearly different operations, so the context is clear. However, it lacks explicit exclusions like 'use read for single file content'.

  4

  Behavioral Transparency · 20%The description adds behavioral details beyond the readOnlyHint annotation: it states that identical files produce no hunks and that binary or non-UTF-8 files are refused. This is valuable because it sets expectations for edge cases. The readOnlyHint is already present, but the description reinforces the non-destructive nature and adds specific failure conditions.

  3

  Parameter Semantics · 15%The schema already provides descriptions for all three parameters (a, b, context) with 100% coverage, so the description does not need to add much. The description mentions 'from a to b' which clarifies the direction of the diff, but the schema already says 'First file to compare' and 'Second file to compare'. The context parameter is well-documented in the schema, so the description adds minimal extra value.

  5

  Conciseness & Structure · 10%The description is a single, concise sentence that packs in the core purpose, the diff style, and key edge-case behaviors. It is front-loaded with the main action and uses the 'diff -u' analogy for immediate clarity. No wasted words.

  4

  Contextual Completeness · 10%Given the tool's simplicity (3 parameters, no output schema, read-only), the description is complete enough. It covers the main behavior, edge cases (identical files, binary/UTF-8 refusal), and the direction. The lack of output schema is fine because the description implies a unified diff format. It could mention the output format more explicitly, but the 'diff -u' analogy covers that.

  params

  3 (2 required, 100% described)

  annotations

  readOnly=true openWorld=false

  output schema

  no

  cost

  2

  bytes

  760

  hash

  e840432f3f0a762e

• edit

  554455A4.7

  This is a well-crafted tool description that clearly explains the tool's purpose, usage constraints, and behavioral nuances. It effectively differentiates from siblings and provides actionable guidance for an AI agent, with no contradictions to annotations.

  5

  Purpose Clarity · 25%The description clearly states the tool edits text files in place by replacing exact oldText with newText, using a str_replace analogy. 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 purpose.

  5

  Usage Guidelines · 20%The description provides explicit usage guidance: pass path with edits or files for a 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, and the description adds critical behavioral details: atomicity per file (file written only if all edits match), batch files succeed/fail separately, and the exact-match requirement. It also mentions dryRun and undo, which are not in annotations. No contradiction with annotations.

  4

  Parameter Semantics · 15%Schema coverage is 100%, so baseline is 3. The description adds value by explaining the mutual exclusivity of path and files, the exact-match requirement, and the atomicity behavior. It also clarifies the dryRun and undo semantics, which are not fully captured in the schema descriptions.

  5

  Conciseness & Structure · 10%The description is concise, with two sentences that pack essential information without redundancy. It front-loads the core action and then covers key constraints and alternatives efficiently. Every sentence adds value.

  5

  Contextual Completeness · 10%Given the tool's complexity (multiple modes, atomicity, exact-match constraints) and the rich schema (100% coverage), the description covers all critical aspects: usage modes, constraints, dryRun, undo, and alternatives. No output schema exists, but the description sufficiently explains behavior 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

  554354A4.4

  The description is well-crafted, clearly stating the tool's purpose and usage context, with explicit alternatives to sibling tools. It adds behavioral details beyond annotations, such as pagination snapshot expiry and filtering defaults. The only minor gap is lack of return format details, but overall it's a strong, concise description.

  5

  Purpose Clarity · 25%The description clearly states the tool lists a directory's files and subdirectories as a tree, with explicit mention of depth, hidden/ignored filtering, and size/stat options. It distinguishes from siblings by naming find_files, stat, and read as alternatives for different needs.

  5

  Usage Guidelines · 20%The description explicitly mentions when to use this tool (listing directory contents) and contrasts with find_files (search by name pattern), stat (dates), and read (file contents). It also clarifies default behavior (one level deep, hidden/ignored skipped) and how to adjust via parameters.

  4

  Behavioral Transparency · 20%Annotations already declare readOnlyHint=true, so the description doesn't need to restate safety. It adds valuable behavioral details: pagination snapshot expiry (~60s), hidden/ignored filtering, and the fact that includeSizes adds a totals line. No contradiction with annotations.

  3

  Parameter Semantics · 15%Schema coverage is 100%, so the description doesn't need to explain each parameter. It does add context for maxDepth (default 1, increase to recurse) and mentions includeSizes adds totals, but most parameter semantics are already in the schema. Baseline 3 is appropriate.

  5

  Conciseness & Structure · 10%The description is a single, dense paragraph that front-loads the core purpose and then efficiently covers key behaviors and alternatives. Every sentence adds value, with no fluff or repetition.

  4

  Contextual Completeness · 10%Given the tool's complexity (8 parameters, pagination, filtering), the description covers the essential behaviors: depth, hidden/ignored, sizes, and pagination snapshot. It doesn't detail return format, but no output schema exists, so a bit more could be added. However, the description is sufficient for an agent to use it correctly.

  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, explicit usage guidelines, and valuable behavioral details beyond the annotations. It effectively differentiates from sibling tools and covers edge cases like overwrite and undo. Minor gaps include lack of return value details, but overall it is a high-quality tool 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 from siblings by explicitly mentioning delete for removal, and the title 'Move or Copy Files' reinforces the purpose.

  5

  Usage Guidelines · 20%The description provides explicit usage guidance: it explains that each destination is a full path, not a folder, and that missing parent directories are created. It also clarifies when to use overwrite (copies only) and when moves are refused, and directs to delete for removing paths, which differentiates from sibling tools.

  4

  Behavioral Transparency · 20%Annotations already indicate destructiveHint=true, so the description doesn't need to restate that. It adds valuable behavioral details: overwrite skips prompts only for copies, moves onto existing files prompt, moves onto non-empty directories are refused, and undo only works for moves (not copies). This goes beyond the annotations, though it doesn't mention permission requirements or side effects on symlinks.

  3

  Parameter Semantics · 15%Schema description coverage is 100%, so the schema already documents all parameters (copy, moves, overwrite). The description adds context about overwrite's scope (copies only) and the undo behavior, but it doesn't add much beyond the schema for the moves array structure. Baseline 3 is appropriate.

  5

  Conciseness & Structure · 10%The description is concise, with three sentences that each add critical information: the core operation, destination semantics, and overwrite/undo behavior. It is front-loaded with the main purpose and avoids redundancy.

  4

  Contextual Completeness · 10%Given the tool's complexity (multiple operations, edge cases, undo), the description covers the key behaviors well. It lacks details on return values (no output schema) and error handling, but the description is sufficient for an agent to use it correctly in most scenarios.

  params

  3 (1 required, 100% described)

  annotations

  readOnly=false destructive=true openWorld=false

  output schema

  no

  cost

  5

  bytes

  1396

  hash

  f9d7c7af2c6ae6a5

• patch

  554354A4.4

  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 critical safety information (atomicity, context-based matching) that complements the annotations. Minor gaps exist in parameter semantics and return value details, but overall it's a strong, helpful description.

  5

  Purpose Clarity · 25%The description clearly states the tool applies a single-file unified diff to an existing text file, with a specific verb ('apply') and resource ('single-file unified diff to one existing text file'). It distinguishes itself from siblings like 'edit' and 'replace_text' by mentioning 'like git apply' and contrasting with 'edit suits a few exact replacements'.

  5

  Usage Guidelines · 20%The description explicitly explains when to use this tool versus alternatives: it mentions 'edit suits a few exact replacements' as an alternative, and implies that patch is for more complex changes. It also provides critical usage constraints: 'Nothing is written unless every hunk applies in file order with exactly matching context' and 'hunks are found by their context, so start line numbers may be off'.

  4

  Behavioral Transparency · 20%Annotations already declare destructiveHint=true and readOnlyHint=false, so the description doesn't need to repeat that. It adds valuable behavioral context: the atomicity of the operation (nothing written unless all hunks apply), the context-based matching (line numbers may be off), and the dryRun option for previewing. This goes beyond the annotations by explaining the failure mode and the safety mechanism.

  3

  Parameter Semantics · 15%Schema description coverage is 100%, so the schema already documents all three parameters (path, diff, dryRun) with descriptions. The tool description adds minimal extra meaning beyond what the schema provides, but it does clarify that the diff should be 'as produced by the diff tool or edit dry-run' and that dryRun 'checks without writing', which slightly enhances the schema's 'Preview the diff without writing'.

  5

  Conciseness & Structure · 10%The description is concise and front-loaded: it opens with the core action and key constraint ('like git apply'), then adds essential behavioral details in a few sentences. Every sentence adds value, with no fluff or repetition of schema information.

  4

  Contextual Completeness · 10%Given the tool's moderate complexity (3 params, no output schema, but with annotations), the description covers the essential aspects: what it does, when to use it, key behavioral constraints, and the dryRun option. It doesn't explain the return value or error handling, but with no output schema and the annotations providing safety context, this is adequate. The mention of 'edit suits a few exact replacements' helps with tool selection among siblings.

  params

  3 (2 required, 100% described)

  annotations

  readOnly=false destructive=true openWorld=false

  output schema

  no

  cost

  2

  bytes

  976

  hash

  3fc66ca3084307ee

• read

  554354A4.4

  This description is well-crafted: it clearly defines the tool's purpose, provides usage guidance including when to use alternatives, and adds valuable behavioral context like result size handling. The 100% schema coverage means parameter semantics are well-covered. Minor gaps in behavioral details (e.g., handling of includeHash) are offset by the annotations and comprehensive schema, resulting in a strong overall score.

  5

  Purpose Clarity · 25%Description clearly states the tool reads text files (like cat) with modes for whole or slice, and mentions siblings like search_text and list for other operations. Distinctly differentiates from siblings (e.g., not for writing/deleting).

  5

  Usage Guidelines · 20%Explicitly instructs when to use this tool vs alternatives: 'Use search_text to find text and list for directories.' Also provides usage constraints: 'Pass path, or paths for a batch, not both.' Clear guidance on binary and slicing for performance.

  4

  Behavioral Transparency · 20%Annotations already declare readOnlyHint: true and openWorldHint: false. Description adds key behaviors: media files return as media, binary option for others, slicing reduces result size, and tokenEstimate via stat. It doesn't mention permissions or error cases but adds useful operational context beyond annotations.

  3

  Parameter Semantics · 15%Schema covers 100% of parameters with descriptions, so baseline is 3. Description adds some context (e.g., 'binary: true to get any other binary file whole', slice costs less), but does not significantly enrich meaning beyond excellent schema description. Meets baseline.

  5

  Conciseness & Structure · 10%Description is compact, front-loaded with the main purpose, and each sentence serves a distinct role (modes, path constraints, binary handling, performance tips, alternatives). No fluff, efficient.

  4

  Contextual Completeness · 10%Complexity high (9 params, many modes, batch, binary, line slicing), but description covers key decisions and redirects to stat for tokenEstimate. No output schema, but description gives enough hints (media, base64, slices). Could mention lineNumber interaction or error handling, but overall adequate given annotations and 100% schema coverage.

  params

  9 (0 required, 100% described)

  annotations

  readOnly=true openWorld=false

  output schema

  no

  cost

  0

  bytes

  1967

  hash

  7f0efb74274dbb1f

• replace_text

  554455A4.7

  This is a high-quality tool description that clearly explains the tool's purpose, provides explicit usage guidance, and adds valuable behavioral transparency beyond the annotations. It effectively differentiates from siblings and covers safety considerations, making it a strong example of a well-documented MCP tool.

  5

  Purpose Clarity · 25%The description clearly states the tool performs find-and-replace of literal text or RE2 regex across files or directories, with optional glob filtering. It distinguishes itself from siblings by explicitly mentioning 'Use edit for one unique exact match' and by describing its sed -i-like behavior, which differentiates it from search_text and edit.

  5

  Usage Guidelines · 20%The description provides explicit guidance on when to use this tool versus alternatives: it says to use edit for a single unique exact match, and it warns about wide scopes and suggests using dryRun first. It also mentions the directory run stops near 100 matches and that maxMatches sets a strict cap, giving clear context for when to use it.

  4

  Behavioral Transparency · 20%Annotations already indicate destructiveHint=true, so the description doesn't need to restate that. It adds valuable behavioral details: the pattern runs over the whole file (can span lines), ^ and $ anchor to file start/end, directory runs stop near 100 matches, each file is written separately, and dryRun and undo are available. This goes beyond the annotations and provides important context for safe usage.

  4

  Parameter Semantics · 15%Schema description coverage is 100%, so the schema already documents all parameters. The description adds extra meaning by explaining the pattern's behavior (whole-file matching, anchoring) and the interaction between maxMatches and directory runs. It also clarifies the use of dryRun and undo, which are not fully explained in the schema. This adds value beyond the schema, though not all parameters are individually elaborated in the description.

  5

  Conciseness & Structure · 10%The description is concise and front-loaded with the core purpose, then adds key behavioral notes and a pointer to an alternative. Every sentence adds value, and it avoids redundancy with the schema. It is well-structured and easy to scan.

  5

  Contextual Completeness · 10%Given the tool's complexity (14 parameters, destructive, directory-wide operations), the description covers the essential behavioral aspects: scope, safety (dryRun, undo), limits (maxMatches), and alternatives. The schema covers parameter details, and the description fills in the behavioral gaps. It is complete enough for an agent to use the tool correctly and safely.

  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. The zero-parameter schema is fully compensated by the description's clarity, making it a model example for such tools.

  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 sibling tools like 'list' and 'find_files' by focusing on root directories and access scope.

  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 implies alternatives for path discovery.

  4

  Behavioral Transparency · 20%Annotations already declare readOnlyHint=true, and the description adds context about read-only directories being listed in readOnlyDirs and that writes/moves/deletes under them are refused. This goes beyond annotations by explaining the behavioral consequence of read-only status.

  4

  Parameter Semantics · 15%The tool has zero parameters, and the schema coverage is 100% (empty properties). The description adds value by explaining the output structure (readOnlyDirs) and the session-granted aspect, which is not in the schema. Baseline 4 for zero params is appropriate.

  5

  Conciseness & Structure · 10%Three sentences, each earning its place: what it lists, when to call it, and the read-only implication. No fluff, front-loaded with the core purpose.

  5

  Contextual Completeness · 10%For a zero-parameter, read-only tool with no output schema, the description fully covers what the agent needs: purpose, usage timing, and behavioral notes on read-only directories. 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 strong across all dimensions: clearly defines purpose, distinguishes from sibling find_files, and provides valuable behavioral context beyond schema. Minor gaps include a slightly cryptic phrase about path formats and limited guidance on when to use vs. not use specific parameters, but overall it is a high-quality, well-structured description.

  5

  Purpose Clarity · 25%The description clearly states the tool performs a grep-like search of file contents using literal text or RE2 regex, returning matching lines with line numbers and paths. It distinguishes from sibling find_files, which matches file names, thus providing clear resource and verb specificity.

  4

  Usage Guidelines · 20%The description provides clear when-to-use context (searching contents vs file names), explicitly naming find_files as the alternative for name-based searches. It notes that named files are searched exclusively and that path can be a file or directory, but does not discuss scenarios to avoid or other siblings. Overall, good guidance for a search tool.

  4

  Behavioral Transparency · 20%Annotations declare readOnlyHint=true, which description aligns with (no writes). The description adds important behavioral context: literal vs regex matching, case sensitivity defaults, line-matching scope, header behavior for named files, and pagination cursor. Slight gap: it doesn't mention hidden/ignored filtering defaults, but schema covers those implicitly. Since annotations cover the read-only safety, this is well above baseline.

  4

  Parameter Semantics · 15%Schema coverage is 100%, so baseline is 3. The description adds meaningful semantics beyond schema: explains that searchPattern is matched within one line, pattern filters by glob, named file causes pattern to be ignored and disables filtering. This clarifies the interplay between parameters, earning a 4.

  4

  Conciseness & Structure · 10%Description is concise with five sentences, front-loaded with the core purpose and key details. It covers all major aspects without redundancy. Slight deduction for minor nuance like 'read accepts either form' which is a bit cryptic and could be clarified, but overall well-structured and efficient.

  4

  Contextual Completeness · 10%With 11 parameters and a 100% schema coverage, the description provides a solid overview of behavior, alternatives, and edge cases (named file behavior, pagination). It lacks some detail on hidden/ignored defaults and return structure, but the schema covers most of that. Given the tool's moderate complexity and no output schema, this description is adequate.

  params

  11 (1 required, 100% described)

  annotations

  readOnly=true openWorld=false

  output schema

  no

  cost

  1

  bytes

  2688

  hash

  011294ae96637bab

• find_files

  554354A4.4

  This is a well-crafted description that clearly explains the tool's purpose, differentiates it from siblings, and provides key behavioral details like pattern matching and pagination. The schema covers parameters thoroughly, so the description focuses on usage context and edge cases, making it highly effective for an AI agent. Minor gaps like explicit snapshot semantics are covered by the schema, so no significant issues.

  5

  Purpose Clarity · 25%The description clearly states the tool finds files by name or glob pattern, analogous to the Unix 'find' command, and distinguishes it from siblings like 'list' (browses directories) and 'search_text' (searches contents). It also specifies the output (root-relative or absolute paths) and the key behavior of matching file names at any depth when no slash is present.

  5

  Usage Guidelines · 20%The description explicitly mentions when to use this tool versus alternatives: 'list browses directories; search_text searches contents.' It also provides usage context such as the pattern matching behavior (no slash matches at any depth) and the default skipping of hidden and ignored files, which helps the agent decide when to set includeHidden/includeIgnored.

  4

  Behavioral Transparency · 20%Annotations already declare readOnlyHint=true, so the description doesn't need to restate safety. It adds valuable behavioral details: hidden/ignored files are skipped by default, pagination uses a cursor that expires after ~60s, and the returned paths are compatible with the 'read' tool. This goes beyond the schema and annotations, though it could mention that results are a snapshot (implied by cursor expiry).

  3

  Parameter Semantics · 15%Schema description coverage is 100%, so the schema already documents all parameters. The description adds some context (e.g., pattern without slash matches at any depth, cursor usage for pagination) but does not systematically explain each parameter beyond what the schema provides. Baseline 3 is appropriate.

  5

  Conciseness & Structure · 10%The description is concise, front-loaded with the core purpose, and each sentence adds value: pattern matching behavior, path format, pagination, and sibling tool differentiation. No fluff or redundancy.

  4

  Contextual Completeness · 10%Given the tool's moderate complexity (8 parameters, pagination, glob patterns) and the rich schema (100% coverage), the description covers the essential behavioral aspects: pattern semantics, default exclusions, pagination, and path compatibility. It could mention the snapshot/expiry behavior more explicitly, but the schema already covers cursor expiry. Overall, it's complete enough for effective use.

  params

  8 (1 required, 100% described)

  annotations

  readOnly=true openWorld=false

  output schema

  no

  cost

  1

  bytes

  1834

  hash

  a1c490a6e06d2266

• stat

  554355A4.5

  This is a high-quality tool description that clearly defines the tool's purpose, differentiates it from siblings, and provides essential behavioral context beyond the annotations. It is concise yet comprehensive, covering usage constraints, return fields, and edge cases. The only minor gap is that parameter semantics are largely left to the schema, but the schema is thorough, so this is acceptable.

  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 it does not read contents. The analogy to ls -ld provides a concrete mental model.

  5

  Usage Guidelines · 20%The description provides explicit usage guidance: 'Pass path, or paths for a batch, not both.' It also clarifies when to use this tool over alternatives by stating 'read returns contents; list lists a directory,' which differentiates stat from those sibling tools. This is a clear when-to-use and when-not-to-use explanation.

  4

  Behavioral Transparency · 20%Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds valuable behavioral context beyond annotations: it explains that missing paths produce NOT_FOUND entries (so stat checks existence), and notes the Windows-specific behavior about rewrite resetting created time unless hard links exist. These are non-obvious behaviors that help the agent anticipate results.

  3

  Parameter Semantics · 15%Schema description coverage is 100%, with both parameters (path and paths) having descriptions including mutual exclusivity and batch limits. The description adds the key constraint 'not both' and clarifies batch behavior, but the schema already covers the parameter semantics well. The description does not add significant new meaning beyond what the schema provides, so a baseline 3 is appropriate.

  5

  Conciseness & Structure · 10%The description is concise and front-loaded with the core purpose. It packs a lot of information into a few sentences without redundancy. Every sentence adds value: purpose, fields, usage constraint, existence checking, Windows nuance, and sibling differentiation. No wasted words.

  5

  Contextual Completeness · 10%Given the tool's moderate complexity (2 params, no output schema, but with annotations), the description is complete. It covers the return fields, batch behavior, existence checking, and platform-specific nuance. The absence of an output schema is compensated by listing the fields returned. The description fully equips the agent to use the tool correctly.

  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 and schema. It effectively guides an agent on when and how to use the undo tool, including important caveats like HTTP restrictions and conditional restoration. The only minor gap is the lack of explicit guidance on what happens when neither id nor steps is provided, but the overall quality is high.

  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 the condition that a file is restored only if unchanged since. It does not explicitly name alternative tools, but the context is sufficient for an agent to decide when to use undo.

  4

  Behavioral Transparency · 20%Annotations already indicate destructiveHint=true, so the description's mention of reverting changes aligns. The description adds valuable behavioral details beyond annotations: the requirement for an id over HTTP, the conditional restoration (only if unchanged since), the result listing file outcomes, truncation on large undos, and dryRun behavior. This is rich context that helps the agent understand side effects and limitations.

  4

  Parameter Semantics · 15%Schema description coverage is 100%, so the schema already documents all three parameters. The description adds meaning by explaining the relationship between id and steps (mutually exclusive), the HTTP restriction for steps, and the dryRun semantics including the caveat about previewing the whole history. This goes beyond the schema's basic descriptions.

  5

  Conciseness & Structure · 10%The description is concise, with three sentences that pack essential information: the core action, key constraints, and dryRun behavior. It is front-loaded with the main purpose and avoids redundancy with the schema. Every sentence adds value.

  4

  Contextual Completeness · 10%Given the tool's complexity (multiple modes, conditional restoration, HTTP restrictions, dryRun nuances) and the lack of an output schema, the description covers the key aspects well. It explains the result format (file outcomes) and truncation behavior, which is important for an agent to interpret results. Minor gaps: it doesn't specify what happens if no id or steps are provided, but the schema's optional parameters and the description's 'not both' imply that one must be chosen.

  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/g73vuwnjea/badge.svg)](https://tdqs.dev/reports/g73vuwnjea)

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/g73vuwnjea \
  -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}")