Over on r/mcp, a recurring complaint from people wiring up their first servers goes something like: "I wired up 4–5 MCP servers and I still can't design one from scratch. When is something a tool vs a resource? Why does my agent keep calling the wrong thing?"
That confusion is almost never a transport problem — it's a design problem. Tools with no description. Names like handle_data. List endpoints that dump everything with no pagination. delete_* tools that never hint at confirmation. Bad tool design wastes context and confuses agents, and nobody was checking for it statically.
So I built mcp-lint: a design linter for MCP servers. Point it at your tools/list output and get a design score out of 100, with every finding named:
mcp-lint audit — 4 tool(s), design score: 85/100
handle_data (score 64/100)
- [missing-description] tool has no description (-20)
- [vague-name] name contains a vague filler word (-6)
- [empty-schema] inputSchema has no properties at all (-10)
list_issues (score 90/100)
- [no-pagination] list-style tool has no limit/offset/cursor/page param (-10)
delete_repo (score 85/100)
- [destructive-no-confirm] destructive tool description has no confirm/approve/dry-run hint (-15)
Eight rules total — missing or rambling descriptions (over 600 chars is its own finding: context tax), vague names, unpaginated list tools, destructive tools with no confirmation hint, empty schemas, schema bloat. Each tool starts at 100 and loses points; the server score is the mean.
git clone https://github.com/hahahahahahahahah6/mcp-lint
cd mcp-lint
python3 mcp_lint.py audit tools.json # human-readable table
python3 mcp_lint.py audit tools.json --json # machine-readable
python3 mcp_lint.py audit tools.json --fail-under 80 # exit 1 if score < 80 (CI gate)
tools.json is either a tools/list JSON-RPC result or a bare array of {name, description, inputSchema}. The --fail-under flag makes it a CI gate: score below 80, the build fails.
It's a sibling to mcp-tax (my other tool), different axis: mcp-tax audits token cost — how much context your server burns. mcp-lint audits design quality — whether the tools are shaped well enough for an agent to use correctly. A server can be cheap and still unusable, or well-designed and still expensive. Run both.
Stdlib only, Python 3.9+. MIT licensed.
Repo: https://github.com/hahahahahahahahah6/mcp-lint
What's the worst-designed MCP tool you've seen in the wild — the one your agent kept calling wrong?