filesystem-mcp

• create

  554355A4.5

  The description is well-crafted, clearly stating the tool's purpose and usage guidelines, and it effectively differentiates from sibling tools. It adds valuable behavioral context beyond the annotations, such as overwrite confirmation and automatic parent directory creation. The schema is comprehensive, so the description complements it well without redundancy.

  5

  Purpose Clarity · 25%The description clearly states the tool's purpose: writing whole text files (create, overwrite, or append) and making empty directories. It distinguishes itself from siblings by explicitly mentioning 'edit' and 'patch' for modifying parts of existing files, which sets it apart from those tools.

  5

  Usage Guidelines · 20%The description provides explicit guidance on when to use this tool: for creating new files, replacing full contents, or creating folders. It also states when not to use it by directing to 'edit' or 'patch' for partial modifications, and mentions the overwrite confirmation requirement, which is a key usage condition.

  4

  Behavioral Transparency · 20%Annotations already indicate destructiveHint=true, and the description adds important behavioral details: missing parent directories are created automatically, overwriting requires overwrite: true or user confirmation, and it returns created paths and an undo id. This goes beyond the annotation by explaining the overwrite confirmation behavior and the undo capability, which is valuable for the agent.

  3

  Parameter Semantics · 15%The schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds some context by mentioning the overwrite confirmation and the automatic creation of parent directories, but it does not add significant new meaning beyond what the schema provides. Baseline 3 is appropriate.

  5

  Conciseness & Structure · 10%The description is concise and well-structured, with a clear first sentence stating the core function, followed by usage guidance and behavioral notes. Every sentence adds value, and it is not overly verbose.

  5

  Contextual Completeness · 10%Given the tool's complexity (multiple modes: create, overwrite, append, directories), the description covers all key aspects: usage, overwrite behavior, parent directory creation, and return values. The schema is rich and covers parameters, so the description is complete enough 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

  1811

  hash

  74c8a6290db15bef

• delete

  554355A4.5

  This is a well-crafted description that clearly defines the tool's purpose, provides explicit usage guidance, and adds valuable behavioral context beyond the annotations. It is concise yet complete, covering all edge cases and distinguishing itself from sibling tools like move. The only minor gap is that parameter semantics are largely covered by the schema, but the description still adds useful behavioral notes.

  5

  Purpose Clarity · 25%The description clearly states the tool deletes files, directories, or symlinks, equivalent to rm or rm -r, and explicitly distinguishes it from move for relocation. It specifies the exact resource and action, making it distinct from siblings like move and create.

  5

  Usage Guidelines · 20%The description provides explicit when-to-use guidance: 'Use when permanently removing paths' and 'Use move to relocate a path instead.' It also covers edge cases like non-empty directories requiring recursive and ignoreIfNotExists for clean success, giving clear context for when to use this tool versus alternatives.

  4

  Behavioral Transparency · 20%Annotations already declare destructiveHint=true, but the description adds critical behavioral details: paths are exact (no glob expansion), non-empty directories require recursive and confirmation, and ignoreIfNotExists allows clean success. It also mentions the return format and undo id, which are not in annotations. The description does not contradict annotations, and the added context is valuable.

  3

  Parameter Semantics · 15%Schema description coverage is 100%, so the schema already documents all three parameters. The description adds some context by explaining the behavior of recursive (requires confirmation) and ignoreIfNotExists (silent success), but these are also partially in the schema. The description does not add significant new meaning beyond the schema, so a baseline of 3 is appropriate.

  5

  Conciseness & Structure · 10%The description is concise, with three sentences that cover purpose, usage, and key behaviors. It is front-loaded with the core action and includes only essential details, with no wasted words. The structure is clear and easy to parse.

  5

  Contextual Completeness · 10%Given the tool's complexity (handles files, directories, symlinks, recursion, confirmation, and ignoreIfNotExists) and the absence of an output schema, the description is complete. It covers all critical behaviors, return format, and undo capability, and the schema covers parameters fully. No significant gaps remain.

  params

  3 (1 required, 100% described)

  annotations

  readOnly=false destructive=true openWorld=false

  output schema

  no

  cost

  1

  bytes

  1392

  hash

  45454b4146c223b3

