Skip to main content
Glama
Sign In
magicsword-mcp

magicsword-mcp

Official
by magicsword-io
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

Preview or confirm a policy assignment

apply_policy_to_endpoints
Destructive

Previews target computers and commits a policy assignment to selected endpoints, hostnames, or groups using a server confirmation token.

Instructions

Requires policies:write and endpoints:read. Preview exactly one selector: endpoint_ids for one/many computers, hostname_pattern, or group_ids. Groups include current subgroup members by default, capped at 500 eligible computers; no future-member binding. Show the concrete computers, policy status/mode and replacement warning to the human. After approval call again with ONLY policy_id and confirmation_token from that preview. confirm=true alone cannot commit. The one-time server token freezes the target IDs; stale policy/assignments or ineligible computers reject the whole operation. This replaces desired assignments and may remove existing protections or schedule an enforcing policy. Success means desired state is saved, not that computers have installed it. Never automatically retry writes.

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": {
      "policy_id": "<policy_id>"
    },
    "name": "apply_policy_to_endpoints"
  }
}

Input Schema

NameRequiredDescriptionDefault
confirmNoLegacy flag: true without a server confirmation_token is rejected
platformNoHostname selector only: optional platform filter
group_idsNoExisting group IDs; exclusive with endpoint_ids/hostname_pattern
policy_idYesPolicy ID to assign
endpoint_idsNoOne or more endpoint IDs; exclusive with hostname_pattern/group_ids
hostname_patternNoCase-insensitive hostname glob; exclusive with endpoint_ids/group_ids
confirmation_tokenNoServer token: commit uses only policy_id and this token after approval
include_descendantsNoGroup selector only: include subgroups, default true

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed10 schema fields changedv0.1.6
    • addedInput schema / additionalProperties
      Added value: +false
    • changedInput schema / properties / confirm / description
      Previous value: -"Set true only after a human approves the resolved preview"New value: +"Legacy flag: true without a server confirmation_token is rejected"
    • addedInput schema / properties / confirmation_token
      Added value: +{
+  "description": "Server token: commit uses only policy_id and this token after approval",
+  "pattern": "^msac_[A-Za-z0-9_-]{43}$",
+  "type": "string"
+}
    • changedInput schema / properties / endpoint_ids / description
      Previous value: -"Explicit list of endpoint UUIDs. Mutually exclusive with hostname_pattern."New value: +"One or more endpoint IDs; exclusive with hostname_pattern/group_ids"
    • addedInput schema / properties / group_ids
      Added value: +{
+  "description": "Existing group IDs; exclusive with endpoint_ids/hostname_pattern",
+  "items": {
+    "format": "uuid",
+    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+    "type": "string"
+  },
+  "maxItems": 50,
+  "minItems": 1,
+  "type": "array"
+}
    • changedInput schema / properties / hostname_pattern / description
      Previous value: -"Glob pattern (case-insensitive) matched against computer_name. Mutually exclusive with endpoint_ids."New value: +"Case-insensitive hostname glob; exclusive with endpoint_ids/group_ids"
    • addedInput schema / properties / hostname_pattern / pattern
      Added value: +"^[^\\u0000-\\u001f\\u007f-\\u009f]*$"
    • addedInput schema / properties / include_descendants
      Added value: +{
+  "description": "Group selector only: include subgroups, default true",
+  "type": "boolean"
+}
    • changedInput schema / properties / platform / description
      Previous value: -"Optional platform filter, applied when resolving hostname_pattern"New value: +"Hostname selector only: optional platform filter"
    • changedInput schema / properties / policy_id / description
      Previous value: -"The policy UUID to assign"New value: +"Policy ID to assign"
  2. First observedv0.1.1

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already declare destructive=true, idempotent=false and closed-world, but the description adds substantially: required scopes (policies:write, endpoints:read), the 500-computer cap and no future-member binding for groups, the one-time token freezing target IDs, whole-operation rejection on stale data or ineligible computers, and the fact that existing protections or an enforcing schedule may be destroyed. It also correctly distinguishes saved desired state from actual installation on the host.

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?

Front-loads the prerequisites, then the preview contract, then the commit contract, then the risk and success definition. Sentences are dense but every one carries an operational constraint; no filler or restatement of the title.

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 an 8-parameter destructive mutation with no output schema, the description covers auth, selector rules, staging and commit mechanics, token lifecycle, rejection conditions, and what the preview should surface to the human. Nothing needed to invoke it safely 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 coverage is 100%, so the baseline is 3; the description earns above that by clarifying selector exclusivity semantics, the group expansion/default-descendants behavior and its 500 cap, and the commit contract that only policy_id plus the server token matter on the second call. It doesn't spell out platform filter or include_descendants semantics, which remain schema-only.

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?

Names a specific verb and resource (apply a policy to endpoints) and immediately frames the two-phase preview/confirm shape, which is what differentiates it from show_policy, flip_to_enforcing, and list_endpoints in the sibling list. An agent can identify what this does and what it is not 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 states the workflow: preview with exactly one selector (endpoint_ids / hostname_pattern / group_ids), get human approval, then call again with ONLY policy_id and confirmation_token. It also names a failure path to avoid (confirm=true alone cannot commit) and a prohibition (never automatically retry writes), leaving nothing 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