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

now-sdk-ext-mcp

by sonisoft-cnanda
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Remove ACL Role

remove_acl_role
Destructive

Removes a role from a ServiceNow ACL to revoke that role's access, requiring user confirmation, session elevation, and update set capture so every write is verified.

Instructions

Remove a role from an access control. 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. Removing the last role makes the platform put snc_internal back, which lets every internal user past the role check, so any script on the ACL then runs for them: add the intended role first. Never remove a role shown only as a sys_id (hidden): its name is unknown to this session.

Input Schema

NameRequiredDescriptionDefault
roleYesThe role name to remove.
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.3/5.0
Behavior5/5

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

Well beyond the annotations (which only say destructive, non-idempotent, open-world), it discloses session elevation to security_admin scoped to ACL tools, that writes go into a named update set and are verified by read-back, and the security consequence of removing the last role (snc_internal restored, letting all internal users past the role check). This is exactly the hidden-mutation and side-effect context an agent needs before writing.

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?

Purpose is front-loaded in the first clause, followed by consent requirements, elevation behavior, and the dangerous edge case in descending order of importance. No sentence is filler; even the long final sentence carries a genuine safety constraint.

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

Completeness5/5

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

For a destructive, open-world mutation with full schema coverage and no output schema, the description covers the safety profile, the elevation side effect, the update-set capture model, and the last-role hazard. Nothing an agent needs in order to call this correctly is missing.

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 each of the seven parameters is already documented, including the scope/scope_id pairing, instance alias, and update_set. The description adds only indirect meaning, such as the role-name-only constraint and the consequence of removing the final role; it does not clarify any specific parameter beyond the schema.

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 opens with a specific verb and resource: 'Remove a role from an access control.' That is unambiguous and clearly the inverse of add_acl_role, so an agent can distinguish it from the sibling set without opening the schema. It stops short of explicitly naming the alternative tool, which keeps it from 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 Guidelines4/5

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

It supplies real preconditions: get user consent after explaining who gains or loses access, add the intended role before removing the last one, and never remove a role that only appears as a sys_id. These are explicit when-to and when-not signals. It never names sibling tools like add_acl_role or get_acl as the alternative path, so it is strong but not complete.

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