{"slug": "your-mcp-server-s-tools-are-confusing-your-agent-i-built-a-linter-that-scores", "title": "Your MCP server's tools are confusing your agent. I built a linter that scores them.", "summary": "A developer has released mcp-lint, an open-source Python design linter for Model Context Protocol servers that scores a server's tools/list output out of 100 and flags issues such as missing descriptions, vague names, unpaginated list tools, destructive tools without confirmation hints, and empty or bloated schemas. The stdlib-only, MIT-licensed tool supports a --fail-under flag to act as a CI gate, and is positioned as a design-quality counterpart to the author's earlier mcp-tax token-cost auditor.", "body_md": "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?\"\n\nThat 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.\n\nSo 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:\n\n```\nmcp-lint audit — 4 tool(s), design score: 85/100\n\n  handle_data  (score 64/100)\n    - [missing-description] tool has no description (-20)\n    - [vague-name] name contains a vague filler word (-6)\n    - [empty-schema] inputSchema has no properties at all (-10)\n\n  list_issues  (score 90/100)\n    - [no-pagination] list-style tool has no limit/offset/cursor/page param (-10)\n\n  delete_repo  (score 85/100)\n    - [destructive-no-confirm] destructive tool description has no confirm/approve/dry-run hint (-15)\n```\n\nEight 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.\n\n```\ngit clone https://github.com/hahahahahahahahah6/mcp-lint\ncd mcp-lint\npython3 mcp_lint.py audit tools.json              # human-readable table\npython3 mcp_lint.py audit tools.json --json       # machine-readable\npython3 mcp_lint.py audit tools.json --fail-under 80   # exit 1 if score < 80 (CI gate)\n```\n\n`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.\n\nIt'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.\n\nStdlib only, Python 3.9+. MIT licensed.\n\nRepo: [https://github.com/hahahahahahahahah6/mcp-lint](https://github.com/hahahahahahahahah6/mcp-lint)\n\nWhat's the worst-designed MCP tool you've seen in the wild — the one your agent kept calling wrong?", "url": "https://wpnews.pro/news/your-mcp-server-s-tools-are-confusing-your-agent-i-built-a-linter-that-scores", "canonical_source": "https://dev.to/haoli/your-mcp-servers-tools-are-confusing-your-agent-i-built-a-linter-that-scores-them-4j4d", "published_at": "2026-10-01 18:03:32+00:00", "updated_at": "2026-10-01 18:14:42.930317+00:00", "lang": "en", "topics": ["ai-agents", "agent-protocols", "developer-tools", "ai-tools"], "entities": ["mcp-lint", "Model Context Protocol", "mcp-tax", "GitHub"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/your-mcp-server-s-tools-are-confusing-your-agent-i-built-a-linter-that-scores", "markdown": "https://wpnews.pro/news/your-mcp-server-s-tools-are-confusing-your-agent-i-built-a-linter-that-scores.md", "text": "https://wpnews.pro/news/your-mcp-server-s-tools-are-confusing-your-agent-i-built-a-linter-that-scores.txt", "jsonld": "https://wpnews.pro/news/your-mcp-server-s-tools-are-confusing-your-agent-i-built-a-linter-that-scores.jsonld"}}