Skip to main content
Glama
jgt87

Copilot Studio MCP

by jgt87
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Assign security roles to a roster of users

cs_admin_assign_users

Assign security roles to many users in one Copilot Studio environment from a CSV roster or inline list, with a dry-run plan before applying changes.

Instructions

Give many users their security roles in one environment, from a CSV roster or an inline list. pac assigns one user and one role per call, so a roster of ten developers with three roles each is thirty calls; this expands the roster and runs them under a single approval. Without confirm it returns the plan: every user-and-role pair it would attempt, so you can read the whole thing before any of it happens. Rows are independent, so a bad UPN or a role the environment does not have is reported and the rest still run. Changes a live environment: requires confirm: true. Runs as the admin account: pass 'profile' or set CPS_ADMIN_PROFILE. Prefer cs_admin_assign_group when the roster is really a group: that is one call per role however many people are in it, and new joiners inherit access. Unverified against a live tenant.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
csvNoPath to a CSV roster. Header row needs a user column (user, upn, email) and a roles column (roles, role); several roles in one cell separated by comma, semicolon or pipe. Optional businessUnit and applicationUser columns. A user on several rows accumulates their roles.
confirmNoRequired to actually perform a change in a live environment. Without it the tool returns a dry run.
profileNopac auth profile of the admin account; default CPS_ADMIN_PROFILE, then the active profile
backgroundNoRun in the background and return a jobId immediately, then poll cs_job_status. MCP clients cut a tool call off after about 60 seconds; this operation can take much longer, and without this the work is orphaned rather than cancelled.
assignmentsNoRoster inline instead of a CSV file
environmentYesEnvironment id or URL to assign the roles in
businessUnitNoBusiness unit for rows that do not name one
continueOnErrorNoDefault true: one failed row does not abort the roster. false stops at the first failure.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.5

TDQS

A4.9/5.0
Behavior5/5

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

No annotations are provided, so the description carries the full burden. It clearly states this is a mutating operation ('Changes a live environment: requires confirm: true'), explains the dry-run behavior without confirm, notes that rows are independent (errors don't abort remaining rows), mentions the single approval mechanism, and warns that it runs as an admin account requiring a specific profile. It also discloses that it is unverified against a live tenant, which is a critical trait. This is exemplary given zero annotation support.

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 dense and informative, covering all critical aspects in a single paragraph. Every sentence serves a purpose: purpose, difference from siblings, dry-run behavior, error handling, mutation requirement, profile handling, alternative tool preference, and verification status. It is front-loaded with the main purpose and usage, and the length is appropriate for the tool's complexity (8 parameters, multiple behavioral nuances). No fluff or repetition.

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?

Despite having no output schema and 8 parameters, the description covers everything an agent needs to call this tool effectively: the two input methods (csv and assignments), the confirm requirement, background execution for long operations, profile handling, and the alternative tool. It also mentions error behavior and dry-run. The only minor gap is the exact return format of the dry-run plan, but the description says 'you can read the whole thing before any of it happens', which is adequate. Given the tool's complexity, this is remarkably complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/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. However, the description adds valuable context beyond the schema: it explains the CSV header format (user/upn/email, roles/role), how multiple roles are separated, and that users can accumulate roles across rows. It also clarifies the 'confirm' flag's role in making actual changes and the 'background' flag's purpose in avoiding MCP timeout issues. This goes well beyond the schema descriptions and helps the agent correctly construct input.

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?

States a specific verb ('assign'), resource ('security roles'), and recipient ('roster of users'), and clearly distinguishes itself from the sibling cs_admin_assign_user (single user) and cs_admin_assign_group (group-based). The description explicitly mentions 'many users' and 'one environment', making the scope unambiguous.

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

Usage Guidelines5/5

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

Explicitly contrasts with cs_admin_assign_group (when the roster is a group) and mentions when to use it. It also provides guidance on the confirm flag (dry run vs live), how to handle large rosters (background), and the need to set the admin profile. The description says 'Prefer cs_admin_assign_group when the roster is really a group' and explains the benefit, leaving no ambiguity about when 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