Skip to main content
Glama

trigger_flow

Trigger a published Flow Designer flow or subflow with optional inputs through ServiceNow's server-side FlowAPI, running it in the background. Use it when no REST endpoint exists.

Instructions

Trigger a published Flow Designer flow or subflow in the background with optional inputs, via the server-side sn_fd.FlowAPI runner (requires WRITE_ENABLED=true and SCRIPTING_ENABLED=true; ServiceNow has no REST endpoint for this)

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": {
      "flow_sys_id": "<flow_sys_id>"
    },
    "name": "trigger_flow"
  }
}

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.
inputsNoKey-value pairs for flow input variables
flow_sys_idYessys_id of the flow to trigger

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

A4/5.0
Behavior4/5

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

Annotations already declare non-read-only, non-idempotent, non-destructive, open-world behavior; the description adds genuinely new context: the dependency on two system properties, the lack of a REST endpoint, and background execution with auto-switch to a job past ~20 seconds. It does not describe how repeated triggers behave despite idempotentHint=false, but that is a minor omission.

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 front-loaded sentence with the operation first and the caveats in a compact parenthetical. Dense but every clause carries information; no padding or restatement of the title.

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

Completeness3/5

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

With no output schema, the description never states what a synchronous trigger returns (e.g., execution sys_id or result object), leaving the agent to infer it; only the async path's job_id is documented, and that comes from the schema. For a mutation tool this is an appreciable gap, though prerequisites and execution model are well covered.

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 the async parameter's schema description already explains the job_id/poll-with-get_job and ~20s fallback behavior, so the description cannot claim that value. Its only added semantic is that inputs are optional and come from the flow definition, which is marginal.

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 (Trigger) and resource (a published Flow Designer flow or subflow), plus the execution mechanism (server-side sn_fd.FlowAPI runner). An agent can distinguish this from create_flow, test_flow, or publish_flow without opening any 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?

Constrains usage to *published* flows and subflows and names the prerequisites (WRITE_ENABLED=true, SCRIPTING_ENABLED=true), which tells the agent when the call will fail. It stops short of explicitly contrasting with test_flow or trigger_scheduled_job, so the alternative-selection guidance is implicit rather than stated.

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