This server connects MCP clients to ServiceNow for AI-assisted data querying, schema/CMDB inspection, aggregation, update-set review, and role-gated writes.
Query any ServiceNow table via the Table API with encoded filters, field selection, pagination, ordering, and display-value options.
Fetch individual records and aggregate data with COUNT, AVG, MIN, MAX, SUM, and GROUP BY through the Stats API.
Browse CMDB configuration items, create/update CIs, and inspect parent/child CI relationships.
Inspect table schemas including inherited fields, and find where tables or fields are referenced by business rules, scripts, UI policies, ACLs, script includes, and reference fields.
Read the authenticated user’s identity and directly assigned active roles, plus query system properties.
List and inspect update sets, create update sets, set the current update set, and list update-set changes.
Create, update, and delete table records; create and update CIs; perform update-set write operations when roles permit.
Run safely with read-only mode or snc_read_only, which hides write tools, while ServiceNow ACLs remain the authority.
Access MCP resources such as table schemas, instance info, current update set, CMDB class hierarchy, and encoded-query reference, plus four guided skill:// workflows.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ServiceNow MCP Server List the 5 most recent incidents"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
uvx mcp-server-servicenow gives an AI assistant the ServiceNow developer data plane: the Table API, the data dictionary, Stats API aggregates, the CMDB and update sets, on any release from Tokyo up. It runs alongside ServiceNow's own MCP servers (how they differ).
"Which fields does cmdb_ci_server have, including inherited ones?"
"Who holds admin, and which roles are granted directly instead of through a group?"
"Review update set 'Q3 fixes' before I promote it."
"Which server CIs are missing an IP address or an owner?"
"How many open incidents does each assignment group have?" (any table works, not just the platform ones)
Related MCP server: ServiceNow MCP Server
About ten minutes on a free developer instance. On a company instance, ask your ServiceNow admin for the user in step 2.
Sign up for a free Personal Developer Instance (PDI) — it comes with demo incidents, changes and CIs. PDIs hibernate after a few hours idle: wake yours from the developer portal before you start.
Don't connect as admin: new instances refuse REST basic auth for it (why), and the server needs far less.
Sign in as admin and go to All › User Administration › Users › New.
User ID mcp.integration, Identity type Machine (this ticks Web service access only), and tick Internal Integration User. If your form has no Identity type, tick Web service access only yourself. Submit, then open the user again.
Set Password, and keep the password for step 3.
Roles › Edit: add itil and snc_read_only, save.
That user can read incidents, changes, problems, CMDB and aggregates, and can't change anything. Schema, update sets and writes need more: see roles.
You need uv (uvx runs the server without installing it). In Claude Code:
read -rs SERVICENOW_PASSWORD # paste the password; it is not shown or kept in your history
claude mcp add servicenow \
-e SERVICENOW_INSTANCE_URL=https://devNNNNNN.service-now.com \
-e SERVICENOW_USERNAME=mcp.integration \
-e SERVICENOW_PASSWORD="$SERVICENOW_PASSWORD" \
-- uvx mcp-server-servicenowOr install the Claude Code plugin, which adds the four skills as slash commands. It reads the same SERVICENOW_* variables from the shell that starts Claude Code (details):
claude plugin marketplace add jschuller/mcp-server-servicenow
claude plugin install servicenow@mcp-server-servicenowInstall uv with winget install astral-sh.uv, then:
$s = Read-Host 'Password' -AsSecureString
$p = [Runtime.InteropServices.Marshal]::PtrToStringBSTR([Runtime.InteropServices.Marshal]::SecureStringToBSTR($s))
claude mcp add servicenow -e SERVICENOW_INSTANCE_URL=https://devNNNNNN.service-now.com -e SERVICENOW_USERNAME=mcp.integration -e "SERVICENOW_PASSWORD=$p" -- uvx mcp-server-servicenowThe button adds the server to your VS Code user profile and asks for the instance URL, user and password on first start, storing the password securely. Or add this to .vscode/mcp.json. Use Copilot Chat in Agent mode.
{
"inputs": [
{ "type": "promptString", "id": "servicenow-url", "description": "ServiceNow instance URL, e.g. https://devNNNNNN.service-now.com" },
{ "type": "promptString", "id": "servicenow-password", "description": "Password for mcp.integration", "password": true }
],
"servers": {
"servicenow": {
"type": "stdio",
"command": "uvx",
"args": ["mcp-server-servicenow"],
"env": {
"SERVICENOW_INSTANCE_URL": "${input:servicenow-url}",
"SERVICENOW_USERNAME": "mcp.integration",
"SERVICENOW_PASSWORD": "${input:servicenow-password}"
}
}
}
}Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):
{
"mcpServers": {
"servicenow": {
"command": "uvx",
"args": ["mcp-server-servicenow"],
"env": {
"SERVICENOW_INSTANCE_URL": "https://devNNNNNN.service-now.com",
"SERVICENOW_USERNAME": "mcp.integration",
"SERVICENOW_PASSWORD": "your-password"
}
}
}
}Codex, opencode, Antigravity, Cursor, pi, the Claude Code plugin and keeping the password out of config files: client setup.
Ask: "List the 5 most recent incidents." The start-here user holds snc_read_only, so the server lists only the 13 read-only tools. Give the user write roles (and remove snc_read_only) and the 7 write tools appear; your client asks before each write.
No answer? Run the same configuration with --check. It makes read-only requests, prints one line per check (instance reachable, identity, roles, table read, schema, aggregates) and never prints a secret:
SERVICENOW_INSTANCE_URL=https://devNNNNNN.service-now.com SERVICENOW_USERNAME=mcp.integration \
SERVICENOW_PASSWORD="$SERVICENOW_PASSWORD" uvx mcp-server-servicenow --checkGot an answer back? Say which client and ServiceNow release in Show and tell — it tells us what works. Questions go to Q&A.
You see | Fix |
| The PDI is asleep: wake it and retry |
| The user isn't Web service access only, or the password is wrong (401) |
| The user lacks a role for that table or tool (roles) |
Everything else: run --check (above), then TROUBLESHOOTING.
20 tools, 5 resources and 4 skills. Full reference: tools, resources and skills.
Group | Tools |
Table API |
|
CMDB |
|
System |
|
Update sets |
|
Resources: table schemas, instance info, the current update set, the CMDB class hierarchy and an encoded-query reference — read without a tool call.
Skills: four guided workflows for the Now Platform, served over MCP as skill:// resources so every client gets them with no plugin:
exploring-tables: schemas, choice lists, a record's history, what touches a table or field, the encoded-query reference;
analyzing-access: who holds which roles, team rosters and group members, and what a 403 or a missing field means;
reviewing-update-sets: risk categories and a pre-promotion checklist;
servicenow-cmdb: CMDB data quality and CSDM conformance.
To run with the tools only, add the server without the plugin (claude mcp add, or an mcp.json entry) and set SERVICENOW_SKILLS=off (or --skills off). off changes only what the server serves: the Claude Code plugin still loads the four skills from its own folder (configuration).
Community skills: skills for applications such as ITSM, and for your own conventions, live in their authors' repositories, each with its own eval results:
EXTENDING.md covers writing, validating, testing with mocked tools, and sharing them;
to find them, browse the servicenow-mcp-skill topic and Discussions › Skills. This project doesn't vet them.
The incident triage skill that shipped here until 0.9.0 is now an example.
ServiceNow's ACLs decide what the user can do; the server adds nothing on top.
You want | Roles | Run with |
Read ITSM and CMDB data (the start-here user) |
| no flag: write tools are hidden for |
…and create or update incidents and CIs |
| no flag; the client asks before writes ( |
…and delete incidents, problems, changes | add | |
Table schemas | add | |
Update sets, system properties |
|
Per-tool detail: roles per tool. Setting up a company instance: recommended integration identity.
Read-only mode — --read-only hides the 7 write tools and refuses any non-GET request.
Read-only identities see read-only tools — when the user holds snc_read_only the write tools are hidden without a flag. A convenience, not a control: ServiceNow refuses those writes anyway.
Table scope lives in ServiceNow — ACLs and REST API access policies on the integration user decide which tables and fields it can read, dot-walks included.
Audit log — one JSON line per tool call or resource read: who, which table, outcome; written fields by name only, never their values, and secret-like values in queries masked.
Your client approves writes — every tool is annotated read-only or destructive, so Claude Code, Copilot and Codex ask before a write. Clients that don't ask (opencode by default, pi) need a read-only identity, or --read-only when the identity can write.
Flags and environment variables: configuration.
Verified with 0.8.0 on 2026-10-11 against ServiceNow Brazil, and the 0.9.0 skills re-checked in Claude Code and Codex: Claude Code 2.1.296, VS Code 1.140 with GitHub Copilot, Codex CLI 0.162.1, opencode 1.19.0, Antigravity CLI 1.1.20 and pi 1.1.0. Claude Desktop, Cursor and any other client that speaks MCP over stdio or Streamable HTTP should work too; behaviour per client: client setup.
Client setup — every client, the Claude Code plugin, Windows
Configuration — the recommended identity, OAuth client credentials (headless), API keys, multiple instances, secrets, every setting
Remote deployment — from source, Streamable HTTP, OAuth 2.1 + PKCE, Docker, Cloud Run
Architecture and embedding — mount it in your own FastMCP server
Write your own skills — the template, the validator, the GitHub Action, sharing
Privacy — the server talks only to your instance; no telemetry
Contributing · Changelog · Support · Security
Write your own skills: EXTENDING.md covers the template, the validator and how to share them. Next: MCP prompts.
Related: sn-app-template — a ServiceNow scoped app template for Claude Code + now-sdk that pairs with this server.
MIT. An independent project, not affiliated with or endorsed by ServiceNow, Inc. ServiceNow is a trademark of ServiceNow, Inc.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | Include record count in results | |
| query | No | Encoded query string to filter records before aggregation | |
| having | No | Post-aggregation filter, aggregate^field^operator^value (e.g., 'count^name^>^1') | |
| group_by | No | Comma-separated fields to group results by (e.g., 'priority,state') | |
| avg_fields | No | Comma-separated fields to average (e.g., 'reassignment_count,reopen_count') | |
| max_fields | No | Comma-separated fields to find maximum values | |
| min_fields | No | Comma-separated fields to find minimum values | |
| sum_fields | No | Comma-separated fields to sum | |
| table_name | Yes | The ServiceNow table name (e.g., 'sys_user_group', 'cmdb_ci', 'incident') | |
| display_value | No | '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 | false |
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.
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.
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.
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.
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.
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.
Create a new CMDB configuration item
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | CI attributes as key-value pairs (must include 'name') | |
| class_name | No | CMDB class name | cmdb_ci |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with annotations (readOnlyHint false, destructiveHint false) by indicating a write operation, but adds no additional behavioral details such as side effects, permissions, or idempotency beyond what the annotations already convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately conveys the tool's purpose without any unnecessary words or fluff, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create operation with a well-specified schema, the description is sufficient. It could mention the required 'name' field but that is already in the schema, so completeness is strong. The lack of an output schema means no return value explanation is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes both parameters (data with 'must include name', class_name with default), achieving 100% coverage. The tool description adds no extra parameter semantics, keeping the baseline at 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and the resource 'CMDB configuration item', distinguishing it from sibling tools like list_ci, get_ci, and update_ci. This is a specific and unambiguous purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you need to create a new CI) but provides no explicit guidance on when to use this tool over alternatives like create_record or update_ci. The intent is clear from the wording but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new record in any ServiceNow table
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | Record field values as key-value pairs | |
| table_name | Yes | The ServiceNow table name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, so the write nature is known. The description adds no further behavioral context—no mention of idempotency, duplicate handling, required permissions, or side effects beyond creating a record.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with zero extraneous content. It conveys the essential purpose efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create operation with two parameters and no output schema, the description is minimally sufficient. However, it lacks any mention of return behavior or edge cases (e.g., what happens if the table doesn't exist), which would be useful given the tool's generic scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both 'data' and 'table_name' having clear descriptions. The tool description adds no parameter-specific guidance, so it meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'create' and the resource 'a new record in any ServiceNow table', which distinguishes it from specific create tools like create_ci. However, it does not explicitly name alternatives, so it misses the top tier for sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as update_record or create_ci. It does not mention prerequisites, error conditions, or when a different tool would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new update set for tracking customizations
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the update set | |
| parent | No | Parent update set sys_id (for batch sets) | |
| description | No | Description of the update set |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate this is a write operation (readOnlyHint=false) and not idempotent (idempotentHint=false). The description adds no further behavioral context such as required permissions, duplicate handling, or side effects. It is not misleading but does not go beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no unnecessary words. It efficiently communicates the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create operation with no output schema, the description is mostly complete. It explains what the tool does and the purpose. However, it does not mention the return value (e.g., the new sys_id) or any potential failure modes, which would be useful but not essential for this straightforward operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all parameters (name, parent, description) with descriptions, giving 100% coverage. The tool description provides no additional meaning or constraints beyond what is already in the schema, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (create), the resource (update set), and the purpose (tracking customizations). It is easily distinguished from sibling tools like get_update_set and list_update_sets, which are read operations, and create_record, which targets a different resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives. While the resource type (update set) differentiates it from create_record or create_ci, there is no direct mention of when this should be preferred or what prerequisites exist (e.g., must have an active update set).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a record from a ServiceNow table by sys_id
| Name | Required | Description | Default |
|---|---|---|---|
| sys_id | Yes | The sys_id of the record to delete | |
| table_name | Yes | The ServiceNow table name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered structurally. The description adds nothing beyond that: it does not mention irreversibility, required permissions, update-set context, or error behavior on a missing sys_id.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with zero filler, front-loading the action, resource, and key. Nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter destructive operation with full annotation coverage and a fully documented schema, the description is minimally adequate. It omits consequences, confirmation behavior, and prerequisites that would help an agent invoke a delete safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both parameters are documented in the schema, so the baseline is 3. The description's 'by sys_id' restates what the schema already says and adds no format or constraint detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb (Delete) and resource (a record from a ServiceNow table), with the lookup key (sys_id) specified. It does not, however, distinguish this from siblings like update_record or clarify scope relative to any bulk/delete alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, no prerequisites (permissions, update set requirements), and no statement about whether it removes records singularly only. The agent must infer everything from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Where-used for a table or one of its fields: the business rules, client scripts, UI policies, ACLs, script includes and reference fields that touch it.
Returns names, sys_ids and flags only, never script, condition or ACL bodies. Script matches (script includes; business rules and client scripts in field mode) are text matches, so expect false positives. Only this exact table is matched: run it again for a parent table (get_table_schema's hierarchy) to find rules and ACLs defined there. A source this identity can't read (403, or a 401 from an access policy that leaves its table out) is listed in not_assessable (under OAuth each such source costs one token refresh). Under basic auth the first 401 is an error (a refused password looks the same), and so is a refused OAuth secret; rows hidden by an ACL are simply missing. complete=false means the source hit the limit.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum matches to return per source | |
| field_name | No | Narrow to one field of the table (e.g., 'assigned_to') | |
| table_name | Yes | The table to look up (e.g., 'incident') |
| Name | Required | Description |
|---|---|---|
| note | No | |
| field | No | |
| table | Yes | |
| groups | Yes | |
| truncated | No | |
| not_assessable | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, the description discloses that only names, sys_ids and flags are returned (never bodies), that script matches produce false positives, that matching is exact-table only, and that limit-truncated sources set complete=false. It also explains auth failure semantics: 401 vs 403 handling, not_assessable entries, token-refresh costs under OAuth, and that ACL-hidden rows silently vanish.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core definition and the important caveats (no bodies, false positives) come next. It is dense but nearly every clause carries operational meaning; the auth/401 parenthetical is the most compressible part.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even with an output schema present, the description covers the non-obvious parts an agent must interpret: not_assessable, complete=false, and silent ACL omissions. For a read-only, idempotent tool with rich annotations and a schema, nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description adds genuine semantics by explaining that field_name switches business rules and client scripts into text-match "field mode", which the schema's "Narrow to one field" wording does not convey. The limit parameter's per-source semantics are left to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
"Where-used for a table or one of its fields" states a specific verb-equivalent and resource, then enumerates the source types scanned (business rules, client scripts, UI policies, ACLs, script includes, reference fields). This is clearly distinguishable from siblings like get_table_schema or list_records.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It tells the agent to run the tool again for a parent table, pointing at get_table_schema's hierarchy, which is real routing guidance. It does not explicitly state when this tool should be skipped in favor of another sibling, so it falls short of a full when/when-not treatment.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single CMDB configuration item by sys_id
| Name | Required | Description | Default |
|---|---|---|---|
| sys_id | Yes | The sys_id of the CI | |
| class_name | No | CMDB class name | cmdb_ci |
| 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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no further behavioral context such as what happens when the sys_id is invalid, what fields are returned, or how class_name affects lookup. Given the annotated safe-read profile, this is adequate but not enriched.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that states the operation and lookup key with no wasted words. It is appropriately sized for a simple get-by-id tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-identifier operation, the description plus rich schema descriptions and safety annotations are nearly sufficient. The main missing element is guidance on alternatives or failure behavior, but no output schema means return values need not be explained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains sys_id, class_name, and display_value in detail. The description adds no meaning beyond 'by sys_id', so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: get a single CMDB configuration item. It also scopes retrieval by sys_id, which distinguishes it from list_ci. It does not explicitly differentiate itself from get_record or other retrieval siblings, keeping it below a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description only restates the operation and gives no explicit guidance on when to use this tool versus alternatives such as get_record, list_ci, or get_ci_relationships. The word 'single' hints at lookup semantics, but no when-to-use or when-not-to-use context is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get relationships for a CMDB configuration item (parent and child)
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of relationships to return | |
| offset | No | Number of relationships to skip | |
| sys_id | Yes | The sys_id of the CI | |
| relation_type | No | Filter by relationship type sys_id |
| Name | Required | Description |
|---|---|---|
| note | No | |
| count | Yes | |
| truncated | No | |
| next_offset | No | |
| relationships | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the useful behavioral detail that both parent and child relationships are returned, but says nothing about pagination, ordering, or whether direction can be controlled.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no wasted words. It states the resource and the parent/child scope immediately, and every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a full input schema, an output schema, and complete annotations, the description supplies enough to call the tool correctly: it names the target CI and the relationship direction. The main missing element is routing guidance relative to sibling tools, which keeps it from a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents sys_id, limit, offset, and relation_type thoroughly. The description adds no parameter-level meaning beyond what the schema provides, which is the baseline case for full coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (get relationships for a CMDB configuration item) and clarifies that both parent and child relationships are returned. It is clear what the tool does, though it does not explicitly distinguish itself from nearby siblings like get_ci or find_references.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus get_ci, list_ci, or find_references, nor any mention of prerequisites or exclusions. The agent must infer the appropriate context entirely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the authenticated user's identity and directly assigned, active roles
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | Extra sys_user fields to return besides user_name, user_display_name, user_email, user_sys_id and roles |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so safety is covered. The description adds a genuinely useful behavioral nuance beyond that: roles returned are only directly assigned and active, preventing an agent from assuming inherited or inactive roles are included.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler; the scope qualifier is attached directly to the resource being fetched.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-required-parameter read tool with full annotation coverage and a fully documented schema, the description covers identity plus the role scoping. Return shape is partially implied via the schema's field list, so nothing essential is missing, though error/auth-failure behavior is unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single 'fields' parameter is fully documented in the schema, including the default returned fields. The description adds no parameter-level detail, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb and resource (get the authenticated user's identity), plus a precise scope qualifier: only 'directly assigned, active roles'. This distinguishes it from generic record-fetching siblings like get_record, though it does not name any alternative tool by name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the phrase 'authenticated user's identity' — an agent can infer this is for identifying the calling user — but there is no explicit when-to-use, when-not-to-use, or alternative named (e.g., get_record for arbitrary users).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single record from a ServiceNow table by sys_id.
If this is refused (401) while list_records works, call list_records with query="sys_id=<sys_id>" and limit=1 instead.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | Comma-separated list of fields to return | |
| sys_id | Yes | The sys_id of the record | |
| table_name | Yes | The ServiceNow table name | |
| 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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, non-destructive and closed-world, so the safety profile is settled. The description adds value beyond that by disclosing a specific failure mode (401 per-record refusal) and a concrete remediation, which the agent cannot infer from annotations or schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, purpose front-loaded, fallback placed after the primary statement. Nothing is redundant and nothing could be removed without losing the 401 workaround.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple idempotent read with a fully documented 4-parameter schema, this is nearly complete; the only gap is no note on what happens when the sys_id does not exist (empty vs error), which the agent must discover at call time.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the display_value description is unusually rich (label vs stored value, 'all' shape, time-zone effects). The description adds no parameter-level meaning on top of that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Get a single record from a ServiceNow table by sys_id") and names the lookup key, which cleanly separates it from list_records, aggregate_records, and get_ci. It does not explicitly contrast with sibling getters (get_ci, get_update_set), so differentiation is implied rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly gives the alternative (list_records with query="sys_id=<sys_id>" and limit=1) and the exact condition that selects it (a 401 refusal while list_records works). That is a real routing rule, though it covers only the failure path and says nothing about when to prefer this over list_records in normal operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query ServiceNow system properties
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of properties to return | |
| query | No | Filter query (e.g., 'name=glide.servlet.uri' or 'nameLIKEglide') |
| Name | Required | Description |
|---|---|---|
| note | No | |
| count | Yes | |
| truncated | No | |
| properties | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is fully covered. The description adds nothing beyond that — no hint about result volume, what kinds of properties are returned, or whether pagination matters at the 100-item cap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence with no filler, and the resource is front-loaded. Its brevity is appropriate, though it is terse to the point of leaving usage entirely to structured fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists and annotations cover the safety profile, so the return-value and risk story need not be in the description. Still, for a query tool with filtering, a short note on what system properties are or when to reach for it would complete the picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both the limit and query parameters are fully documented in the schema, including an example filter syntax. The description adds no parameter meaning of its own, which is the expected baseline when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb (Query) and resource (ServiceNow system properties), which is more precise than the title alone. It does not distinguish this tool from read-oriented siblings such as list_records, get_record, or get_table_schema, so an agent gets clarity but no differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, no mention of prerequisites, permissions, or common query patterns. The filter format lives only in the schema, not in the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the data dictionary (field definitions) for a ServiceNow table, including inherited fields
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of fields to return (own fields first, then inherited) | |
| table_name | Yes | The table name to get schema for | |
| include_inherited | No | Include fields inherited from parent tables (e.g. cmdb_ci fields on cmdb_ci_server) |
| Name | Required | Description |
|---|---|---|
| note | No | |
| table | Yes | |
| fields | Yes | |
| hierarchy | Yes | |
| truncated | No | |
| field_count | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is fully covered. The description adds the useful behavioral fact that inherited fields are included by default, but says nothing about ordering, truncation at the limit, or performance on large tables.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler; the key concept (data dictionary / field definitions) appears immediately with the table scope attached.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only schema lookup with full parameter documentation, annotations, and an output schema, the description covers what is needed. The only shortfall is absent guidance on cost/size (limit defaults to 200) for very wide tables.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all three parameters (including the limit ordering note and the include_inherited example) are already documented in the schema. The description's mention of inherited fields merely echoes the schema, adding no new syntax or format detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Get the data dictionary (field definitions) for a ServiceNow table') and adds a scope qualifier about inherited fields. It is clearly distinguishable from record-level siblings like get_record or get_ci, though it never names an alternative explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: an agent can infer this is a schema-discovery step before querying or building records. There is no explicit when-to-use/when-not guidance, no mention of alternatives like get_record, and no prerequisite context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details of a specific update set by sys_id
| Name | Required | Description | Default |
|---|---|---|---|
| sys_id | Yes | The sys_id of the update set |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no additional behavioral details beyond confirming it is a read operation, which is consistent with annotations. It does not describe return format or error handling, but given the annotation coverage, a baseline 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the verb and resource. It contains no filler or redundant information, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has only one parameter and no output schema, and the description plus annotations fully convey its purpose and safety. An agent can correctly invoke it with just the sys_id, and the read-only, idempotent nature is already declared. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameter 'sys_id' is fully documented in the schema. The description mentions 'by sys_id' but does not add additional meaning, such as format requirements or special cases. With high coverage, the baseline of 3 is warranted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get details' with the specific resource 'update set' and identifies the key parameter 'sys_id'. It distinguishes itself from sibling tools like 'list_update_sets' (which lists) and 'get_record' (generic), making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used to retrieve details of a specific update set, but it does not explicitly mention when to use it over alternatives or provide exclusions. There is no guidance on how it compares to sibling tools like 'list_update_sets' or 'get_record'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List CMDB configuration items with optional class and query filtering
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of CIs to return | |
| query | No | Encoded query string (e.g., 'operational_status=1') | |
| fields | No | Comma-separated list of fields to return | |
| offset | No | Number of records to skip | |
| class_name | No | CMDB class name (e.g., 'cmdb_ci', 'cmdb_ci_server', 'cmdb_ci_computer') | cmdb_ci |
| 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 |
| Name | Required | Description |
|---|---|---|
| note | No | |
| class | Yes | |
| count | Yes | |
| records | Yes | |
| warning | No | |
| truncated | No | |
| next_offset | No | |
| display_note | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as a read-only, idempotent, non-destructive, closed-world operation. The description adds no behavioral context beyond the schema and annotations, such as pagination behavior or output shape, but it also does not contradict them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no wasted words. It is appropriately concise, though its brevity leaves out useful routing context rather than adding structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has seven optional parameters, rich schema descriptions, annotations, and an output schema. The description is minimally adequate because the structured fields carry most of the needed detail, but it does not help an agent decide when to use this list tool over sibling retrieval tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all seven parameters are already well documented in the input schema. The description only mentions class and query filtering, adding no syntax or meaning beyond what the schema provides, which matches the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: list CMDB configuration items, with optional class and query filtering. It is clear what the tool does, but it does not distinguish itself from siblings like get_ci, list_records, or aggregate_records.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'optional class and query filtering' implies that filters can be used, but there is no explicit guidance on when to use this tool versus get_ci or list_records. No exclusions, prerequisites, or alternative routing are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List records from any ServiceNow table with optional filtering, field selection, and pagination
| 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 |
| Name | Required | Description |
|---|---|---|
| note | No | |
| count | Yes | |
| records | Yes | |
| warning | No | |
| truncated | No | |
| next_offset | No | |
| display_note | No |
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.
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.
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.
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.
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.
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.
List all customer updates (changes) within an update set
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of changes to return | |
| update_set_sys_id | Yes | The sys_id of the update set |
| Name | Required | Description |
|---|---|---|
| note | No | |
| count | Yes | |
| changes | Yes | |
| truncated | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the description carries a lighter burden. It adds nothing beyond them: it does not say that results are truncated at the default limit of 50, what the maximum of 500 implies, or whether an empty list means no changes versus an invalid sys_id. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler. It is arguably over-terse for a paginated list tool, but nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-shape explanation is not required, and the 2-parameter schema is fully documented. What is missing for a list tool is the pagination/truncation behavior — an agent calling with the default limit of 50 could silently miss changes in a large update set, and nothing in the description warns of that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both parameters, so the schema already explains limit (max 50/500 bounds) and update_set_sys_id. The description adds no meaning beyond that, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: list changes belonging to one update set, scoped by the required update_set_sys_id. That distinguishes it from list_update_sets (which enumerates the sets themselves) and get_update_set (which fetches a single set). It does not explicitly contrast with those siblings, and the phrase 'customer updates (changes)' is slightly loose, but the operation is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to use this tool rather than get_update_set, list_update_sets, or get_record, and no prerequisites (e.g., that the sys_id must come from list_update_sets). The 'within an update set' phrasing implies context but provides no routing guidance or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List update sets with optional state and query filtering
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of update sets to return | |
| query | No | Filter query (e.g., 'state=in progress', 'nameLIKErelease') | |
| state | No | Filter by state: 'in progress', 'complete', 'ignore', or 'default' |
| Name | Required | Description |
|---|---|---|
| note | No | |
| count | Yes | |
| truncated | No | |
| update_sets | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so safety is fully covered; the description adds only the optional-filter behavior. It says nothing about default page size, maximum results, ordering of results, or whether filtering combinations are combined with AND.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no filler; every clause (list, state filter, query filter) maps to actual capability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be described, and annotations carry the safety profile. What is missing for an agent to use it confidently is how this list relates to get_update_set and list_update_set_changes, and whether results are ordered or paginated beyond the limit cap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains limit, query syntax examples, and state values. The description merely names two of the three parameters and adds no syntax or combination semantics beyond that baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('List update sets') plus the supported filters, so the core operation is unambiguous. It does not distinguish this tool from related siblings such as get_update_set (single fetch) or list_update_set_changes (child records), so an agent must infer the boundary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use guidance, no exclusions, and no pointer to alternatives like get_update_set for a single record. Usage is only implied by the word 'List' and the presence of filtering options.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set an update set as the current active update set
| Name | Required | Description | Default |
|---|---|---|---|
| sys_id | Yes | The sys_id of the update set to make current |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate this is a non-readonly, idempotent, non-destructive operation. The description adds no further behavioral details, such as whether the change is persistent or affects the current session, which could be useful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words. It is well-structured and immediately understandable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema, the description is largely sufficient. It could be slightly more informative about what constitutes 'current active' or any side effects, but overall it provides enough context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter sys_id is described directly in the schema, and the description does not add extra semantic meaning beyond what is already provided. Since schema coverage is 100%, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: setting an update set as the current active one. The verb 'set' and the resource 'update set' are explicit, and the tool is easily distinguished from siblings like create_update_set or list_update_sets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
When to use this tool versus alternatives is implied by the name and description, but not explicitly stated. The description does not say 'use this to switch the active update set' or mention that create_update_set is for new ones.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a CMDB configuration item
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | CI attributes to update | |
| sys_id | Yes | The sys_id of the CI to update | |
| class_name | No | CMDB class name | cmdb_ci |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=true, so the safety profile is covered elsewhere. The description adds nothing about what a destructive update overwrites, permission requirements, or how class_name affects behavior, so it contributes no behavioral context beyond 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with zero waste, which is well structured. It is arguably too terse for a destructive mutation tool, but along the conciseness axis it earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive CMDB mutation with a nested free-form 'data' object and no output schema, the definition is thin: it says nothing about the shape of the nested attributes, the class_name default, or the effect of the update. Annotations cover the safety flags but not the operational detail an agent needs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so sys_id, data, and class_name are already documented in the schema. The description adds no syntax, format, or default guidance (e.g. the cmdb_ci default), leaving the baseline of 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Update a CMDB configuration item'), so an agent knows exactly what operation is performed. However, it does nothing to distinguish itself from siblings like update_record or create_ci, and never signals what a 'configuration item' update entails versus a generic record update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no mention of prerequisites, and no routing to alternatives such as update_record or create_ci. The agent is left to infer the entire selection context from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing record in a ServiceNow table
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | Fields to update as key-value pairs | |
| sys_id | Yes | The sys_id of the record to update | |
| table_name | Yes | The ServiceNow table name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds nothing beyond that: it doesn't say whether the 'data' object performs a partial merge or full replacement, nor what permissions are required, which is the key behavioral question for an update tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with zero filler and the resource named immediately. It is efficient, though the brevity borders on under-specification for a mutation tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Annotations cover the mutability/idempotency profile and the schema fully describes inputs, so the core is intact. The description is still silent on update semantics (merge vs replace) and any side effects, which matters for a destructive write into a full ServiceNow table.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters (table_name, sys_id, data) are documented in the schema itself. The description adds no format or syntax detail beyond that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear verb+resource ('Update an existing record in a ServiceNow table'), so the agent knows exactly the operation. However it offers no differentiation from the sibling update_ci or create_record/delete_record beyond the word 'record'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this versus siblings like update_ci or create_record, and no prerequisites or exclusions. The agent must infer the table/sys_id targeting model on its own.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.9.2aggregate_records2 fields changedInput schema / properties / display_valueAdded 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"
+}Input schema / properties / having / descriptionPrevious value: -"Post-aggregation filter (e.g., 'COUNT>5')"New value: +"Post-aggregation filter, aggregate^field^operator^value (e.g., 'count^name^>^1')"find_referencesget_ci1 field changedInput schema / properties / display_valueAdded 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"
+}get_ci_relationships1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "properties": {
+ "count": {
+ "type": "integer"
+ },
+ "next_offset": {
+ "type": "integer"
+ },
+ "note": {
+ "type": "string"
+ },
+ "relationships": {
+ "items": {
+ "additionalProperties": true,
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "truncated": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "count",
+ "relationships"
+ ],
+ "type": "object"
+}get_record1 field changedInput schema / properties / display_valueAdded 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"
+}get_system_properties1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "properties": {
+ "count": {
+ "type": "integer"
+ },
+ "note": {
+ "type": "string"
+ },
+ "properties": {
+ "items": {
+ "additionalProperties": true,
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "truncated": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "count",
+ "properties"
+ ],
+ "type": "object"
+}get_table_schema1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "properties": {
+ "field_count": {
+ "type": "integer"
+ },
+ "fields": {
+ "items": {
+ "additionalProperties": true,
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "hierarchy": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "note": {
+ "type": "string"
+ },
+ "table": {
+ "type": "string"
+ },
+ "truncated": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "table",
+ "hierarchy",
+ "field_count",
+ "fields"
+ ],
+ "type": "object"
+}list_ci3 fields changedInput schema / properties / display_valueAdded 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"
+}Input schema / properties / response_formatAdded 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"
+}Output schema / (root)Previous value: -nullNew value: +{
+ "properties": {
+ "class": {
+ "type": "string"
+ },
+ "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",
+ "class",
+ "records"
+ ],
+ "type": "object"
+}list_records3 fields changedInput schema / properties / display_valueAdded 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"
+}Input schema / properties / response_formatAdded 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"
+}Output 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"
+}list_update_set_changes1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "properties": {
+ "changes": {
+ "items": {
+ "additionalProperties": true,
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "count": {
+ "type": "integer"
+ },
+ "note": {
+ "type": "string"
+ },
+ "truncated": {
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "count",
+ "changes"
+ ],
+ "type": "object"
+}list_update_sets1 field changedOutput schema / (root)Previous value: -nullNew value: +{
+ "properties": {
+ "count": {
+ "type": "integer"
+ },
+ "note": {
+ "type": "string"
+ },
+ "truncated": {
+ "type": "boolean"
+ },
+ "update_sets": {
+ "items": {
+ "additionalProperties": true,
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "count",
+ "update_sets"
+ ],
+ "type": "object"
+}v0.9.1aggregate_records1 field changedInput schema / properties / table_name / descriptionPrevious value: -"The ServiceNow table name (e.g., 'incident', 'cmdb_ci')"New value: +"The ServiceNow table name (e.g., 'sys_user_group', 'cmdb_ci', 'incident')"delete_record1 field changedInput schema / properties / confirmRemoved value: -{
- "default": false,
- "description": "Acknowledge this destructive change. Only consulted when the server runs with --write-confirm and the client cannot show a confirmation dialog; ignored otherwise.",
- "type": "boolean"
-}get_current_user1 field changedInput schema / properties / fields / descriptionPrevious value: -"Comma-separated fields to return (default: user_name,name,email,roles)"New value: +"Extra sys_user fields to return besides user_name, user_display_name, user_email, user_sys_id and roles"get_table_schema1 field changedInput schema / properties / include_inherited / descriptionPrevious value: -"Include fields inherited from parent tables (e.g. task fields on incident)"New value: +"Include fields inherited from parent tables (e.g. cmdb_ci fields on cmdb_ci_server)"list_records1 field changedInput schema / properties / table_name / descriptionPrevious 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')"update_ci1 field changedInput schema / properties / confirmRemoved value: -{
- "default": false,
- "description": "Acknowledge this destructive change. Only consulted when the server runs with --write-confirm and the client cannot show a confirmation dialog; ignored otherwise.",
- "type": "boolean"
-}update_record1 field changedInput schema / properties / confirmRemoved value: -{
- "default": false,
- "description": "Acknowledge this destructive change. Only consulted when the server runs with --write-confirm and the client cannot show a confirmation dialog; ignored otherwise.",
- "type": "boolean"
-}v0.7.0aggregate_records1 field changedOutput schema / (root)Previous value: -{
- "additionalProperties": true,
- "type": "object"
-}New value: +nullcreate_ci1 field changedOutput schema / (root)Previous value: -{
- "additionalProperties": true,
- "type": "object"
-}New value: +nullcreate_record1 field changedOutput schema / (root)Previous value: -{
- "additionalProperties": true,
- "type": "object"
-}New value: +nullcreate_update_set1 field changedOutput schema / (root)Previous value: -{
- "additionalProperties": true,
- "type": "object"
-}New value: +nulldelete_record2 fields changedInput schema / properties / confirmAdded value: +{
+ "default": false,
+ "description": "Acknowledge this destructive change. Only consulted when the server runs with --write-confirm and the client cannot show a confirmation dialog; ignored otherwise.",
+ "type": "boolean"
+}Output schema / (root)Previous value: -{
- "properties": {
- "result": {
- "type": "string"
- }
- },
- "required": [
- "result"
- ],
- "type": "object",
- "x-fastmcp-wrap-result": true
-}New value: +nullget_ci1 field changedOutput schema / (root)Previous value: -{
- "additionalProperties": true,
- "type": "object"
-}New value: +nullget_ci_relationships3 fields changedInput schema / properties / limitAdded value: +{
+ "default": 100,
+ "description": "Maximum number of relationships to return",
+ "maximum": 1000,
+ "minimum": 1,
+ "type": "integer"
+}Input schema / properties / offsetAdded value: +{
+ "default": 0,
+ "description": "Number of relationships to skip",
+ "minimum": 0,
+ "type": "integer"
+}Output schema / (root)Previous value: -{
- "additionalProperties": true,
- "type": "object"
-}New value: +nullget_current_user1 field changedOutput schema / (root)Previous value: -{
- "additionalProperties": true,
- "type": "object"
-}New value: +nullget_record1 field changedOutput schema / (root)Previous value: -{
- "additionalProperties": true,
- "type": "object"
-}New value: +nullget_system_properties1 field changedOutput schema / (root)Previous value: -{
- "additionalProperties": true,
- "type": "object"
-}New value: +nullget_table_schema5 fields changedInput schema / properties / include_inheritedAdded value: +{
+ "default": true,
+ "description": "Include fields inherited from parent tables (e.g. task fields on incident)",
+ "type": "boolean"
+}Input schema / properties / limit / defaultPrevious value: -50New value: +200Input schema / properties / limit / descriptionPrevious value: -"Maximum number of fields to return"New value: +"Maximum number of fields to return (own fields first, then inherited)"Input schema / properties / limit / maximumPrevious value: -500New value: +1000Output schema / (root)Previous value: -{
- "additionalProperties": true,
- "type": "object"
-}New value: +nullget_update_set1 field changedOutput schema / (root)Previous value: -{
- "additionalProperties": true,
- "type": "object"
-}New value: +nulllist_ci1 field changedOutput schema / (root)Previous value: -{
- "additionalProperties": true,
- "type": "object"
-}New value: +nulllist_records1 field changedOutput schema / (root)Previous value: -{
- "additionalProperties": true,
- "type": "object"
-}New value: +nulllist_update_set_changes1 field changedOutput schema / (root)Previous value: -{
- "additionalProperties": true,
- "type": "object"
-}New value: +nulllist_update_sets1 field changedOutput schema / (root)Previous value: -{
- "additionalProperties": true,
- "type": "object"
-}New value: +nullset_current_update_set1 field changedOutput schema / (root)Previous value: -{
- "properties": {
- "result": {
- "type": "string"
- }
- },
- "required": [
- "result"
- ],
- "type": "object",
- "x-fastmcp-wrap-result": true
-}New value: +nullupdate_ci2 fields changedInput schema / properties / confirmAdded value: +{
+ "default": false,
+ "description": "Acknowledge this destructive change. Only consulted when the server runs with --write-confirm and the client cannot show a confirmation dialog; ignored otherwise.",
+ "type": "boolean"
+}Output schema / (root)Previous value: -{
- "additionalProperties": true,
- "type": "object"
-}New value: +nullupdate_record2 fields changedInput schema / properties / confirmAdded value: +{
+ "default": false,
+ "description": "Acknowledge this destructive change. Only consulted when the server runs with --write-confirm and the client cannot show a confirmation dialog; ignored otherwise.",
+ "type": "boolean"
+}Output schema / (root)Previous value: -{
- "additionalProperties": true,
- "type": "object"
-}New value: +nullv0.5.1aggregate_recordscreate_cicreate_recordcreate_update_setdelete_recordget_ciget_ci_relationshipsget_current_userget_recordget_system_propertiesget_table_schemaget_update_setlist_cilist_recordslist_update_set_changeslist_update_setsset_current_update_setupdate_ciupdate_recordScored across 20 tools
The generic record tools overlap substantially with the CI-specific tools: create_record/create_ci, update_record/update_ci, list_records/list_ci, and get_record/get_ci all target the CMDB table in different ways. Descriptions clarify the CMDB intent, but an agent must still decide whether to use the generic or specialized tool for the same underlying table.
All tool names use consistent snake_case and a verb_noun pattern such as create_record, list_records, get_update_set, and delete_record. The few compound names like set_current_update_set and get_ci_relationships remain predictable and readable.
Twenty tools is at the high end for a single MCP server and feels heavy, though the broad ServiceNow surface area (records, CMDB, update sets, metadata) explains much of the count. It is reasonable but not tightly scoped.
Core record CRUD is complete, and CMDB plus update-set workflows are mostly covered with schema, references, aggregation, and current-user tools. Minor gaps exist, such as no dedicated delete_ci or broader update-set lifecycle operations, but generic record tools can cover some of these.
One MCP endpoint for Claude, GPT & Gemini: 100+ tools + no-code connectors + agent workers.
Any REST/SOAP/GraphQL/OData/SQL API as MCP tools for Claude & ChatGPT. 561 connectors: SAP, ERP.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows