Skip to main content
Glama

test_agent_access

Read-onlyIdempotent

Checks whether a user can access an AI agent, agentic workflow, or Now Assist skill and explains the verdict from active status, ACL roles, and data-access settings.

Instructions

Answer "can this user use this AI agent, agentic workflow or Now Assist skill?" with the reasons. Works it out from the instance data: whether the asset is active, its execute ACLs (types gen_ai_agent, gen_ai_workflow, gen_ai_skill, falling back to the type's wildcard rule), the roles on those ACLs, the skill role filter (in_product_roles) and the user's active roles. Also reports data access: run-as user and role masking (sys_agent_access_role_configuration). ACL conditions, scripts and custom security attributes are reported as not evaluated, and the verdict is then undetermined. This models the platform check. It is not ServiceNow's own "Test access" (AI Agent Studio, Brazil) or Access Analyzer, which have no documented REST API.

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": {
      "user": "<user>",
      "target": "<target>"
    },
    "name": "test_agent_access"
  }
}

Input Schema

NameRequiredDescriptionDefault
userYesUser sys_id, user_name or email
targetYessys_id or name of the agent, workflow or skill
target_typeNoagent (AI agent), workflow (agentic workflow / use case) or skill (Now Assist skill). Default agent.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv5.0.1

TDQS

A4.4/5.0
Behavior5/5

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

Annotations cover safety (readOnly, idempotent, non-destructive), and the description goes well beyond them: it discloses the evaluation method, the ACL type fallback rule, that run-as and role masking (sys_agent_access_role_configuration) are also reported, and critically that ACL conditions, scripts and custom attributes are reported as not evaluated with an undetermined verdict. That last caveat is exactly the kind of limitation an agent needs to avoid over-trusting the result.

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?

Front-loaded with the question being answered, then the evidence sources, then caveats and disambiguation — a sensible order with no filler. It is dense and slightly long, and the disclaimer sentence about ServiceNow's built-in tools could be tightened, but every sentence carries information.

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?

With no output schema, the description carries the burden and does so: it states what the answer contains (verdict plus reasons), what supporting data is reported (ACL roles, skill role filter, run-as user, role masking), and when the verdict degrades to undetermined. Nothing essential for correct invocation or interpretation appears 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 coverage is 100% and each parameter already documents accepted formats (sys_id/user_name/email, sys_id or name, enum meanings), so the schema does the heavy lifting. The description adds conceptual framing — that target_type selects among agent, workflow, or skill — but no syntax or format detail beyond the schema. Baseline 3 applies.

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?

Opens with the exact question it answers ("can this user use this AI agent, agentic workflow or Now Assist skill?") and names the specific inputs it evaluates — activation state, execute ACLs of types gen_ai_agent/gen_ai_workflow/gen_ai_skill with wildcard fallback, ACL roles, skill role filter, and user active roles. It also explicitly separates itself from the platform's own "Test access" and Access Analyzer, so an agent can tell what this tool is and is not.

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?

Usage context is clear: use it to answer an access/entitlement question for a specific user against a specific AI asset, with a note that it models the platform check rather than calling ServiceNow's UI features. It does not explicitly name or exclude MCP siblings such as test_now_assist_skill or test_flow, so routing among in-server alternatives is left to inference.

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