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

> Source: <https://dev.to/haoli/your-mcp-servers-tools-are-confusing-your-agent-i-built-a-linter-that-scores-them-4j4d>
> Published: 2026-10-01 18:03:32+00:00

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](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?