Building Better MCP Tools
Patterns and signals from evaluating 2,000+ MCP servers. Each issue links to Arcade's Agentic Tool Patterns.
Top Issues Across the Ecosystem
| Issue | Occurrences | Agent impact | Pattern |
|---|---|---|---|
| Missing descriptions | 6,568 | Agents guess what a tool does, when to use it, and what it returns - leading to wrong tool selection and wasted calls | Tool Description → |
| No error handling guidance | 1,899 | 400/500 errors without context cause unrecoverable retry loops in agent workflows | Recovery Guide → |
| No output schema | 1,407 | Agents can't plan multi-step workflows because they don't know what a tool returns | Response Shaper → |
| No pagination guidance | 694 | Unbounded list returns exceed context windows and degrade agent performance | Paginated Result → |
| Missing parameter constraints | 691 | Free-form strings where enums or ranges apply - agents produce invalid values | Constrained Input → |
| Destructive ops unguarded | 417 | Delete and update tools without confirmation - agents invoke irreversible actions | Confirmation Request → |
| Naming inconsistencies | 401 | Mixed casing and ambiguous verbs reduce tool discoverability for agents | Tool Description → |
| Missing tool annotations | 137 | No hints about whether a tool reads or writes - agents can't assess risk before calling | Performance Hint → |
Agentic Tool Patterns
Tool Interface
Execution
Made improvements? Submit for rescoring. We're building deeper analysis and automated suggestions.