Skip to main content
Glama

run_instance_scan

Run a ServiceNow Instance Scan through the CI/CD API for saved suites, combos, scoped apps, update sets, point records, or full scans; returns a progress ID and supports async jobs.

Instructions

Start an Instance Scan through the CI/CD API: a saved suite scan (by suite or combo), a suite against scoped apps or update sets, a point scan of one record, or a full scan. Returns the progress id; pass async: true to follow the scan to the end as a job. Requires WRITE_ENABLED=true

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": {
      "scan_type": "<scan_type>"
    },
    "name": "run_instance_scan"
  }
}

Input Schema

NameRequiredDescriptionDefault
asyncNoRun as a background job and return a job_id at once. Poll it with get_job. Calls that take longer than about 20 seconds switch to a job on their own.
suiteNoSuite name or sys_id (suite, scoped_apps, update_sets)
scan_typeYessuite re-runs the saved instance-wide scan of a suite; full runs every active check and can take a long time
combo_sys_idNoscan_combo sys_id to re-run (combo)
target_tableNoTable of the record to scan (point)
target_sys_idNosys_id of the record to scan (point)
app_scope_sys_idsNosys_scope sys_ids to scan (scoped_apps)
update_set_sys_idsNosys_update_set sys_ids to scan (update_sets)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv5.1.0

TDQS

A3.9/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=false, openWorldHint=true, and non-idempotent, so the write nature is not news. The description does add genuinely new context: it returns a progress id, async:true follows the scan as a job, and it requires WRITE_ENABLED=true – a real precondition an agent must know. It stops short of describing side effects or re-run behavior, so it sits just above baseline.

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

Conciseness4/5

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

Front-loaded with the action and the mode list, then the return value and the prerequisite. It is dense and every sentence adds something, though the mode enumeration is somewhat compressed into one packed clause.

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

Completeness4/5

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

For an 8-parameter mutation tool with no output schema, the description covers the return value (progress id), the async/job path, and the WRITE_ENABLED precondition. Remaining gaps – side effects of a full scan, permissions beyond the write flag – are minor.

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

Parameters3/5

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

Schema coverage is 100% and each property already documents its scan_type association, so the schema carries the parameter burden. The description restates the mode-to-parameter mapping and the async option but adds no format or syntax detail beyond it; baseline 3 is correct.

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 ("Start an Instance Scan") and immediately enumerates the scan modes it supports, which map onto the scan_type enum. An agent can distinguish this from the get_instance_scan_* siblings, which read results rather than start scans.

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

Usage Guidelines4/5

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

The clause listing saved suite (by suite or combo), suite against scoped apps/update sets, point scan of one record, and full scan gives clear selection guidance for each mode. It does not explicitly say when not to use it versus the findings/summary siblings, but the start-vs-read split is clear enough.

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

Deploy Server

Other Tools