servicenow-platform-mcp

Overview Schema Source Related Servers Score Discussions Admin

record_read

Fetch ServiceNow records from any table by sys_id or name with sensitive fields masked, and discover writable script fields for subsequent updates.

Instructions

Fetch a record by sys_id or name from any table.

Exactly one of sys_id or name must be supplied. Sensitive fields are masked. The response includes a script_fields list (resolved dynamically via sys_dictionary plus the table's super_class chain) so callers can discover which script-bearing fields are writable on a subsequent record_write.

Args: table: ServiceNow table name (e.g. sys_script, catalog_script_client, incident). Tables with zero script fields return script_fields: [] and succeed. sys_id: Mutually exclusive with name. Direct lookup by sys_id. name: Mutually exclusive with sys_id. Resolves via name=<value> query; ambiguous matches return an error. fields: Comma-separated field projection. Empty returns compact identity/update metadata plus all discovered script-bearing fields. '*' returns the full masked record.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`name`	No
`table`	Yes
`fields`	No
`sys_id`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.12.0Sep 1, 2026
- addedInput schema / properties / fields
```
Added value: +{
+  "default": "",
+  "title": "Fields",
+  "type": "string"
+}
```
First observedv0.10.0May 30, 2026

TDQS

A4.7/5.0

Behavior5/5

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

With no annotations provided, the description carries the full burden, and it delivers: sensitive fields are masked, script_fields is resolved via sys_dictionary and super_class chain, zero-script-field tables succeed with an empty list, and ambiguous name lookups error. This gives an agent accurate expectations beyond the input schema.

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?

The description is longer than average but well-organized with a front-loaded purpose sentence and an Args section. The behavioral details about script_fields are relevant and earn their place. Minor redundancy exists because mutual exclusivity is stated both up front and within each parameter, but overall structure is effective.

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

Completeness5/5

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

For a read tool with no annotations and no schema-level parameter descriptions, this definition covers the key operational context: required/optional parameters, edge cases, return behavior, and integration with a subsequent record_write. The presence of an output schema means return-value structure does not need to be duplicated in the description.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must fully compensate, and it does. Every parameter is explained: table with examples, sys_id with mutual exclusivity, name with resolution semantics and ambiguity errors, and fields with projection and empty-value behavior. This is a complete parameter contract.

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?

The first sentence clearly states the verb and resource: 'Fetch a record by sys_id or name from any table.' This distinguishes it from siblings like query, record_write, and describe by specifying a direct record-fetch operation by identifier. The scope is concrete and immediately actionable.

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 description provides clear invocation context: exactly one of sys_id or name must be supplied, and ambiguous name matches return an error. It explains the relationship to record_write by mentioning script_fields discovery, but it does not explicitly contrast this tool with query or other read-oriented siblings. Still, the usage conditions are unambiguous.

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

Install Server