The Happy Path Bias
Read most MCP server READMEs and you'll learn exactly how to set the server up and what it can do in ideal conditions. "Query any SQL database." "Read and write files." "Search the web." These capability descriptions are accurate but incomplete. They don't tell you what happens when things go sideways.
What happens when you query a table with 10 million rows? What happens when the database connection drops mid-query? What file sizes are too large to process? Which SQL dialects are actually supported? The answers to these questions are usually discovered through painful trial and error.
What Failure Documentation Should Include
Known limitations: "Maximum result set size is 10,000 rows. Larger queries will be truncated." "Binary files are not supported and will return an error." These set expectations so users don't waste time discovering limits through failures.
Common error scenarios: "If you see 'connection timeout,' the database server may be unreachable. Check that the host and port in your configuration are correct." This saves debugging time by providing the most likely explanation for common errors.
Edge cases: "Queries with BLOB columns will fail because binary data can't be serialized to JSON." "File paths with Unicode characters may not work on Windows." These prevent the specific surprises that cause the most frustration.
The Trust Effect
Counterintuitively, documenting failures builds trust. When a README honestly says "this server works great for queries under 10,000 rows but struggles with larger result sets," you trust the author more than one that claims unlimited capabilities. You also make a better-informed adoption decision.
Good failure documentation is a developer experience investment. Users who understand the tool's limits use it within those limits and have a good experience. Users who discover limits through failure have a bad experience and might switch to an alternative.
Related Reading
- Why MCP Server Discovery Is Harder Than It Looks
- How Error Messages from MCP Servers Affect Agent Behavior
- Why Developer Experience Matters for AI Tool Adoption
Browse MCP servers on Skillful.sh. Search 137,000+ AI tools.