mcp-descriptions.json

{
  "descriptions": {
    "agent-fields_list": "List the configured agent profile fields (the schema behind agent records). Returns an array of field definitions with id, label, name, type, choices, and required flag. Use this before creating or updating agents when you need to know which custom fields exist and their valid values.",
    "agents_delete": "Permanently delete an agent (destructive — the agent's record and group memberships are removed). Required: id (numeric agent ID). Returns 204 No Content on success. Prefer agents_deactivate if you only need to disable login; deletion cannot be undone.",
    "agents_get": "Fetch a single agent's full profile by numeric ID. Required: id. Returns the agent object with first_name, last_name, email, mobile_phone, work_phone, ticket_scope, group_ids, role_ids, occasional flag, signature, and active state. Use this when you already have an ID; use agents_list to search by attribute.",
    "agents_list": "List all agents in the workspace with pagination. Optional: query (Freshservice query DSL, e.g. \"email:'user@example.com'\"), page, per_page (max 100). Returns an array of agents with id, email, names, group_ids, role_ids, and active flag. Use changes_filter-style query for attribute search; agents_get when you already have an ID.",
    "assets_delete": "Soft-delete an asset by its display ID (destructive — the asset is hidden from default lists but can be restored within 30 days via assets_restore). Required: display_id (CMDB display identifier, not the internal numeric ID). Returns 204 No Content.",
    "assets_get": "Fetch a single asset's full CMDB record by display ID. Required: display_id (e.g. \"1\", \"42\"). Returns the asset with name, asset_type_id, asset_tag, impact, usage_type, user_id, location_id, agent_id, and the full type_fields map (custom CMDB attributes vary by asset type).",
    "assets_components_list-asset": "List the hardware/software components attached to a single asset (CPU, memory, disks, installed apps depending on asset type). Required: display_id. Returns an array of component objects with id, component_type, and component_data. Use when triaging hardware tickets or building a software inventory report.",
    "assets_contracts_list-asset": "List contracts (warranty, lease, maintenance) linked to a single asset. Required: display_id. Returns an array of contract summaries with id, name, contract_type, start_date, end_date, and status. Use to check warranty/support coverage before approving a repair or replacement ticket.",
    "assets_requests_list-asset": "List service-request and incident tickets that reference a single asset. Required: display_id. Returns an array of ticket summaries with id, subject, status, priority, and created_at. Use to gather an asset's full ticket history when diagnosing a recurring hardware issue.",
    "assets_restore_asset": "Restore a previously soft-deleted asset back to active status. Required: display_id. Returns 204 No Content. Use within 30 days of assets_delete; after the retention window the asset is gone permanently.",
    "canned-responses_get": "Fetch a single canned-response template by ID. Required: id. Returns the response with title, content (HTML or plain), content_html, visibility (folder_id), and group_ids who can use it. Use to preview a template before inserting it into a ticket reply.",
    "canned-responses_list": "List all canned-response templates the calling agent can access. Returns an array of templates with id, title, content_summary, folder_id, and visibility. Use to surface reply suggestions when an agent is composing a ticket response.",
    "change-form-fields_list": "List the configured change-record form fields (the schema behind change records, including any custom fields). Returns an array of field definitions with id, label, name, type, choices, required, position. Use before creating or updating changes to discover available custom fields.",
    "changes_delete": "Permanently delete a change record (destructive — change history, notes, tasks, and approvals are removed). Required: id (numeric change ID). Returns 204 No Content. Cannot be undone; prefer setting status to cancelled if you only need to abort an unapproved change.",
    "changes_filter": "Search changes via the Freshservice query DSL (richer than list filters). Required: query (e.g. \"status:1 AND priority:>2\"). Returns an array of change summaries with id, subject, status, priority, planned_start_date, planned_end_date, requester_id, and assigned_agent_id. Prefer this over changes_list when you need attribute filters beyond pagination.",
    "changes_get": "Fetch a single change record's full payload by ID. Required: id. Returns the change with subject, description_text, status, priority, impact, risk, change_type, planned_start_date, planned_end_date, requester_id, agent_id, group_id, department_id, approvers, and custom_fields. Use changes_list or changes_filter to discover IDs.",
    "changes_list": "List changes in the workspace, paginated. Optional: page, per_page (max 100). Returns an array of changes with id, subject, status, priority, planned dates, and assigned agent. For attribute filters (status, priority, date range) use changes_filter; this is the dumb pagination endpoint.",
    "changes_notes_create-change": "Add an internal note (not a customer-visible reply) to a change record. Required: id (change ID) and body (note text, HTML allowed). Returns the new note with id, body, created_at, and user_id. Use to record approval discussion or post-implementation review notes; visible only to agents.",
    "changes_notes_list-change": "List all internal notes attached to a single change. Required: id (change ID). Returns an array of notes with id, body, user_id, created_at. Use to read the change's discussion history before approving or rolling back.",
    "changes_tasks_delete-change": "Permanently remove a task line-item from a change's task list (destructive). Required: id (change ID) and task_id (task ID within that change). Returns 204 No Content. Useful when restructuring a change plan; cannot be undone.",
    "changes_tasks_list-change": "List the implementation tasks attached to a single change record. Required: id (change ID). Returns an array of tasks with id, title, status, due_date, agent_id, and notify_before_seconds. Use to surface the change's runbook before approving or executing it.",
    "changes_time-entries_list-change": "List billable/non-billable time entries logged against a single change. Required: id (change ID). Returns an array of time entries with id, time_spent (HH:MM), executed_at, billable flag, note, and agent_id. Use for change-effort reporting or labor cost accounting.",
    "contracts_list": "List vendor and warranty contracts in the workspace. Returns an array of contracts with id, name, contract_type, start_date, end_date, status (active/expired/about_to_expire), vendor_id, and cost. Use to surface expiring contracts in a renewal workflow.",
    "departments_list": "List the organization's departments (used to scope tickets, agents, and assets). Returns an array of departments with id, name, description, head_user_id, and prime_user_id. Use when building a department dropdown or aggregating ticket metrics by department.",
    "groups_create": "Create a new agent group (a routing target for tickets, e.g. \"Network\", \"Hardware\"). Required: name. Optional: description, escalate_to (agent ID), unassigned_for (auto-escalate delay), business_hours_id, agent_ids. Returns the new group with id, created_at. Use during onboarding to mirror a new IT team in Freshservice.",
    "groups_get": "Fetch a single agent group by ID. Required: id. Returns the group with name, description, agent_ids, escalate_to, unassigned_for, business_hours_id, and approval_required flag. Use to read current membership before adding/removing agents.",
    "groups_list": "List all agent groups in the workspace. Returns an array of groups with id, name, description, agent_ids count, and business_hours_id. Use to build a ticket-assignment picker or to audit group membership.",
    "locations_list": "List physical/logical locations defined in the workspace (sites, floors, rooms). Returns an array of locations with id, name, parent_location_id, contact_name, email, phone, and address fields. Use when filtering assets or tickets by site.",
    "products_create": "Register a new product (asset model template, e.g. \"MacBook Pro 16-inch 2024\"). Required: name. Optional: description, asset_type_id, manufacturer, status (in_production/retired), mode_of_procurement. Returns the new product with id. Use during procurement onboarding before creating individual asset records of that model.",
    "products_get": "Fetch a single product (asset model) by ID. Required: id. Returns the product with name, description, asset_type_id, manufacturer, status, mode_of_procurement, created_at. Use to inspect a model before linking new assets to it.",
    "products_list": "List all product (asset model) records. Returns an array of products with id, name, asset_type_id, manufacturer, status. Use to populate a model dropdown when bulk-creating assets.",
    "products_update": "Update an existing product (asset model) record. Required: id. Optional: name, description, status, mode_of_procurement, manufacturer. Returns the updated product. Use to retire a model (status=retired) or correct manufacturer metadata.",
    "requester-fields_list": "List the configured requester (end-user) profile fields, including custom fields. Returns an array of field definitions with id, label, name, type, choices, required, position. Use before creating or updating requesters to discover the valid custom-field set.",
    "requesters_deactivate": "Deactivate a requester (end-user) so they can no longer log new tickets, without deleting their ticket history (destructive in the sense of revoking access). Required: id. Returns 204 No Content. Prefer over deletion when an employee leaves; their ticket history stays intact.",
    "requesters_get": "Fetch a single requester (end-user) by ID. Required: id. Returns the requester with first_name, last_name, primary_email, secondary_emails, work_phone, mobile_phone_number, department_ids, location_id, reporting_manager_id, and active flag. Use to look up the person behind a ticket's requester_id.",
    "requesters_list": "List requesters (end-users) with optional attribute search and pagination. Optional: query (Freshservice DSL, e.g. \"primary_email:'user@example.com'\"), page, per_page (max 100). Returns an array of requester summaries. Use for email-based lookup before creating a duplicate user.",
    "requesters_convert-to-agent_convert-requester-to-agent": "Promote a requester (end-user) to an agent account, preserving their ticket history. Required: id (requester ID). Returns the new agent record with id, email, group/role assignments. Use when an end-user joins the IT team; preserves their submitted-ticket history under their new agent identity.",
    "requesters_reactivate_requester": "Re-enable a previously deactivated requester so they can log new tickets again. Required: id (requester ID). Returns 204 No Content. The mirror operation to requesters_deactivate.",
    "service-catalog_list-items": "List items available in the service catalog (request templates end-users can submit). Optional: page, per_page. Returns an array of catalog items with id, name, short_description, category_id, product_id, delivery_time, cost. Use to populate a self-service portal picker or audit the catalog.",
    "solutions_get-category": "Fetch a single knowledge-base category by ID. Required: id. Returns the category with name, description, position, default_category flag, workspace_id, and visible_in_portal flag. Use to inspect category metadata before creating articles under it.",
    "solutions_list-categories": "List all knowledge-base categories (the top level of the KB taxonomy). Returns an array of categories with id, name, description, position, and default_category flag. Use to build a KB navigation tree or to find a category_id when creating an article.",
    "ticket-form-fields_list": "List the configured ticket form fields, including custom fields. Returns an array of field definitions with id, label, name, type, choices, required, position. Use before creating or updating tickets to discover the valid custom-field set and choice values.",
    "tickets_delete": "Soft-delete a ticket by ID (destructive — moves to trash; recoverable within 30 days via tickets_restore). Required: id. Returns 204 No Content. Use to remove spam or duplicate tickets; the requester's notification trail is preserved in audit logs.",
    "tickets_list": "List tickets in the workspace, paginated. Optional: page, per_page (max 100), order_type (asc/desc). Returns an array of ticket summaries with id, subject, status, priority, requester_id, responder_id, group_id, created_at, due_by. For attribute filtering (status, priority, custom fields) use tickets_filter; this is the unfiltered paginated endpoint.",
    "tickets_activities_list-ticket": "Read the chronological activity log for a single ticket (status changes, assignments, field edits, replies). Required: id. Returns an array of activity entries with actor_id, action, performed_at, and details map. Use for audit trails or to reconstruct what happened on a ticket.",
    "tickets_conversations_list-ticket": "List all conversation entries (public replies and private notes) on a single ticket. Required: id. Returns an array of conversations with id, body, body_text, from_email, to_emails, private flag, attachments, and user_id. Use to read the full thread context before crafting a reply.",
    "tickets_restore_ticket": "Restore a previously soft-deleted ticket from trash back to active status. Required: id. Returns 204 No Content. Use within 30 days of tickets_delete; after the retention window the ticket is gone permanently.",
    "tickets_tasks_delete-ticket": "Permanently remove a task line-item from a ticket's task list (destructive). Required: id (ticket ID) and task_id. Returns 204 No Content. Useful for cleaning up obsolete checklist items.",
    "tickets_tasks_get-ticket": "Fetch a single task from a ticket's task list by IDs. Required: id (ticket ID) and task_id. Returns the task with title, status (open/in_progress/completed), due_date, agent_id, notify_before_seconds, group_id. Use to inspect a task's current state before updating it.",
    "tickets_tasks_list-ticket": "List the checklist tasks attached to a single ticket. Required: id (ticket ID). Returns an array of tasks with id, title, status, due_date, agent_id, group_id. Use to surface a ticket's runbook or to check task completion before resolving the parent ticket.",
    "tickets_time-entries_list-ticket": "List billable/non-billable time entries logged against a single ticket. Required: id (ticket ID). Returns an array of time entries with id, time_spent (HH:MM), executed_at, billable flag, note, agent_id. Use for ticket-effort reporting or labor cost accounting.",
    "vendors_list": "List vendor/supplier organizations registered for procurement and contract tracking. Returns an array of vendors with id, name, description, address, primary_contact_id, email, phone, and category. Use when filtering contracts or purchase orders by supplier.",
    "workspaces_list": "List workspaces (top-level tenants) accessible to the calling token. Returns an array of workspaces with id, name, description, primary flag, and created_at. Use to discover the workspace_id required by other tools in multi-workspace accounts; single-workspace accounts always have one entry with primary=true."
  }
}