• diff

  554355A4.5

  This is a well-crafted description that excels in purpose clarity and usage guidance, clearly distinguishing from siblings and providing actionable instructions. Behavioral transparency is strong, building on annotations to detail edge cases. Parameter semantics is adequate as the schema covers parameters; conciseness and completeness are exemplary for a tool of this complexity.

  5

  Purpose Clarity · 25%The description clearly states 'Compare two text files and return a unified diff from a to b', which is specific about the verb, resource, and format. It explicitly references 'diff -u' to clarify behavior. It distinguishes itself from siblings like 'read' (which inspects content) and 'search_text' (which finds patterns).

  5

  Usage Guidelines · 20%The description explicitly says 'Use when reviewing changes between two files', providing clear context. It also gives usage guidance: 'Use read to inspect full files or slices first', suggesting when to defer to alternatives. It mentions limitations (rejects binary, TOO_LARGE) that inform decision-making.

  4

  Behavioral Transparency · 20%Annotations already include readOnlyHint=true, which is consistent with a diff tool. The description adds valuable behavioral details beyond annotations: 'identical files return no hunks' clarifies output behavior, and error conditions (rejects binary, non-UTF-8, TOO_LARGE) are disclosed. While readOnlyHint covers safety, the description enriches understanding.

  3

  Parameter Semantics · 15%The input schema already provides descriptions for all three parameters (a, b, context) with 100% coverage. The description does not add much beyond the schema, but it reinforces that 'a' and 'b' are files and introduces the concept of 'hunks' which relates to output. Since schema coverage is high, baseline 3 is appropriate.

  5

  Conciseness & Structure · 10%The description is concise, with only 3 sentences that are front-loaded with the core functionality. Every sentence provides essential information: what it does, when to use it, and what to expect including edge cases. There is no fluff or redundancy.

  5

  Contextual Completeness · 10%Given the tool's simplicity (3 parameters, no output schema, no nested objects) and comprehensive annotations (readOnlyHint=true), the description covers all necessary aspects: purpose, usage, edge cases, and alternatives. With high schema coverage and clear behavioral notes, no critical information is missing.

  params

  3 (2 required, 100% described)

  annotations

  readOnly=true openWorld=false

  output schema

  no

  cost

  2

  bytes

  959

  hash

  e56b995cab64f701

• edit

  554455A4.7

  This is a high-quality tool description that clearly defines the tool's purpose, provides explicit usage guidelines with alternatives, and adds behavioral transparency beyond annotations. The parameter semantics are well-supported by the schema, and the description is concise yet complete, making it easy for an agent to select and use correctly.

  5

  Purpose Clarity · 25%The description clearly states the tool edits text files by replacing exact oldText with newText, and it distinguishes itself from siblings by explicitly naming replace_text, patch, and create for different use cases. The verb 'edit' and resource 'text files' are specific, and the scope (in-place replacement) is unambiguous.

  5

  Usage Guidelines · 20%The description provides explicit when-to-use guidance: 'Use when changing specific unique snippets in one or more files.' It also gives clear exclusions: 'Use replace_text for multiple occurrences or regex, patch to apply unified diffs, and create for new files.' This directly addresses alternatives and when not to use this tool.

  4

  Behavioral Transparency · 20%Annotations already declare destructiveHint=true, so the description doesn't need to restate that. It adds valuable behavioral context: the requirement that oldText must match exactly once, failure behavior (leaves file untouched), return of an edit summary with line counts and undo id, and dryRun preview. This goes beyond annotations, though it could mention that edits are irreversible without undo, but the undo id is mentioned.

  4

  Parameter Semantics · 15%Schema description coverage is 100%, so the baseline is 3. The description adds meaning by explaining the exact-match requirement and the use of context lines, which is not fully captured in the schema's parameter descriptions. It also clarifies the dryRun behavior and the ignoreWhitespace re-indentation, adding value beyond the schema.

  5

  Conciseness & Structure · 10%The description is two sentences, front-loaded with the core action, and every clause earns its place. It packs a lot of information (matching rules, failure behavior, return values, alternatives) without redundancy. The structure is efficient and scannable.

  5

  Contextual Completeness · 10%Given the tool's complexity (5 params, batch mode, exact-match constraints) and the rich schema (100% coverage) plus annotations, the description covers all critical aspects: when to use, matching rules, failure behavior, return values, and alternatives. No output schema exists, but the description mentions the edit summary and undo id, which is sufficient. It is complete for an agent to select and invoke correctly.

  params

  5 (0 required, 100% described)

  annotations

  readOnly=false destructive=true openWorld=false

  output schema

  no

  cost

  0

  bytes

  2926

  hash

  2d702cce50cf5157

