Run hscli as an MCP server for AI agents to call Help Scout commands as native tools
8 tools with basic schemas and descriptions, but significant gaps in parameter documentation and output schema clarity. Tool names follow verb_noun convention (alias_list, auth_login, api). Descriptions are present but generic (10-50 chars, below the 50-200 char LLM-optimized baseline). Most parameters lack descriptions entirely. No documented output schemas. Error handling and recovery guidance absent. The 'api' tool is particularly problematic: it accepts arbitrary HTTP methods and paths, creating a high-risk surface with minimal guardrails.
List all configured aliases
Create or update an alias
Remove an alias
Make a raw API request
Authenticate with Help Scout
Log out and remove stored credentials
Force-refresh the stored access token
Configure your own Help Scout OAuth app
Descriptions are too short (10-50 chars vs. 50-200 char baseline). LLMs cannot determine when to select tools or distinguish similar ones (e.g., auth_login vs auth_setup both say 'Authenticate').
Most parameters lack descriptions. 'client-credentials' in auth_login has a description, but 'name' and 'command' in alias_set lack context on format/constraints. LLMs cannot infer parameter meaning from names alone.
'api' tool is a generic HTTP gateway accepting arbitrary methods and paths. No input validation, no rate limiting, no permission checks. High risk for prompt injection and unintended API calls. Violates single-responsibility principle.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | F | 49 | 2026-07-28+ | v2 |
No documented output schemas for any tool. LLMs cannot plan downstream calls or extract required fields. E.g., alias_list returns a list but structure is undocumented.
No error handling guidance. Tools do not indicate what errors are retryable, user-fixable, or fatal. No recovery suggestions (e.g., 'If login fails, try auth_setup first').