Skip to main content
Glama
Sign In
now-sdk-ext-mcp

now-sdk-ext-mcp

by sonisoft-cnanda
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Add ACL Role

add_acl_role

Adds a role to a ServiceNow ACL so users holding it pass the role check and gain access to the ACL’s scripts; confirm the access change with the user before applying it.

Instructions

Add a role to an access control: users with that role then pass its role check (roles are alternatives), and reach any script the ACL has. This is a security change: before calling it, tell the user who gains or loses access and get their go-ahead. It elevates its own session to security_admin (only for ACL tools; other tools stay unelevated) and writes into the named update set, verifying each write by reading it back. To swap a role, add the new one before removing the old.

Input Schema

NameRequiredDescriptionDefault
roleYesThe role name to add.
scopeNoThe ACL's application: its scope name (e.g. "x_acme_app"), or "global". Give this or scope_id.
sys_idYesThe ACL's sys_id.
instanceNoThe ServiceNow instance auth alias to connect to. This is the alias configured via `snc configure` (e.g., "myinstance", "prod", "test"). The user will typically refer to this by name when saying things like "on my myinstance instance". If not provided, falls back to the SN_AUTH_ALIAS environment variable.
scope_idNoThe ACL's application by sys_scope sys_id, instead of scope.
update_setYessys_id of an In progress update set of that application (create one with create_update_set). Every write is captured there and verified; the user's own current update set is left as it is.
acknowledge_upgrade_skipNoOnly for an installed Store application, and only after the user has reviewed it: upgrades of that application then skip this ACL until the customization is reviewed.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv5.5.0

TDQS

A4.4/5.0
Behavior5/5

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

Beyond the annotations, the description discloses important behavior: this is a security change, it elevates the session to security_admin only for ACL tools, it writes into the named update set, and it verifies each write by reading it back. These details materially help an agent understand risk and side effects.

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?

The description is front-loaded with the core action and effect, then adds security, elevation, update-set, and swap-order context in a compact sequence. Every sentence contributes useful information without repetition.

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 a security-sensitive mutation with seven parameters and no output schema, the description covers the key operational concerns: approval, elevation, update-set capture, write verification, and role-swap ordering. It does not describe duplicate-role behavior, failure modes, or return values, which are minor remaining gaps.

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 parameter meanings are already well documented in the schema. The description adds useful context about role alternatives and swap ordering, but it does not significantly extend the meaning of individual parameters beyond the schema.

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?

The description uses a specific verb and resource: add a role to an ACL. It explains the effect precisely, including that users with the role pass its check and reach ACL scripts, and it distinguishes the operation from removal by explaining the swap sequence.

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?

It gives a clear prerequisite for use: notify the user who gains or loses access and obtain approval before calling. It also gives sequencing guidance for role swaps by saying to add the new role before removing the old, though it does not explicitly name remove_acl_role or state when not to use this tool.

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