• list

  554455A4.7

  This is a high-quality tool description. It clearly states purpose, provides explicit usage guidance with sibling alternates, and adds valuable behavioral details beyond annotations (pagination, hidden/ignored files, sorting). It is concise and well-structured. The only minor improvement could be explicit notes on parameter interactions, but schema coverage already handles that, so the description earns high scores across dimensions.

  5

  Purpose Clarity · 25%The description clearly states the tool lists directory contents as a tree of names, comparing to ls or tree. It distinguishes from siblings by explicitly mentioning find_files, stat, and read, showing awareness of the tool's role in exploring structure.

  5

  Usage Guidelines · 20%It provides explicit guidance on when to use this tool ('when exploring directory structure or checking folder contents') and lists alternatives (find_files, stat, read) for other tasks. It also clarifies default traversal depth and hidden/ignored file behavior, helping the agent decide when to adjust parameters.

  4

  Behavioral Transparency · 20%Annotations declare readOnlyHint=true and openWorldHint=false, and the description aligns with that. It adds important behavioral details not in annotations: one-level-deep default, skipping hidden/ignored files, sortBy size ordering, and pagination semantics (snapshot, 60s expiry, resourceUri on incomplete page). Slight gap: it doesn't mention that traversal is one level deep unless maxDepth is raised, but it does; also doesn't state whether path can be a file or only directory, though schema implies directory. Overall, it goes beyond annotations, so a 4 is warranted.

  4

  Parameter Semantics · 15%Schema coverage is 100%, so baseline is 3, but the description adds value by explaining the overall behavior of maxDepth and pagination context (e.g., nextCursor when paged). It also clarifies sortBy meaning (largest first) which is already in schema but reinforced. It does not describe each parameter individually, but that is covered by schema. Since it enriches the understanding of how parameters interact (maxDepth, cursor, sortBy, includeHidden), a 4 is appropriate.

  5

  Conciseness & Structure · 10%The description is two sentences: front-loaded with core purpose and usage, then key behavioral notes. Every sentence adds unique value (purpose, usage, traversal depth, hidden/ignored, sortBy, return format, sibling pointers). No fluff or redundancy.

  5

  Contextual Completeness · 10%Given the tool's moderate complexity (8 parameters, but all optional with defaults) and rich schema descriptions (100% coverage), the description provides sufficient context. It mentions output format (formatted tree text, nextCursor), default behaviors, and alternatives. No output schema exists, but the description covers return structure adequately. The description is complete for an agent to select and invoke correctly.

  params

  8 (0 required, 100% described)

  annotations

  readOnly=true openWorld=false

  output schema

  no

  cost

  0

  bytes

  1951

  hash

  e1da679cca20cfbe

