Skip to main content
Glama
servicenow-mcp

servicenow-mcp

sn_apply_plan

Destructive

Applies an approved plan to a ServiceNow record: re-reads to refuse if changed, writes exactly the planned fields, then reads back to report any fields ServiceNow stored differently.

Instructions

Write a plan made by sn_plan_change, only after the user has agreed to its changes. For an existing record it first reads the record again and refuses if anything changed since the plan was made. It sends exactly the planned fields, then reads the record back and reports any field ServiceNow stored differently, for example because a business rule changed it. If ServiceNow refuses the write, nothing changes and the plan stays unapplied with the reason kept in it. This is a write tool. It refuses to run unless the server was started with SN_ALLOW_WRITE=1 or SN_ALLOW_WRITE=plan.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "plan_id": "<plan_id>"
    },
    "name": "sn_apply_plan"
  }
}

Input Schema

NameRequiredDescriptionDefault
plan_idYesThe plan_id that sn_plan_change returned. Example: 20261016-101500-1a2b3c4d.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only say this is a destructive write; the description goes far beyond by disclosing optimistic-concurrency re-read and refusal on change, that exactly the planned fields are sent, that the record is read back and divergences reported, and that a refused write leaves state untouched with the reason recorded in the plan. It also discloses the SN_ALLOW_WRITE gating requirement, which is essential operational context an agent cannot get from annotations.

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

Conciseness5/5

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

The most consequential facts are front-loaded: what it does, the precondition, and the write-tool warning. Every sentence carries distinct information about concurrency, field selection, verification, or failure behaviour, with no restatement of the name or schema.

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

Completeness5/5

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

No output schema exists, and the description compensates by explaining what is reported back after the write, including the divergence report. Combined with the staleness guard and the permission gate, an agent has everything needed to invoke it safely for a destructive one-parameter tool.

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

Parameters5/5

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

With a single fully-documented parameter the schema already covers the mechanics, but the description adds provenance value by tying plan_id to the output of sn_plan_change. That tells the agent where the value must come from rather than just its shape.

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

Purpose5/5

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

States a specific verb and resource ('Write a plan made by sn_plan_change') and immediately distinguishes itself from the sibling that produces the plan. An agent can tell this is the apply step versus the planning step without opening either schema.

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

Usage Guidelines4/5

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

Gives a clear precondition ('only after the user has agreed to its changes') and names the tool that must run first (sn_plan_change), plus refusal conditions tied to staleness and server config. It does not mention sibling options such as sn_check_plan for previewing or sn_undo_plan for reversal, so the alternative routing is implied rather than explicit.

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