Skip to main content
Glama
jschuller

ServiceNow MCP Server

by jschuller
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Aggregate Records

aggregate_records
Read-onlyIdempotent

Aggregate ServiceNow table records with COUNT, AVG, MIN, MAX, SUM, and optional GROUP BY filters, returning grouped stats for reporting and analysis.

Instructions

Aggregate records using COUNT, AVG, MIN, MAX, SUM with optional GROUP BY via the Stats API.

If the Stats API is refused (401) while list_records works, count with list_records instead: the same query, fields="sys_id", limit=1000, paging with offset.

Input Schema

NameRequiredDescriptionDefault
countNoInclude record count in results
queryNoEncoded query string to filter records before aggregation
havingNoPost-aggregation filter, aggregate^field^operator^value (e.g., 'count^name^>^1')
group_byNoComma-separated fields to group results by (e.g., 'priority,state')
avg_fieldsNoComma-separated fields to average (e.g., 'reassignment_count,reopen_count')
max_fieldsNoComma-separated fields to find maximum values
min_fieldsNoComma-separated fields to find minimum values
sum_fieldsNoComma-separated fields to sum
table_nameYesThe ServiceNow table name (e.g., 'sys_user_group', 'cmdb_ci', 'incident')
display_valueNo'false' (default) returns stored group_by values; 'true' returns labels in place of sys_ids and choice values; 'all' returns both. query= still filters on stored values, not labelsfalse

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.9.2
    • addedInput schema / properties / display_value
      Added value: +{
+  "default": "false",
+  "description": "'false' (default) returns stored group_by values; 'true' returns labels in place of sys_ids and choice values; 'all' returns both. query= still filters on stored values, not labels",
+  "enum": [
+    "false",
+    "true",
+    "all"
+  ],
+  "type": "string"
+}
    • changedInput schema / properties / having / description
      Previous value: -"Post-aggregation filter (e.g., 'COUNT>5')"New value: +"Post-aggregation filter, aggregate^field^operator^value (e.g., 'count^name^>^1')"
  2. Changed1 schema field changedv0.9.1
    • changedInput schema / properties / table_name / description
      Previous value: -"The ServiceNow table name (e.g., 'incident', 'cmdb_ci')"New value: +"The ServiceNow table name (e.g., 'sys_user_group', 'cmdb_ci', 'incident')"
  3. Changed1 schema field changedv0.7.0
    • changedOutput schema / (root)
      Previous value: -{
-  "additionalProperties": true,
-  "type": "object"
-}New value: +null
  4. First observedv0.5.1

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds information the annotations cannot express: the dependency on the Stats API and the specific 401 failure mode with a documented workaround. It does not describe the shape of the aggregated results, which is the remaining gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences (plus a wrapped fallback) with the capability stated first and the operational caveat second. Every clause carries information an agent could act on; nothing repeats the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter tool with no output schema, the description covers capability and the failure path but says nothing about the returned structure — whether results come back as grouped rows, how aggregate columns are named, or what happens when count=true alongside group_by. Adequate, but an agent must infer the result shape.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every one of the 10 parameters is already documented in the schema, including the non-obvious having and display_value semantics. The description adds only the function-to-parameter mapping by naming COUNT/AVG/MIN/MAX/SUM and GROUP BY, which is marginal value over the schema — the baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb+resource (aggregate records) and enumerates the supported functions (COUNT, AVG, MIN, MAX, SUM) plus GROUP BY, which lets an agent distinguish it from the record-oriented siblings. It stops short of explicitly contrasting it with list_records as the preferred aggregation path; list_records only appears as a degraded fallback.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The second paragraph gives a concrete when-to-use-what rule: if the Stats API returns 401, switch to list_records with fields="sys_id", limit=1000 and offset paging. That is actionable routing guidance, but there is no general statement about when NOT to use this tool (e.g., for non-aggregate retrieval), so it is not a full 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools