Ticket and work-order reporting with Agent MCP

Agent MCP gives a connected AI client five reporting tools for Service Desk tickets and work orders. This reference lists what each tool returns, the questions it can and cannot answer, the filters and grouping rules it applies, and the limits to know before you trust a number. Connecting an AI client to Calm is covered in How Ask Calm and Agent MCP work.

The five reporting tools

Each tool answers a different reporting job. Module-specific tools appear only when the relevant Service Desk or Work Orders capability is available, and every result is subject to your normal site and record access.

Questions each tool answers

Match the population you want to the tool and the interpretation of its counts. The past-month-end row is the one to read before asking for a historical backlog.

Date boundaries

Wrong boundaries are the most common way a period report goes wrong. Every creation and closure window uses inclusive lower bounds and exclusive upper bounds.

• createdFrom and closedFrom are inclusive; createdBefore and closedBefore are exclusive.

• Supply an explicit UTC offset or Z on every boundary. For a September 2026 report on a UK site, use 2026-09-01T00:00:00+01:00 and 2026-10-01T00:00:00+01:00.

• Across daylight-saving changes, calculate each boundary separately in the site's timezone.

• Durations are calendar (elapsed) hours, not working hours.

• Work-order search and meeting-pack operational windows follow the scheduled-work date filters, not the separate dueAt deadline: this_week is today through six days ahead, and this_month is today through month-end in the site timezone. Use the exposed dueAt timestamp independently for your own deadline policy.

Filters and grouping

Filters narrow the population before counts are taken; grouping controls how the same population is split for breakdowns.

Category totals come from get_ticket_category_metrics, not from get_ticket_metrics.

Grouping rules

• Location: each record contributes to one primary current location link (ordered by location name then id), so records with multiple locations are counted once. The unlocated bucket means no current link. Hidden primary locations are omitted from groups while readable parent records remain in headline totals; the groupingRule explanation tells you why group sums may differ from totals.

• Work-order assignment: groups use one active individual, team, or unassigned id per work order, and inactive retained assignment ids are ignored. Projected stored work is counted separately from open work.

• Category: counts use the stored effective category in precedence order: triaged, then suggested, then reported. A null categoryId means the record is uncategorised; a stored id with a null name means the category definition is unavailable. Categories are never guessed from the title.

Closure metrics

get_closure_metrics measures time from the recorded creation timestamp to the recorded closure timestamp, and returns the fields you need to judge how much of the answer is measured data.

• The response includes measuredCount, invalidDurationCount, and missingClosedAtCount alongside the mean and a resolution-outcome breakdown.

• Missing closure timestamps cannot be assigned to a month: missingClosedAtCount covers all permitted closed records matching the outcome filter, regardless of the requested closure window.

• A null mean means there were no valid measured records, not zero.

• resolutionType=completed separates completions from other outcomes.

Status history

get_status_history returns recorded transitions for individual records, paged per record.

• It accepts one recordId, or up to 25 recordIds of one record type. Duplicate ids are deduplicated.

• unavailableRecordIds combines absent and inaccessible records into one list.

• Each readable record returns its events, matchCount, truncated, and nextOffset; offset and limit apply separately to each record.

• To continue a truncated record, request that recordId with its nextOffset.

• elapsedHoursSincePreviousEvent uses the preceding recorded event, including across page boundaries.

• Backfilled events retain their source. A readable record with zero events has no recorded history; it does not mean zero elapsed resolution time.

• The recorded history may contain gaps; missing historical events cannot be reconstructed.

Fields exposed on reads

Reads expose the fields reports and follow-up questions are built from, always filtered by the permissions of the connected user.

• Issue and request detail and open-inbox samples expose stored effective category ids and names, creation and current closure timestamps, outcomes, raising membership id and name, attachment flags, and permission-aware location and asset lists. Anonymous reporters stay masked and contact details remain omitted.

• Work-order reads expose lifecycle timestamps, resolution outcome, scheduling details, priority, and active individual, team, or unassigned assignment details.

Ids, availability, and completeness

Use ids from the same connection, and read the availability and completeness fields before quoting a number.

• Replace site and record ids with ids obtained from the same connection. Omit siteId only when the connection has one usable site.

• Metric availability distinguishes an unreadable module or population (unavailable) from an allowed population with zero matches (available). breakdownUnavailable explains an unavailable location or assignment breakdown while totals remain available.

• Record-id refusals are deliberately indistinguishable from absence. Unknown record types and unsupported grouping values are rejected.

• Metric aggregates cover all matching records the caller may read and are complete.

• Search results, attention lists, and composed reports are compact samples. countCompleteness=lower_bound means the count was taken after filtering and deduplication of capped reads and can understate the true permitted population, including when zero. exact means all source records were read, though returned rows may still be capped. These flags do not turn samples into complete monthly reports.

How counts and visibility behave across Calm and Agent MCP is described in more detail in How AI report counts and visibility work.

Example calls

Replace SITE_ID and the record ids with ids obtained from the same connection.

[
  { "name": "get_ticket_metrics", "arguments": { "siteId": "SITE_ID", "recordType": "issues", "status": "all", "createdFrom": "2026-09-01T00:00:00+01:00", "createdBefore": "2026-10-01T00:00:00+01:00" } },
  { "name": "get_closure_metrics", "arguments": { "siteId": "SITE_ID", "recordType": "work_orders", "closedFrom": "2026-09-01T00:00:00+01:00", "closedBefore": "2026-10-01T00:00:00+01:00", "resolutionType": "completed" } },
  { "name": "get_ticket_category_metrics", "arguments": { "siteId": "SITE_ID", "recordType": "requests", "status": "all", "createdFrom": "2026-09-01T00:00:00+01:00", "createdBefore": "2026-10-01T00:00:00+01:00" } },
  { "name": "get_work_order_metrics", "arguments": { "siteId": "SITE_ID", "status": "open", "groupBy": "assignment" } },
  { "name": "get_ticket_metrics", "arguments": { "siteId": "SITE_ID", "recordType": "issues", "status": "open", "groupBy": "location" } },
  { "name": "get_status_history", "arguments": { "siteId": "SITE_ID", "recordType": "issues", "recordIds": ["ISSUE_ID_1", "ISSUE_ID_2"], "limit": 50 } }
]

Not available through Agent MCP reporting

These gaps are product facts, not connection problems, so asking again in a different way will not produce them.

• We do not provide native SLA targets, paused-time policy, working calendars, or SLA attainment. You can apply your own rules to the available timestamps and recorded transitions.

• Historical month-end backlog and counts of all closure and reopen events are not available.

• Search for closed issues and requests is limited (open-only and capped), and work-order search lacks continuation paging. Metric totals remain complete.

• Planned-work categories on work orders are not exposed as reporting fields or groups.

• Incident reporting has no customer MCP registration.