Model Context Protocol server for Freshdesk ticketing and contact management integration
The server defines 9 tools with generally clear verb-noun naming (create_ticket, list_tickets, get_ticket, update_ticket, delete_ticket, search_tickets, reply_to_ticket, get_ticket_conversations, get_contact_by_email). All tools have descriptions and input schemas with typed parameters. However, several critical gaps reduce quality: (1) Output schemas are not documented, responses are inferred from code but not formally specified in tool definitions; (2) Descriptions lack actionable guidance about when to use similar tools (e.g., list_tickets vs search_tickets guidance appears in descriptions but not systematically); (3) No enums for status/priority fields, tools accept free-form strings or integers, inviting LLM errors; (4) Error handling is basic (returns generic error dicts) with no recovery guidance; (5) Parameter descriptions reference example IDs/emails inline (e.g., 'e.g. [email protected]') which LLMs may reuse literally; (6) No mention of destructive operation confirmation for delete_ticket; (7) Response field naming inconsistencies (some return 'success' boolean, others omit it). Per-tool averaging: 9 tools score 60-65 individually, resulting in ~62 overall.
Creates a support ticket for a customer.
Permanently deletes a ticket.
Looks up a customer contact by email address.
Retrieves details of a single ticket.
Shows all conversations (replies and notes) on a ticket.
Use when the user asks to list, show, or count tickets by their status. Do NOT use for keyword or subject searches — use search_tickets instead.
No documented output schemas. Response structure is inferred from code (success/ticket_id/count/results) but not formally declared to the LLM. Without documented output shapes, LLMs cannot reliably extract fields or plan downstream tool calls.
Status and priority parameters accept free-form strings or integers without enum constraints. Code internally maps 'open'→2, 'pending'→3, etc., but no JSON Schema enum is declared. LLMs cannot see valid options and may hallucinate invalid values like 'on_hold' or status=10.
Inline example values in parameter descriptions (e.g., 'email e.g. john@com', 'ticket_id e.g. 33'). LLMs frequently reuse example values literally in real calls, causing failures or unintended lookups. Replace with formal constraints (pattern, minLength) or remove examples entirely.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 53 | 2026-07-28+ | v2 |
Sends a public reply to the customer via email. Use when asked to "reply", "write to the customer", "notify the requester". For internal notes use update_ticket with the note parameter.
Use when the user asks to find, search, or look up tickets by a word or topic. Do NOT use to filter by status — use list_tickets instead.
Updates a ticket status/priority or adds an internal note. For replies to the customer use reply_to_ticket instead.
delete_ticket lacks error handling or confirmation guidance. No mention of dry-run, confirmation step, or undo capability. Agents can permanently delete tickets without warning. Destructive operations should require explicit confirmation or support recovery.
Error responses are minimal (e.g., 'API error 400: {raw_text}'). No recovery guidance. When list_tickets fails with a bad status value, it returns 'Invalid status "pending"... Use: open, pending, resolved, closed' (good), but other tools return bare HTTP errors. Inconsistent error classification.
Response field naming inconsistency. Some tools return {'success': True, ...}, others return {'count': ..., 'tickets': [...]}. Inconsistent 'success' field presence makes parsing brittle. All should consistently include a 'success' or 'error' field.
No pagination for list_tickets or search_tickets. Code fetches 'per_page': 30 but does not expose limit/offset/page parameters to the LLM. If a user asks to 'list all open tickets', the tool silently caps at 30 results without the agent knowing there are more.
Tool descriptions mention usage guidance (e.g., 'Do NOT use for keyword searches') but this is scattered and inconsistent. Description for list_tickets is good, but get_ticket, update_ticket, and others lack similar context about when to use them vs alternatives.