Skip to main content
Glama

create_ai_agent

Create ServiceNow AI agent definitions with specified capabilities and optional auto-generated execute ACLs to control who can invoke the agent.

Instructions

Create an AI agent definition with optional auto-generated ACLs (requires NOW_ASSIST_ENABLED + WRITE_ENABLED)

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": {
      "name": "<name>",
      "description": "<description>",
      "capabilities": "<capabilities>"
    },
    "name": "create_ai_agent"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameYesAgent name
roleNoAgent role/purpose, e.g. "Service desk triage specialist" (default: the description)
descriptionYesAgent description
capabilitiesYesTools to attach: AI Agent tool (sn_aia_tool) names or sys_ids. Unknown entries are reported, not created
instructionsNoAgent instructions for its first version (default: the description)
auto_generate_aclsNoCreate the execute ACL (type gen_ai_agent) that controls who can invoke the agent (default true)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv5.0.1
    • changedInput schema / properties / auto_generate_acls / description
      Previous value: -"Automatically create ACL records for the agent (default true)"New value: +"Create the execute ACL (type gen_ai_agent) that controls who can invoke the agent (default true)"
    • changedInput schema / properties / capabilities / description
      Previous value: -"List of capability identifiers the agent supports"New value: +"Tools to attach: AI Agent tool (sn_aia_tool) names or sys_ids. Unknown entries are reported, not created"
    • addedInput schema / properties / instructions
      Added value: +{
      +  "description": "Agent instructions for its first version (default: the description)",
      +  "type": "string"
      +}
    • addedInput schema / properties / role
      Added value: +{
      +  "description": "Agent role/purpose, e.g. \"Service desk triage specialist\" (default: the description)",
      +  "type": "string"
      +}
  2. Addedv4.9.0

TDQS

A3.6/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, so the description need not restate safety. It adds real context beyond them: that the call can also create execute ACLs (type gen_ai_agent) as a side effect, and that two feature/environment flags must be enabled before the operation is permitted. What remains unsaid is failure behavior (duplicate names, unsupported capability entries beyond the schema note) and the response payload.

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 no filler; the verb and resource lead and the prerequisite is compressed into a parenthetical. It is arguably over-compressed, since the ACL clause drops its verb and reads as a fragment, but nothing is redundant.

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?

For a six-parameter mutating create tool with no output schema, the description says nothing about what is returned (e.g., the new agent's sys_id or the generated ACLs) or what happens on name collisions. It covers prerequisites and the ACL side effect but leaves an agent guessing about the result of a successful call.

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%, with each of the six parameters documented including defaults for role, instructions, and auto_generate_acls. The description adds nothing parameter-level beyond what the schema already provides, so the baseline of 3 applies.

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?

States a specific verb and resource ('Create an AI agent definition') and flags its distinctive side effect ('optional auto-generated ACLs'), which separates it from the get_/list_/attach_ siblings. It does not explicitly name an alternative, but the create intent is unambiguous against the surrounding tool set.

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

Usage Guidelines3/5

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

The parenthetical prerequisite ('requires NOW_ASSIST_ENABLED + WRITE_ENABLED') is useful gating information for when the call will succeed, but there is no guidance on when to prefer this over other creation paths or any exclusions. Usage context is implied by the prerequisites rather than stated as guidance.

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