ServiceNow_Developer_Panel

Overview Schema Source Related Servers Discussions Admin

request_table

Read-onlyIdempotent

Fetch records from one ServiceNow table with filters, field selection, and limits; returns a sample and a cache name for reading or exporting the full result.

Instructions

Fetch records from one ServiceNow table. Returns a sample of the records, any warnings and a cache_name; the full result is cached locally for query_cache and export_cache. To join several tables, fetch them with request_tables instead.

Input Schema

Name	Required	Description
`limit`	No	Maximum number of records to fetch, 100 when omitted. When exactly this many records come back, limit_reached is true and more records probably match: ask again with a higher limit. Above 10000 the request is split into several calls.
`query`	No	Encoded query passed as sysparm_query, for example active=true^priority=1. Empty returns every record up to the limit. ServiceNow ignores conditions on fields the table does not have and returns the records unfiltered, so use the exact field names, as listed by describe_table: for example business rules in sys_script name their table in collection, not table.
`table`	Yes	ServiceNow table name, for example incident or sys_user.
`fields`	No	Field names passed as sysparm_fields. Dot-walking is allowed, for example caller_id.name. Empty returns every field.
`refresh`	No	Skip the local cache and ask the instance again. Leave false to reuse a recent response.
`instance`	Yes	Name of a configured instance, as returned by list_instances.
`order_by`	No	Field name passed as sysparm_order_by. Empty keeps the instance order.
`max_records`	No	How many of the fetched records to return in this response. The full result stays in the local cache: use query_cache with the returned cache_name to read the rest.

Output Schema

Name	Required	Description	Default
`limit`	Yes
`table`	Yes
`source`	Yes
`columns`	Yes
`records`	Yes
`warnings`	Yes
`row_count`	Yes
`cache_name`	Yes
`elapsed_ms`	Yes
`executed_at`	Yes
`limit_reached`	Yes
`sample_truncated`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 4, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already declare read-only, open-world and idempotent, so the safety profile is covered. The description adds genuinely non-obvious behavior: only a sample plus warnings and a cache_name come back, while the full result is cached locally for query_cache/export_cache — that is real information not present in the structured fields.

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 sentences, zero waste, return shape stated before the alternative-tool routing. Every clause earns its place.

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?

Given eight parameters, an output schema and rich annotations, the description covers the essentials: scope, return payload, caching follow-up, and the sibling alternative. Error/permission behavior is left implicit, a minor gap for an open-world read against a remote instance.

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?

Schema coverage is 100%, so baseline would be 3, but the description supplies cross-parameter semantics the schema does not: the returned cache_name is the handle for reading the remainder via query_cache, which ties max_records to the caching tools. It does not restate per-field syntax, which is correctly left to the schema.

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

Purpose5/5

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

Specific verb and resource ('Fetch records from one ServiceNow table') with explicit single-table scope, and it names the sibling it is not (request_tables) in the same breath. An agent can distinguish this from request_tables without opening either schema.

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?

Explicitly routes multi-table/join cases to request_tables and points at query_cache/export_cache for the full result set, giving a clear selection rule. It stops short of stating when to prefer refresh=true versus the cache, leaving that judgement to the per-parameter text.

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

Deploy Server