• move

  554354A4.4

  This is a well-crafted tool description that clearly explains the move/copy functionality, provides explicit usage guidance, and adds behavioral context beyond the annotations. It effectively distinguishes itself from sibling tools and covers all critical constraints. Minor gaps exist in parameter semantics (schema already covers them) and undo details, but overall it's a high-quality description.

  5

  Purpose Clarity · 25%The description clearly states the tool moves, renames, or copies files and directories, explicitly comparing to 'mv or cp -r'. It distinguishes from siblings by mentioning 'Use delete to remove paths' and implies it's not for content editing (unlike edit, patch, replace_text). The verb and resource are specific and unambiguous.

  5

  Usage Guidelines · 20%The description provides explicit when-to-use guidance: 'Use when renaming paths, moving files between directories, or copying trees (copy: true)'. It also gives a critical exclusion: 'Each destination must be the full target path, not an existing directory to move into', and clarifies overwrite behavior. It names an alternative (delete) for removal, making the usage context complete.

  4

  Behavioral Transparency · 20%Annotations already declare destructiveHint=true, so the description doesn't need to restate that. It adds valuable context beyond annotations: the distinction between move and copy behavior, the requirement for full target paths, the confirmation requirement for moving onto existing files, and the return of an undo id. This is rich behavioral disclosure that helps the agent anticipate side effects and constraints.

  3

  Parameter Semantics · 15%Schema description coverage is 100%, so the schema already documents all three parameters (moves, copy, overwrite) with descriptions. The tool description adds some semantic nuance (e.g., 'copy: true' for copying trees, 'overwrite applies only to copies'), but it doesn't significantly expand on the schema's parameter descriptions. Baseline 3 is appropriate given the high schema coverage.

  5

  Conciseness & Structure · 10%The description is concise and front-loaded: the first sentence states the core purpose, followed by usage guidance and key constraints. Every sentence adds value—no fluff or repetition. It's structured logically from what it does to when to use it to important caveats, all in a compact paragraph.

  4

  Contextual Completeness · 10%Given the tool's moderate complexity (3 params, no output schema, no nested objects), the description covers the essential aspects: purpose, usage, constraints, and return value (moved paths and undo id). It doesn't explain the undo mechanism in detail, but that's likely covered by the undo sibling tool. The description is complete enough for an agent to use the tool correctly without additional context.

  params

  3 (1 required, 100% described)

  annotations

  readOnly=false destructive=true openWorld=false

  output schema

  no

  cost

  5

  bytes

  1367

  hash

  016075a0ef18080a

• patch

  554354A4.4

  This is a well-crafted description that clearly explains the tool's purpose, usage, and failure behavior, and effectively distinguishes it from sibling tools. It leverages the annotations appropriately and adds valuable context about atomicity and dryRun. Minor gaps exist in explaining the undo mechanism and return format, but overall it is highly effective.

  5

  Purpose Clarity · 25%The description clearly states the tool applies a single-file unified diff to an existing text file, analogous to git apply. It distinguishes itself from siblings by explicitly naming edit and replace_text as alternatives for different use cases.

  5

  Usage Guidelines · 20%The description provides explicit guidance on when to use this tool (applying diffs from diff tools or git) and when not to (use edit for unique snippet replacements, replace_text for regex across files). It also mentions dryRun for testing applicability, which is a clear usage hint.

  4

  Behavioral Transparency · 20%Annotations already declare destructiveHint=true, so the description's mention of 'Writes nothing unless every hunk applies' adds valuable context about atomicity and failure behavior. It also discloses that mismatched hunks leave the file untouched, which is beyond the annotation's basic destructive flag. However, it doesn't detail what happens on partial success or the undo mechanism beyond mentioning an undo id.

  3

  Parameter Semantics · 15%Schema description coverage is 100%, so the schema already documents all three parameters. The description adds context about the diff format (single-file unified diff) and the dryRun purpose, but these are also partially in the schema. The description doesn't add significant new meaning beyond what the schema provides, so baseline 3 is appropriate.

  5

  Conciseness & Structure · 10%The description is concise, with each sentence serving a purpose: it states the action, provides usage context, explains failure behavior, mentions return values, and gives alternatives. No wasted words.

  4

  Contextual Completeness · 10%Given the tool's moderate complexity (3 params, no output schema), the description covers the key aspects: what it does, when to use it, failure behavior, and alternatives. It could be more complete by explaining the undo id usage or return format, but the description is sufficient for an agent to use the tool correctly.

  params

  3 (2 required, 100% described)

  annotations

  readOnly=false destructive=true openWorld=false

  output schema

  no

  cost

  2

  bytes

  1101

  hash

  700cca4452aa9529

