Skip to main content
Glama

run_discovery_scan

Triggers a ServiceNow Discovery scan for network or infrastructure from a schedule ID, optionally targeting a MID server or running asynchronously to avoid blocking.

Instructions

[Write] Trigger a ServiceNow Discovery scan for network/infrastructure

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": {
      "schedule_id": "<schedule_id>"
    },
    "name": "run_discovery_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.
mid_serverNoOptional MID server name
schedule_idYesDiscovery schedule sys_id to run

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv5.0.1
    • addedInput schema / properties / async
      Added value: +{
      +  "description": "Run 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.",
      +  "type": "boolean"
      +}
  2. First observedv1.0.2

TDQS

C2.9/5.0
Behavior2/5

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, so the '[Write]' prefix adds nothing new. The description omits what the scan actually does (targets, credentials needed, expected duration, side effects on network devices), leaving behavioral burden almost entirely on annotations and the async param description.

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?

A single short sentence with the mutation tag front-loaded and zero filler. It is efficient but borders on under-specification rather than being purely concise.

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

Completeness2/5

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

For a non-idempotent, open-world mutation with no output schema, the description says nothing about permissions required, what a successful trigger returns, or how to observe scan progress beyond the async path already covered in the schema. An agent has to infer most operational context.

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 description coverage is 100%, so schedule_id, mid_server and async are already documented in the schema, including the job-switching behavior for long calls. The description adds no further meaning beyond what is structured, making the baseline 3 appropriate.

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

Purpose4/5

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

The description states a specific verb and resource ('Trigger a ServiceNow Discovery scan') and scopes it to network/infrastructure, which clearly separates it from read-oriented siblings such as list_discovery_schedules or get_instance_scan_findings. It stops short of naming a sibling alternative, so it is not a 5.

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

Usage Guidelines2/5

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

There is no guidance on when to prefer this tool over related ones like scan_vulnerabilities or run_control_test, no prerequisites (e.g., an existing schedule must have a valid sys_id), and no statement about whether a scan can be re-run or cancelled. The only implicit cue is the '[Write]' tag.

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