Schema quality: missing property descriptions across official MCP servers #3669
Description
Summary
While running automated quality checks against the official MCP reference servers, I found that most servers are missing description fields on their tool input schema properties. This matters because LLMs use these descriptions to understand how to call tools correctly — without them, the model has to guess what each parameter means from the name alone.
Findings
Tested with MCP Observatory v0.13.0 on 2026-03-22.
server-filesystem (11 tools, 18 missing descriptions)
Every tool property across all 11 tools lacks a description:
read_file:pathmissing descriptionwrite_file:path,contentmissing descriptionsedit_file:path,editsmissing descriptionscreate_directory:pathmissing descriptionlist_directory:pathmissing descriptiondirectory_tree:path,excludePatternsmissing descriptionsmove_file:source,destinationmissing descriptionssearch_files:path,pattern,excludePatternsmissing descriptionsget_file_info:pathmissing description
server-everything (13 tools, 5 missing descriptions + 4 missing required)
get-resource-reference:resourceTypemissing description- 4 tools missing
requiredarray:get-resource-links,get-resource-reference,gzip-file-as-resource,trigger-long-running-operation - Resource
README.md.gzmissing description
server-memory (6 tools, 4 missing descriptions)
create_entities:entitiesmissing descriptioncreate_relations:relationsmissing descriptionadd_observations:observationsmissing descriptiondelete_observations:deletionsmissing description
Why this matters
The MCP spec recommends tool input schemas follow JSON Schema with descriptions. When an LLM sees:
{ "type": "string" }vs:
{ "type": "string", "description": "Absolute or relative path to the file to read" }The second version produces significantly better tool-use accuracy. Since these are the reference implementations that other server authors look at, setting a good example here would improve schema quality across the ecosystem.
Suggested fix
Add description fields to all tool input schema properties. Example for read_file:
inputSchema: {
type: "object",
properties: {
path: {
type: "string",
description: "Absolute or relative path to the file to read"
}
},
required: ["path"]
}Reproduction
npx @kryptosai/mcp-observatory score npx -y @modelcontextprotocol/server-filesystem /tmp
npx @kryptosai/mcp-observatory score npx -y @modelcontextprotocol/server-everything
npx @kryptosai/mcp-observatory score npx -y @modelcontextprotocol/server-memory
Activity
khalidsaidi commentedon Mar 24, 2026
radeshgovind-2005 commentedon Mar 27, 2026
Hi, I've submitted PR #3732 which addresses all the points raised in this issue.
jashshah999 commentedon May 5, 2026
PengSpirit commentedon May 9, 2026
Ben-Home commentedon Jun 13, 2026
cliffhall commentedon Oct 19, 2026
Triage: Priority Low (total 4)
Board: Servers V2 (#43), Status
Incoming, awaiting maintainer review (no milestone yet). Part of the backlog triage in #4875.cliffhall commentedon Oct 20, 2026
Prior work, from the PR backlog triage (#4877). These outside pull requests addressed this issue against the pre-refactor code:
They are being closed as part of the backlog triage in #4875, since the repository now takes issues rather than outside PRs and their diffs predate the v2 refactor. They stay readable and serve as prototypes for the fix here. Thank you to their authors.
Pranav-Nexus commentedon Oct 21, 2026
v2 Codebase Audit (
origin/main/v2.0.0) & Ready-to-Run Factory PromptFollowing the v2 spec refactor (#4857) and backlog triage (#4875 / #4877), I audited the current v2 codebase across all three servers (
filesystem,memory,everything) to see what was already resolved by the refactor and what still lacks property descriptions under theAGENTS.mdrule ("Validate tool input with Zod schemas, with descriptions on the fields").1. What
v2Already Fixed vs. What Remainssrc/filesystem/server.ts(16 properties across 11 tools still missing.describe()):jsonSchema2020(<Tool>ArgsSchema.shape)directly toinputSchema, so adding.describe()on the top-level Zod schemas automatically populates the advertised2020-12JSON Schema. However,read_fileandread_text_filestill inline a duplicate{ path, tail, head }object insidejsonSchema2020({...})instead of passingReadTextFileArgsSchema.shape.ReadTextFileArgsSchema:pathReadMediaFileArgsSchema:pathWriteFileArgsSchema:path,contentEditFileArgsSchema:path,editsCreateDirectoryArgsSchema:pathListDirectoryArgsSchema:pathListDirectoryWithSizesArgsSchema:pathDirectoryTreeArgsSchema:path,excludePatternsMoveFileArgsSchema:source,destinationSearchFilesArgsSchema:path,pattern,excludePatternsGetFileInfoArgsSchema:pathsearch_filesvsdirectory_treedescriptions:search_files(lib.tssearchFilesWithValidation), bothpatternandexcludePatternsare evaluated directly viaminimatch(relativePath, ..., { dot: true })—meaning a bare directory name likeexcludePatterns: ["node_modules"]only excludes the top-level directory entry itself while still traversing children unless**/node_modules/**is passed (and a bare filenamepattern: "foo.ts"only matches at the root ofpathunless**/foo.tsor*.tsis used).directory_tree(server.tsbuildTree) auto-expands non-wildcardexcludePatternsto**/${pattern}and**/${pattern}/**. Calling out the expected glob syntax (e.g.,'*.ts','**/*.json',['**/node_modules/**']) in the parameter descriptions prevents first-turn agent retries.src/memory/index.ts(5 top-level properties still missing.describe()):delete_entities(entityNames),delete_relations(relations), andopen_nodes(names) already have.describe()in v2..describe():SearchNodesQuerySchema(search_nodes->query)create_entities(entities: z.array(EntitySchema))create_relations(relations: z.array(RelationSchema))add_observations(observations: z.array(...))delete_observations(deletions: z.array(...))src/everything/(1 property missing.describe()):requiredarrays and resource descriptions noted in the original v1 report are already resolved in v2.src/everything/tools/get-resource-reference.ts->GetResourceReferenceSchema.shape.resourceType(z.enum([RESOURCE_TYPE_TEXT, RESOURCE_TYPE_BLOB]).default(RESOURCE_TYPE_TEXT)) is still missing.describe().2. Prompt for the Agentic Workflow (
CONTRIBUTING.mdformat)Per
CONTRIBUTING.md, here is a self-contained prompt that can be fed directly into the repository's workflow to close #3669 with protocol-level test assertions inserver-tools.test.ts:jajazpua commentedon Nov 1, 2026
jajazpua commentedon Nov 4, 2026
Because the measurements cited here were made with MCP Observatory v0.13.0 in March 2026, I'd rerun the current reference servers before attributing all the same missing-description counts to their latest versions.
For a safe patch review, compare the actual
tools/listmanifests before/after: (1) verify each newly described field points to the same schema path, (2) ensure therequiredarrays, types, enum values and defaults remain unchanged unless intentionally fixed, and (3) score description coverage separately from behavioral/schema compatibility.That would distinguish a documentation-quality improvement from a possibly breaking contract edit. This is a proposed verification method; I haven't rerun Observatory against current server releases.
test(everything): check input descriptions on both protocol eras (#3669)
Merge pull request #5475 from modelcontextprotocol/v2/feat/3669-schem…
cliffhall commentedon Nov 5, 2026
Fixed by #5475: every tool input property in the filesystem, memory and everything servers now has a description, and a test in each TypeScript server fails on any property without one. The Python servers were already fully described.
fix(filesystem): state the shared excludePatterns rule in both schemas
feat: describe every tool input property (modelcontextprotocol#3669)