We read the schemas of 4,951 public MCP servers

Description and use

The study found that 21.8 % of parameters lack descriptions, 17.4 % of tools have indistinct descriptions, and schema sizes can reach 280,000 tokens. Recommendations for improving descriptions and collision checks were provided.

Problem

MCP server tool schemas often lack descriptive clarity, leading to ambiguous tool selection and potential model errors.

Outcome

The study revealed widespread schema deficiencies, quantified their prevalence, and offered concrete guidance for improving tool and parameter descriptions to reduce model ambiguity.

Workflow

• Collect tool schemas from Smithery registry or local servers
• Validate registry data against real server responses
• Analyze parameter descriptions for presence and distinctiveness
• Compute tool description distinctiveness per server
• Measure token cost of schema transmission
• Identify enum usage and enforceability
• Generate actionable recommendations for server maintainers

Evidence

59,038 of 270,487 parameters — 21.8% — ship with no description.

Source

17.4% of tools are exactly zero distinctive.

Source

Median server: 4,991 bytes, roughly 1,250 tokens

Source