Skip to main content
Glama

sn_atf

List ServiceNow ATF tests and suites, read legacy results, and return migration guidance for running tests or suites through the supported runner.

Instructions

Automated Test Framework — list tests/suites and read legacy results. Run actions return migration guidance for sn_atf_run.

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": {
      "action": "<action>",
      "profile": "<profile>"
    },
    "name": "sn_atf"
  }
}

Input Schema

NameRequiredDescriptionDefault
waitNoWait for test/suite completion (default true)
limitNoMax results (default 20, max 1000)
actionYesATF operation: list tests, list suites, run a test, run a suite, or get results
fieldsNoComma-separated fields to return
offsetNoDeterministic result offset (default 0)
profileYesConfigured ServiceNow profile name (required; no default fallback).
timeoutNoMax wait time in seconds (default 120 for tests, 300 for suites)
suite_nameNoFilter tests by suite name (for list action)
test_sys_idNo32-hex test sys_id (required for run)
execution_idNo32-hex execution/result sys_id (required for results action)
suite_sys_idNo32-hex suite sys_id (required for run-suite)

Output Schema

NameRequiredDescriptionDefault
dataYes
profileYesConfigured ServiceNow profile name (required; no default fallback).
metadataYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv2.3.0
    • addedOutput schema / properties / metadata / properties / cache
      Added value: +{
      +  "enum": [
      +    "hit",
      +    "miss",
      +    "bypass",
      +    "mixed"
      +  ],
      +  "type": "string"
      +}
    • addedOutput schema / properties / metadata / properties / timing
      Added value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "total_ms": {
      +      "minimum": 0,
      +      "type": "integer"
      +    },
      +    "upstream_ms": {
      +      "minimum": 0,
      +      "type": "integer"
      +    },
      +    "watermark_ms": {
      +      "minimum": 0,
      +      "type": "integer"
      +    }
      +  },
      +  "required": [
      +    "total_ms",
      +    "upstream_ms",
      +    "watermark_ms"
      +  ],
      +  "type": "object"
      +}
  2. Changed18 schema fields changedv2.2.0
    • addedInput schema / additionalProperties
      Added value: +false
    • changedInput schema / properties / execution_id / description
      Previous value: -"Execution/result sys_id (required for results action)"New value: +"32-hex execution/result sys_id (required for results action)"
    • addedInput schema / properties / execution_id / pattern
      Added value: +"^[0-9a-f]{32}$"
    • addedInput schema / properties / limit / default
      Added value: +20
    • changedInput schema / properties / limit / description
      Previous value: -"Max results (default 20)"New value: +"Max results (default 20, max 1000)"
    • addedInput schema / properties / limit / maximum
      Added value: +1000
    • addedInput schema / properties / limit / minimum
      Added value: +1
    • changedInput schema / properties / limit / type
      Previous value: -"number"New value: +"integer"
    • addedInput schema / properties / offset
      Added value: +{
      +  "default": 0,
      +  "description": "Deterministic result offset (default 0)",
      +  "maximum": 10000,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • addedInput schema / properties / profile
      Added value: +{
      +  "description": "Configured ServiceNow profile name (required; no default fallback).",
      +  "maxLength": 128,
      +  "minLength": 1,
      +  "type": "string"
      +}
    • removedInput schema / properties / query
      Removed value: -{
      -  "description": "ServiceNow encoded query filter",
      -  "type": "string"
      -}
    • changedInput schema / properties / suite_sys_id / description
      Previous value: -"Suite sys_id (required for run-suite)"New value: +"32-hex suite sys_id (required for run-suite)"
    • addedInput schema / properties / suite_sys_id / pattern
      Added value: +"^[0-9a-f]{32}$"
    • changedInput schema / properties / test_sys_id / description
      Previous value: -"Test sys_id (required for run)"New value: +"32-hex test sys_id (required for run)"
    • addedInput schema / properties / test_sys_id / pattern
      Added value: +"^[0-9a-f]{32}$"
    • addedInput schema / properties / wait / default
      Added value: +true
    • changedInput schema / required
      Previous value: -[
      -  "action"
      -]New value: +[
      +  "action",
      +  "profile"
      +]
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "additionalProperties": false,
      +  "properties": {
      +    "data": {
      +      "additionalProperties": false,
      +      "properties": {
      +        "action": {
      +          "enum": [
      +            "list",
      +            "suites",
      +            "run",
      +            "run-suite",
      +            "results"
      +          ],
      +          "type": "string"
      +        },
      +        "result": {
      +          "anyOf": [
      +            {
      +              "type": "null"
      +            },
      +            {
      +              "type": "string"
      +            },
      +            {
      +              "type": "number"
      +            },
      +            {
      +              "type": "boolean"
      +            },
      +            {
      +              "additionalProperties": {},
      +              "propertyNames": {
      +                "type": "string"
      +              },
      +              "type": "object"
      +            },
      +            {
      +              "items": {},
      +              "type": "array"
      +            }
      +          ]
      +        }
      +      },
      +      "required": [
      +        "action",
      +        "result"
      +      ],
      +      "type": "object"
      +    },
      +    "metadata": {
      +      "additionalProperties": false,
      +      "properties": {
      +        "kind": {
      +          "enum": [
      +            "single",
      +            "collection",
      +            "operation"
      +          ],
      +          "type": "string"
      +        },
      +        "limits": {
      +          "additionalProperties": false,
      +          "properties": {
      +            "max_bytes": {
      +              "maximum": 14680064,
      +              "minimum": 1000,
      +              "type": "integer"
      +            },
      +            "max_records": {
      +              "exclusiveMinimum": 0,
      +              "maximum": 9007199254740991,
      +              "type": "integer"
      +            }
      +          },
      +          "required": [
      +            "max_records",
      +            "max_bytes"
      +          ],
      +          "type": "object"
      +        },
      +        "pagination": {
      +          "anyOf": [
      +            {
      +              "additionalProperties": false,
      +              "properties": {
      +                "mode": {
      +                  "const": "none",
      +                  "type": "string"
      +                }
      +              },
      +              "required": [
      +                "mode"
      +              ],
      +              "type": "object"
      +            },
      +            {
      +              "additionalProperties": false,
      +              "properties": {
      +                "has_more": {
      +                  "type": "boolean"
      +                },
      +                "limit": {
      +                  "exclusiveMinimum": 0,
      +                  "maximum": 9007199254740991,
      +                  "type": "integer"
      +                },
      +                "mode": {
      +                  "const": "offset",
      +                  "type": "string"
      +                },
      +                "next_offset": {
      +                  "maximum": 9007199254740991,
      +                  "minimum": 0,
      +                  "type": "integer"
      +                },
      +                "offset": {
      +                  "maximum": 9007199254740991,
      +                  "minimum": 0,
      +                  "type": "integer"
      +                },
      +                "order_by": {
      +                  "items": {
      +                    "minLength": 1,
      +                    "type": "string"
      +                  },
      +                  "maxItems": 8,
      +                  "minItems": 1,
      +                  "type": "array"
      +                },
      +                "recovery": {
      +                  "const": "adjust_request_and_retry_same_offset",
      +                  "type": "string"
      +                },
      +                "returned": {
      +                  "maximum": 9007199254740991,
      +                  "minimum": 0,
      +                  "type": "integer"
      +                }
      +              },
      +              "required": [
      +                "mode",
      +                "limit",
      +                "offset",
      +                "returned",
      +                "has_more",
      +                "order_by"
      +              ],
      +              "type": "object"
      +            }
      +          ]
      +        },
      +        "record_count": {
      +          "maximum": 9007199254740991,
      +          "minimum": 0,
      +          "type": "integer"
      +        },
      +        "truncation": {
      +          "additionalProperties": false,
      +          "properties": {
      +            "dropped_records": {
      +              "maximum": 9007199254740991,
      +              "minimum": 0,
      +              "type": "integer"
      +            },
      +            "reason": {
      +              "enum": [
      +                "record_limit",
      +                "byte_limit"
      +              ],
      +              "type": "string"
      +            },
      +            "truncated": {
      +              "type": "boolean"
      +            }
      +          },
      +          "required": [
      +            "truncated"
      +          ],
      +          "type": "object"
      +        }
      +      },
      +      "required": [
      +        "kind",
      +        "record_count",
      +        "limits",
      +        "pagination",
      +        "truncation"
      +      ],
      +      "type": "object"
      +    },
      +    "profile": {
      +      "description": "Configured ServiceNow profile name (required; no default fallback).",
      +      "maxLength": 128,
      +      "minLength": 1,
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "data",
      +    "metadata",
      +    "profile"
      +  ],
      +  "type": "object"
      +}
  3. First observedv1.0.0

TDQS

A3.8/5.0
Behavior3/5

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

Annotations are thin (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the description carries much of the load, and it does disclose one important trait: run actions do not actually execute tests but return migration guidance. However, the annotation title 'Run ATF tests' points the opposite way, and the description says nothing about blocking behavior from 'wait', what 'legacy' results mean, or permission requirements for the profile.

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?

Two sentences with no filler: capability first, migration routing second. Nothing is repeated from the schema and there is no surplus wording.

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 11-parameter, five-action tool the description covers scope and the main invocation trap (run actions are non-functional here). Because the input schema is fully documented and an output schema exists, return values and parameter detail need not be restated. It is only slightly thin on the results path and on the blocking semantics of 'wait'.

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 the baseline is 3; every parameter including the action enum is already documented. The description adds one genuinely useful semantic beyond the schema: that action=run/run-suite does not run tests but returns guidance. It adds nothing about profile, fields, limit/offset, or timeout beyond what the schema states.

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 names specific operations against a specific resource: 'list tests/suites and read legacy results', and explicitly routes run/run-suite elsewhere ('Run actions return migration guidance for sn_atf_run'). That separates it cleanly from the sibling sn_atf_run. It stops short of distinguishing it from sn_atf_results, since 'legacy results' is not explained relative to non-legacy results.

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 second sentence is a direct usage rule: if you want to run something, this tool will only hand back migration guidance pointing at sn_atf_run, so the agent should call that sibling instead. That is an explicit when-not-to-use and an alternative. Still missing is any guidance on choosing this over sn_atf_results for retrieving results.

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