Your MCP server's tools are confusing your agent. I built a linter that scores them.

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?