Skip to main content
Glama
Knuckles-Team

servicenow-api

by Knuckles-Team
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Get incidents

servicenow_get_incidents
Read-onlyIdempotent

Retrieve ServiceNow incident records with filters, selected fields, limits, and pagination to review or manage incident details.

Instructions

Retrieve details of incident records.

:param name_value_pairs: Dictionary of name-value pairs for filtering records. :type name_value_pairs: str :param sysparm_display_value: Display values for reference fields ('True', 'False', or 'all'). :type sysparm_display_value: str :param sysparm_exclude_reference_link: Exclude reference links in the response. :type sysparm_exclude_reference_link: bool :param sysparm_fields: Comma-separated list of field names to include in the response. :type sysparm_fields: str :param sysparm_limit: Maximum number of records to return. Defaults to DEFAULT_INCIDENT_LIMIT when omitted; see Response.truncated. :type sysparm_limit: int :param sysparm_no_count: Do not include the total number of records in the response. :type sysparm_no_count: bool :param sysparm_offset: Number of records to skip before starting the retrieval. :type sysparm_offset: int :param sysparm_query: Encoded query string for filtering records. :type sysparm_query: str :param sysparm_query_category: Category to which the query belongs. :type sysparm_query_category: str :param sysparm_query_no_domain: Exclude records based on domain separation. :type sysparm_query_no_domain: bool :param sysparm_suppress_pagination_header: Suppress pagination headers in the response. :type sysparm_suppress_pagination_header: bool :param sysparm_view: Display style ('desktop', 'mobile', or 'both'). :type sysparm_view: str

:return: Response containing list of parsed Pydantic models with information about the retrieved records, plus truncated/applied_limit/next_offset metadata disclosing whether a default cap was applied and how to page past it. :rtype: Response

:raises MissingParameterError: If table is not provided. :raises ParameterError: If input parameters are invalid or an unknown argument is passed.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
dataNo
incident_idNo
sysparm_viewNo
sysparm_limitNo
sysparm_queryNo
api_parametersNo
sysparm_fieldsNo
sysparm_offsetNo
name_value_pairsNo
sysparm_no_countNo
sysparm_display_valueNo
sysparm_query_categoryNo
sysparm_query_no_domainNo
sysparm_exclude_reference_linkNo
sysparm_suppress_pagination_headerNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv2.4.0

TDQS

B3.3/5.0
Behavior3/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds genuinely useful behavior: a default cap (DEFAULT_INCIDENT_LIMIT), Response.truncated/applied_limit/next_offset paging metadata, and raised error types. However, the ':raises MissingParameterError: If table is not provided' line is leftover template noise that references a parameter that doesn't exist in this tool's schema, which is misleading rather than informative.

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

Conciseness3/5

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

The core purpose is front-loaded in one clean sentence, but the body is a raw docstring dump where every ':type' line redundantly restates type information already present in the input schema, and the trailing ':raises table' error is vestigial. Roughly a third of the text is waste.

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

Completeness4/5

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

For a 15-parameter, no-output-schema read tool, the description is nearly self-sufficient: it documents the return shape (list of records plus truncated/applied_limit/next_offset), the default-limit behavior, and most parameters. The missing pieces are the three undocumented parameters and the erroneous 'table' error reference.

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

Parameters4/5

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

With 0% schema description coverage, the description carries the full burden and mostly delivers: 12 of 15 parameters get Sphinx docs, including non-obvious detail the schema lacks (sysparm_display_value accepts 'True'/'False'/'all'; sysparm_view accepts 'desktop'/'mobile'/'both'). The gaps are the undocumented data, incident_id, and api_parameters parameters, and several entries merely restate the parameter name.

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 clear verb+resource: 'Retrieve details of incident records.' An agent knows it's a read operation on incidents, but the phrasing is ambiguous about whether it returns a single record or a list, and it never differentiates itself from the sibling servicenow_get_incident (singular) which reads very similarly.

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

Usage Guidelines2/5

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

There is no guidance on when to choose this tool over servicenow_get_incident, servicenow_get_table_record, or the write-side servicenow_ingest_incidents/servicenow_create_incident. The description jumps straight into Sphinx parameter docs without ever stating the selection conditions.

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