• read

  554455A4.7

  This is a high-quality description that clearly explains the tool's purpose, usage, and behavioral nuances. It effectively differentiates from sibling tools and provides essential context for parameter semantics, making it a model example for tool descriptions.

  5

  Purpose Clarity · 25%The description clearly states the tool reads text files like cat, with options for whole file or slices via head/tail/startLine/endLine. It distinguishes itself from siblings by mentioning stat for size/token estimates, search_text for finding text, and list for browsing folders.

  5

  Usage Guidelines · 20%Explicitly says 'Use when inspecting file contents' and provides clear guidance on when to use alternatives: 'Use stat for size and token estimates before reading, search_text to find text, and list to browse folders.' This is excellent differentiation.

  4

  Behavioral Transparency · 20%Annotations already declare readOnlyHint=true, so the description doesn't need to restate safety. It adds useful behavioral details: binary mode disables slicing, images/audio return as media, batch mode returns per-path results, and lineNumbers prefix behavior. No contradictions.

  4

  Parameter Semantics · 15%Schema coverage is 100%, so baseline is 3. The description adds value by explaining the binary mode disables slicing, images/audio return as media, and batch mode returns per-path results, which are not fully captured in the schema. It also clarifies the lineNumbers prefix should be left out of edit text.

  5

  Conciseness & Structure · 10%The description is concise, front-loaded with the core purpose, and every sentence adds value. It covers key behaviors and alternatives without redundancy.

  5

  Contextual Completeness · 10%Given the tool's complexity (9 parameters, batch mode, binary mode, slicing), the description is complete. It covers return types, batch behavior, and usage guidance. No output schema exists, but the description adequately explains what is returned.

  params

  9 (0 required, 100% described)

  annotations

  readOnly=true openWorld=false

  output schema

  no

  cost

  0

  bytes

  1961

  hash

  279bb552da424f76

• replace_text

  555455A4.9

  This is an excellent description: it clearly defines the tool's purpose, differentiates from siblings, provides critical usage guidance (dryRun, scope warnings), and discloses behavioral nuances beyond annotations. The parameter descriptions are enriched with practical examples and warnings, making selection and invocation straightforward.

  5

  Purpose Clarity · 25%Clearly states it finds and replaces text or RE2 regex across files or directories, like sed -i. Differentiates from siblings by mentioning edit for single snippets and patch for unified diffs.

  5

  Usage Guidelines · 20%Explicitly says use for replacing every match across a file or project, advises dryRun for wide scopes, and directs to edit for single unique snippets and patch for unified diffs. Also notes default maxMatches behavior.

  5

  Behavioral Transparency · 20%Discloses destructive nature (modifies files) beyond the destructiveHint annotation, mentions directory runs stop near 100 matches, returns match counts and undo id, and advises dryRun for safety. No contradiction with annotations.

  4

  Parameter Semantics · 15%Schema coverage is 100%, but description adds crucial context like path scope warning (omitting targets ENTIRE root), RE2 limitations (no lookahead/backrefs), and caseSensitive behavior relative to search_text. This goes beyond bare schema descriptions.

  5

  Conciseness & Structure · 10%Front-loaded with a clear one-line purpose, followed by key usage distinctions and safety tips. Each sentence adds value without redundancy; appropriate length for a complex tool.

  5

  Contextual Completeness · 10%Given high complexity (14 params, destructive, no output schema), it covers return values (counts, files, undo id), scoping, regex nuances, and operational limits. The parameter descriptions in the schema also enrich completeness.

  params

  14 (2 required, 100% described)

  annotations

  readOnly=false destructive=true openWorld=false

  output schema

  no

  cost

  2

  bytes

  3157

  hash

  e9b7867b603340b6

