filesystem: tool parameters missing descriptions (agents guess at values)

All 14 tools in the filesystem server define required parameters with no description field in the JSON schema. For example, read_file declares path as a required string but doesn't specify whether it expects a relative path, absolute path, glob pattern, or file URI.

This matters because AI agents use parameter descriptions to decide what values to pass. Without descriptions, agents must infer from the parameter name alone, which leads to incorrect tool calls (wrong path format, missing trailing slashes, etc.).

Affected parameters (16 required params across 14 tools):

Tool	Parameter	Type
read_file	path	string
read_text_file	path	string
read_media_file	path	string
write_file	path, content	string
edit_file	path, edits	string, array
create_directory	path	string
list_directory	path	string
list_directory_with_sizes	path	string
directory_tree	path	string
move_file	source, destination	string
search_files	path, pattern	string
get_file_info	path	string

Example of what helps agents (from other MCP servers):

{
  "name": "path",
  "type": "string",
  "description": "Absolute path to the file. Must be within the allowed directories."
}

vs what filesystem currently returns:

{
  "name": "path",
  "type": "string"
}

Found via static schema analysis (mcp-assert lint).

Same issue affects mcp-server-git and server-memory in this repo:

mcp-server-git (12 tools): 22 errors, 23 warnings. Every parameter in all 12 tools is undescribed. Agents don't know if repo_path is absolute or relative, if ref is a branch name or SHA, if diff_unified is a number or a flag.

server-memory (9 tools): 4 errors, 1 warning. create_entities, create_relations, add_observations, delete_observations all have required parameters with no description.

$ mcp-assert lint --server "uvx mcp-server-git --repository /path/to/repo"
mcp-git: 12 tools, 22 errors, 23 warnings

$ mcp-assert lint --server "npx -y @modelcontextprotocol/server-memory"
memory-server: 9 tools, 4 errors, 1 warning

This is a systemic pattern across the official servers: schemas define parameter types but omit descriptions. The most impactful fix would be adding descriptions to required parameters in the servers that agents use most frequently (filesystem, git, memory).

I built mcpeval specifically for catching these kinds of schema issues automatically. It flags missing parameter descriptions, missing enums on categorical fields, and generic param names that cause agents to guess.

$ mcpeval check filesystem_server.json
  Schema Score: 72/100 (C)
  !  read_file    Parameter 'path' has no description
  !  edit_file    Parameter 'dryRun' has no description

Could be useful as a pre-commit hook or CI check to prevent these from shipping.

Closing as a duplicate of #3984; let's track it there.

Navigation Menu

Repository navigation

filesystem: tool parameters missing descriptions (agents guess at values) #4095

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

filesystem: tool parameters missing descriptions (agents guess at values) #4095

Description

Activity

blackwell-systems commented on May 3, 2026

jashshah999 commented on May 5, 2026

PengSpirit commented on May 9, 2026

localden commented on Jul 30, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions