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, expanding every user-and-role pair into a single approved batch run.

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. Changed2 schema fields changedv0.1.8
    • removedInput schema / additionalProperties
      Removed value: -false
    • removedInput schema / properties / assignments / items / additionalProperties
      Removed value: -false
  2. First observedv0.1.5

TDQS

A4.8/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 and does so well: it discloses the dry-run behavior without confirm, the mutation/live-environment impact, the admin-account requirement (profile/CPS_ADMIN_PROFILE), per-row independence with partial failure semantics, the call-explosion cost model, and an honesty caveat ('Unverified against a live tenant'). This is unusually rich behavioral context.

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 purpose, then cost model, dry-run safety, and the alternative. Dense but nearly every sentence earns its place; it runs slightly long, with the admin-account and unverified notes stacked near the end rather than in priority order.

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 being an 8-param mutation tool with no annotations and no output schema, the description covers safety, auth, partial-failure semantics, cost, and the return shape of the dry run. Nothing critical to calling it correctly is missing.

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, but the description adds meaning beyond the schema by explaining confirm as the live-vs-dry-run switch and the profile defaulting. It also contextualizes the roster expansion, though much parameter detail (CSV column syntax, background behavior) is already in 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?

States a specific verb+resource+scope ('Give many users their security roles in one environment, from a CSV roster or an inline list') and immediately distinguishes itself from the single-assignment path ('pac assigns one user and one role per call') and from cs_admin_assign_group. An agent can identify the tool's job without opening the schema.

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 names when to use the alternative: 'Prefer cs_admin_assign_group when the roster is really a group.' It also gives the operating condition (requires confirm:true to change a live environment) so the agent knows when to set the flag. When-to-use, when-not, and the alternative are all present.

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