• list_roots

  554455A4.7

  This is a well-crafted description for a simple, read-only tool. It clearly states the purpose, provides explicit usage guidance, and adds valuable behavioral context about access control that goes beyond the annotations. With zero parameters and no output schema, the description is appropriately concise and complete, making it a strong example of effective tool documentation.

  5

  Purpose Clarity · 25%The description clearly states the tool lists workspace directory roots, specifies the scope (including session-granted roots), and distinguishes it from sibling tools by focusing on directory boundaries rather than file operations. The verb 'list' and resource 'workspace directory roots' are specific and unambiguous.

  5

  Usage Guidelines · 20%The description explicitly says to use this tool when starting a session or checking accessible directory boundaries, providing clear context for when it is appropriate. It also implicitly differentiates from siblings by noting that other tools handle file operations, and it explains the relationship to access control, which guides usage.

  4

  Behavioral Transparency · 20%Annotations already declare readOnlyHint=true and openWorldHint=false, so the description adds value by explaining the return structure ({ roots, readOnlyDirs }) and the behavioral consequence: mutating operations under readOnlyDirs are refused with ACCESS_DENIED. It also mentions that other tools prompt for approval outside roots, which is useful context beyond annotations. However, it doesn't detail the exact format of paths or whether roots are sorted, but that's minor.

  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 return value and usage context, which is sufficient.

  5

  Conciseness & Structure · 10%The description is three sentences, each earning its place: the first states the core function, the second gives usage context, and the third explains behavioral implications. It is front-loaded with the primary purpose and avoids redundancy.

  5

  Contextual Completeness · 10%Given the tool's simplicity (no parameters, no output schema), the description is complete. It covers what the tool returns, when to use it, and the access control behavior, which is all an agent needs to know. The annotations and sibling context further round out the picture.

  params

  0 (0 required, 100% described)

  annotations

  readOnly=true openWorld=false

  output schema

  no

  cost

  0

  bytes

  636

  hash

  09098809323a9502

• search_text

  554455A4.7

  This is an excellent tool description that clearly defines the purpose, provides explicit usage guidance with alternatives, and adds valuable behavioral context beyond the annotations. It leverages the schema's high coverage while adding semantic details that help the agent understand edge cases like case sensitivity and pagination. The description is concise yet comprehensive, making it a top-tier example.

  5

  Purpose Clarity · 25%The description clearly states the tool searches file contents for text or regex, like grep, and distinguishes it from siblings by mentioning find_files for name-based search and read for viewing context. The verb 'search' and resource 'file contents' are specific and unambiguous.

  5

  Usage Guidelines · 20%The description explicitly says when to use this tool ('when searching for keywords or patterns across files') and provides alternatives: 'Use read to view full context, and find_files to find by name.' This gives clear guidance on when not to use it and what to use instead.

  4

  Behavioral Transparency · 20%Annotations already declare readOnlyHint=true, so the description doesn't need to repeat that. It adds useful behavioral details: case-insensitive by default, line-by-line matching, returns grouped results with line numbers and a nextCursor for paging, and notes that pagination snapshots expire after ~60s. It also mentions that replacements match case by default, which is a subtle behavioral nuance. Minor gap: doesn't mention that hidden/ignored files are excluded by default, but that's in the schema.

  4

  Parameter Semantics · 15%Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the searchPattern semantics (line-by-line, case-insensitive by default) and the pattern parameter's role as a glob filter, which goes beyond the schema's basic descriptions. It also clarifies the path parameter's behavior (naming a file ignores pattern and filtering), which is not fully explicit in the schema. This extra context justifies a 4.

  5

  Conciseness & Structure · 10%The description is two sentences, front-loaded with the core purpose and usage, and every clause adds value. It efficiently covers purpose, usage, key behaviors, and alternatives without redundancy. No fluff.

  5

  Contextual Completeness · 10%Given the tool's complexity (11 parameters, no output schema), the description covers the essential aspects: what it does, when to use it, key behaviors (case sensitivity, line-by-line, paging), and alternatives. The schema provides detailed parameter documentation, so the description doesn't need to repeat that. It's complete for an agent to select and invoke correctly.

  params

  11 (1 required, 100% described)

  annotations

  readOnly=true openWorld=false

  output schema

  no

  cost

  1

  bytes

  2678

  hash

  280886960cf8815c

• find_files

  554355A4.5

  This is a well-crafted tool description that clearly states its purpose, provides explicit usage guidance with alternatives, and adds behavioral context beyond the annotations. It leverages the schema for parameter details while adding pattern semantics and default behavior. The description is concise, well-structured, and complete for the tool's complexity.

  5

  Purpose Clarity · 25%The description clearly states the tool's purpose: 'Find files by name or glob pattern, like find.' It specifies the resource (files) and the action (find), and distinguishes it from siblings by mentioning 'Use list to browse directory trees, and search_text to search file contents.' This is a specific verb+resource with clear differentiation.

  5

  Usage Guidelines · 20%The description provides explicit guidance on when to use this tool: 'Use when locating files by name or pattern anywhere in the workspace.' It also gives exclusions: 'Use list to browse directory trees, and search_text to search file contents.' This clearly tells the agent when to use this tool versus alternatives.

  4

  Behavioral Transparency · 20%Annotations already declare readOnlyHint=true, so the description doesn't need to repeat that. It adds valuable behavioral context: 'Skips hidden and ignored files by default' and 'Returns matching paths and a nextCursor for paging.' It also explains pattern semantics (with/without slash). This goes beyond annotations, though it doesn't mention the 60s cursor expiry (that's in the schema).

  3

  Parameter Semantics · 15%Schema description coverage is 100%, so the schema already documents all parameters. The description adds some context about pattern behavior (e.g., 'A pattern without / matches names at any depth (*.ts); a pattern with / matches relative paths (src/**/*.ts)') which is helpful, but most parameter details are in the schema. Baseline 3 is appropriate.

  5

  Conciseness & Structure · 10%The description is concise and front-loaded. It starts with the core purpose, then usage guidance, then pattern semantics, then default behavior, then return value, and finally alternatives. Every sentence adds value with no fluff. It's well-structured and easy to scan.

  5

  Contextual Completeness · 10%Given the tool's complexity (8 parameters, glob patterns, pagination), the description covers the essential aspects: purpose, usage, pattern semantics, default exclusions, return value, and alternatives. The schema covers parameter details, and annotations cover safety. The description is complete for an agent to use effectively.

  params

  8 (1 required, 100% described)

  annotations

  readOnly=true openWorld=false

  output schema

  no

  cost

  1

  bytes

  1911

  hash

  7f618320bc27c3ba

• stat

  554354A4.4

  This is a well-crafted description that clearly defines the tool's purpose, provides explicit usage guidance with alternatives, and adds valuable behavioral context beyond the annotations. It is concise and complete, with only minor gaps in edge-case details. Overall, it scores high across all dimensions, making it a strong example of a helpful tool description.

  5

  Purpose Clarity · 25%The description clearly states the tool's purpose: 'Get metadata without reading file contents, like ls -ld.' It specifies the resource (files/directories) and the action (stat), and distinguishes it from siblings by explicitly mentioning 'Use read to view contents, and list to browse directories.' This is a specific verb+resource with clear differentiation.

  5

  Usage Guidelines · 20%The description provides explicit guidance on when to use the tool: 'Use when checking file existence, size, type, or timestamps.' It also gives exclusions: 'Use read to view contents, and list to browse directories.' This clearly delineates when to use stat versus alternatives, meeting the highest standard.

  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 get a NOT_FOUND entry (so batches succeed), and that symlinks report their target after validating the path. It also lists the returned fields (type, size/entryCount, tokenEstimate, timestamps, permissions, mimeType). This is rich context that goes beyond the annotations, though it doesn't detail error handling for invalid paths or permission issues, so a 4 is appropriate.

  3

  Parameter Semantics · 15%Schema description coverage is 100%, so the schema already documents both parameters (path and paths) with descriptions. The tool description adds context about batch mode ('Missing paths get their own NOT_FOUND entry') and mentions that paths are for batch mode, but it doesn't add syntax or format details beyond what the schema provides. Baseline 3 is correct when schema does the heavy lifting.

  5

  Conciseness & Structure · 10%The description is concise and front-loaded: it starts with the core purpose, then usage guidance, then behavioral details, and ends with alternatives. Every sentence adds value, with no fluff. It's well-structured and efficient.

  4

  Contextual Completeness · 10%Given the tool's moderate complexity (2 params, batch mode, symlink handling) and the presence of annotations (readOnlyHint) and full schema coverage, the description is quite complete. It covers when to use, what it returns, and edge cases (missing paths, symlinks). It doesn't have an output schema, so the description's mention of return fields is helpful. Minor gaps: it doesn't specify whether the tool works on directories (though 'ls -ld' implies it does) or how permissions are formatted, but these are minor. A 4 is justified.

  params

  2 (0 required, 100% described)

  annotations

  readOnly=true openWorld=false

  output schema

  no

  cost

  0

  bytes

  1076

  hash

  a601bfaca18649a0

• undo

  554455A4.7

  This is a well-crafted description that clearly explains the tool's purpose, usage constraints, and behavioral nuances. It effectively complements the schema and annotations, providing the agent with all necessary information to invoke the tool correctly, including edge cases like HTTP limitations and conditional restoration.

  5

  Purpose Clarity · 25%The description clearly states the tool reverts earlier mutating tool calls by undo id or steps, which is specific and distinguishes it from siblings like delete or edit. It also mentions the key constraint of not using both id and steps, and the HTTP limitation.

  5

  Usage Guidelines · 20%It explicitly says when to use (rolling back recent file changes) and provides guidance on using dryRun to inspect history without reverting. It also notes the HTTP-specific requirement for an undo id, which helps the agent choose the right invocation method.

  4

  Behavioral Transparency · 20%The description adds important behavioral details beyond the destructiveHint annotation: it explains that files are only restored if unchanged since the target call, and that modified files are skipped with explanation. It also discloses the return of restored and skipped paths, which is useful context. However, it doesn't detail what happens to non-file resources or the exact error behavior, but the annotation already covers destructiveness.

  4

  Parameter Semantics · 15%The schema already provides descriptions for all three parameters (id, steps, dryRun), and the description adds context on how they interact (not both, HTTP limitation). The dryRun parameter's schema description is already detailed, and the description reinforces its purpose. This adds value beyond the schema, so a 4 is appropriate.

  5

  Conciseness & Structure · 10%The description is concise, with each sentence adding critical information: the core action, usage guidance, behavioral caveat, HTTP constraint, and return value. It is well-structured and front-loaded with the primary purpose.

  5

  Contextual Completeness · 10%Given the tool's complexity (multiple modes, HTTP restrictions, conditional restoration), the description covers all essential aspects: how to specify what to undo, the dryRun option, the restoration condition, and the return format. The schema covers parameter details, and the description fills in the behavioral gaps, making it complete for an agent to use correctly.

  params

  3 (0 required, 100% described)

  annotations

  readOnly=false destructive=true openWorld=false

  output schema

  no

  cost

  0

  bytes

  1171

  hash

  b8ea285f6ec3bdfa

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

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