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?

Comments

[arobakid]

static design checks on tools/list are overdue; missing descriptions and unpaginated list tools cause most of the wrong-tool calls I see. I'd love a rule for near-duplicate tool names, which confuse models more than a missing description. We do something adjacent at Elva (getelva.ai): AI labeling and API scoring on the OpenAPI spec before it becomes MCP tools, so naming problems surface upstream.

[hao li]

Fully agree on near-duplicates — that's the nastiest failure mode in practice. A missing description at least makes the model pause; two tools named search_items and item_search with identical shapes make it confidently guess. I'd implement it as a pairwise similarity check over names and descriptions, flagging things like word-order swaps or Levenshtein-close names with overlapping input shapes. Catching it upstream in the OpenAPI spec is the right layer — by the time it's MCP tools, the naming damage is done. Adding this to the rule list, thanks.