action1-mcp-server

Create a role

action1_create_role

Destructive

Create new Action1 roles with a name, description, and scoped permissions for granular access control. Use it to define custom roles and restrict permission scopes safely.

Instructions

Create a role. Creates a new role. Perm: manage_roles.

Input Schema

Name	Required	Description
`body`	Yes	Request body
`confirm`	No	Required to execute. Exact string "YES".
`dry_run`	No	Default true (preview). Set false to execute.

Output Schema

Name	Required	Description	Default
`id`	No
`name`	No
`self`	No
`tool`	No
`type`	No
`users`	No
`dry_run`	No
`would_send`	No
`description`	No
`scoped_permissions`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed16 schema fields changedv0.6.0Oct 26, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

changedInput schema / properties / body / description

Previous value: -"Request body (schema: object)"New value: +"Request body"

addedInput schema / properties / body / properties

Added value: +{
+  "description": {
+    "description": "The role description.",
+    "type": "string"
+  },
+  "name": {
+    "description": "The role name.",
+    "type": "string"
+  },
+  "scoped_permissions": {
+    "items": {
+      "additionalProperties": {},
+      "properties": {
+        "exclude_scope": {
+          "items": {
+            "additionalProperties": {},
+            "propertyNames": {
+              "type": "string"
+            },
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "include_scope": {
+          "items": {
+            "additionalProperties": {},
+            "propertyNames": {
+              "type": "string"
+            },
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "permission": {
+          "description": "The permission ID. List of available permissions can be found by calling /API/permissions.",
+          "type": "string"
+        },
+        "restrictions": {
+          "additionalProperties": {},
+          "description": "Optional restrictions for `include_scope` only (not for `exclude_scope`).",
+          "propertyNames": {
+            "type": "string"
+          },
+          "type": "object"
+        }
+      },
+      "required": [
+        "permission",
+        "include_scope",
+        "exclude_scope"
+      ],
+      "type": "object"
+    },
+    "type": "array"
+  }
+}

addedInput schema / properties / body / required

Added value: +[
+  "name",
+  "description"
+]

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

changedOutput schema / additionalProperties
```
Previous value: -trueNew value: +{}
```
addedOutput schema / properties / description
```
Added value: +{}
```
addedOutput schema / properties / dry_run
```
Added value: +{}
```
addedOutput schema / properties / id
```
Added value: +{}
```
addedOutput schema / properties / name
```
Added value: +{}
```
addedOutput schema / properties / scoped_permissions
```
Added value: +{}
```
addedOutput schema / properties / self
```
Added value: +{}
```
addedOutput schema / properties / tool
```
Added value: +{}
```
addedOutput schema / properties / type
```
Added value: +{}
```
addedOutput schema / properties / users
```
Added value: +{}
```
addedOutput schema / properties / would_send
```
Added value: +{}
```

First observedv0.5.0Jun 27, 2026

TDQS

C2.7/5.0

Behavior3/5

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is covered. The description adds one genuine piece of extra context, the required `manage_roles` permission, but stays silent on the confirmation/dry-run execution gate that matters most for a destructive non-idempotent write.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

"Create a role. Creates a new role." is a duplicated statement; the second sentence earns no place. What remains is front-loaded but wasteful, and the space freed by removing the repetition could have carried the missing usage or safety context.

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

Completeness3/5

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

An output schema exists and the input schema is fully documented, so return values and parameters need not be explained. Still, for a destructive write tool with role-related siblings, the description never states when to create versus clone or update, leaving a real gap.

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 `body`, `name`, `description`, `scoped_permissions` and the `confirm`/`dry_run` flags are all self-documenting. The description adds nothing about the nested permission/scope structure, which is fine at this coverage level — baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The verb+resource ("Create a role") is unambiguous, but the description offers no differentiation from nearby siblings such as action1_clone_role, action1_update_role, or action1_create_role_user. An agent knows what it does but not how it differs from those alternatives.

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

Usage Guidelines2/5

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

There is no when-to-use guidance and no exclusions — nothing tells the agent to prefer clone_role when copying an existing role or update_role when modifying one. Only the permission prerequisite ("Perm: manage_roles") is stated, which is context but not usage routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server