ServiceNow MCP Server

Overview Schema Source Related Servers Discussions Admin

List Records

list_records

Read-onlyIdempotent

List records from any ServiceNow table with optional filters, field selection, and pagination to retrieve exactly the data you need.

Instructions

List records from any ServiceNow table with optional filtering, field selection, and pagination

Input Schema

Name	Required	Description	Default
`limit`	No	Maximum number of records to return
`query`	No	Encoded query string (e.g., 'active=true^priority=1')
`fields`	No	Comma-separated list of fields to return
`offset`	No	Number of records to skip
`order_by`	No	Field to order results by (prefix with '-' for descending)
`table_name`	Yes	The ServiceNow table name (e.g., 'sys_user', 'cmdb_ci_server', 'incident')
`display_value`	No	'false' (default) returns stored values; 'true' returns labels in place of sys_ids and choice values; 'all' returns {display_value, value} per field, which keeps the sys_id beside the name. query= still filters on stored values, not labels. With 'true' or 'all', dates come back in this identity's time zone and format	false
`response_format`	No	'detailed' (default) returns each reference field as {link, value}; 'concise' drops the link (an instance URL) and returns the sys_id alone	detailed

Output Schema

Name	Required	Description	Default
`note`	No
`count`	Yes
`records`	Yes
`warning`	No
`truncated`	No
`next_offset`	No
`display_note`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv0.9.2Oct 23, 2026

addedInput schema / properties / display_value

Added value: +{
+  "default": "false",
+  "description": "'false' (default) returns stored values; 'true' returns labels in place of sys_ids and choice values; 'all' returns {display_value, value} per field, which keeps the sys_id beside the name. query= still filters on stored values, not labels. With 'true' or 'all', dates come back in this identity's time zone and format",
+  "enum": [
+    "false",
+    "true",
+    "all"
+  ],
+  "type": "string"
+}

addedInput schema / properties / response_format

Added value: +{
+  "default": "detailed",
+  "description": "'detailed' (default) returns each reference field as {link, value}; 'concise' drops the link (an instance URL) and returns the sys_id alone",
+  "enum": [
+    "concise",
+    "detailed"
+  ],
+  "type": "string"
+}

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "count": {
+      "type": "integer"
+    },
+    "display_note": {
+      "type": "string"
+    },
+    "next_offset": {
+      "type": "integer"
+    },
+    "note": {
+      "type": "string"
+    },
+    "records": {
+      "items": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "truncated": {
+      "type": "boolean"
+    },
+    "warning": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "count",
+    "records"
+  ],
+  "type": "object"
+}

Changed1 schema field changedv0.9.1Oct 14, 2026

changedInput schema / properties / table_name / description

Previous value: -"The ServiceNow table name (e.g., 'incident', 'sys_user', 'cmdb_ci')"New value: +"The ServiceNow table name (e.g., 'sys_user', 'cmdb_ci_server', 'incident')"

Changed1 schema field changedv0.7.0Sep 9, 2026

changedOutput schema / (root)

Previous value: -{
-  "additionalProperties": true,
-  "type": "object"
-}New value: +null

First observedv0.5.1Aug 1, 2026

TDQS

B3.4/5.0

Behavior3/5

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds little beyond that: it does not mention the default limit of 20, the 1000 cap, or how the total row count is signaled, and it does not flag that query filters on stored values rather than display labels (only the schema does).

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

Conciseness4/5

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

A single sentence, front-loaded with the verb and resource, with zero filler. It is well-formed but so terse that it stops short of the routing information that would make the brevity a net win.

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?

With an output schema present and annotations covering safety, the description need not explain return values, and it does not. However, for an 8-parameter tool that is the primary read entry point among 20 siblings, it omits default page size, result caps, and how it relates to get_record/aggregate_records, leaving the agent to reconstruct selection logic from the schema alone.

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% and each parameter is documented in detail, including the non-obvious display_value and response_format semantics, so the schema carries the burden. The description only names the capability categories ('filtering, field selection, pagination') without adding syntax or defaults, which is the baseline for full coverage.

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?

States a specific verb+resource ('List records') and scopes it to 'any ServiceNow table', which tells an agent this is a generic cross-table read. It does not explicitly differentiate itself from siblings like get_record or aggregate_records, so an agent must infer the boundary from names alone.

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

Usage Guidelines3/5

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

Naming filtering, field selection, and pagination implies the use case (browsing/enumerating rows), but there is no explicit when-to-use or when-not guidance. Nothing tells the agent to prefer get_record for a single known sys_id or aggregate_records for counts, which is a real ambiguity across 20 sibling tools.

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