---
title: "corestack_team_role_delete"
url: https://docs.corefinity.com/mcp/tools/corestack_team_role_delete
type: tool
last_updated: 2026-11-13
feature: team
related:
  - https://docs.corefinity.com/api/reference/organisation/delete-custom-role.md
  - https://docs.corefinity.com/guides/organisation/people/users-and-invitations.md
---
# corestack_team_role_delete

**Delete a custom role.** Delete one of your company's custom roles that nobody holds. Send confirm_name set to the role's name, exactly. Scope: write.

- Scope: `write`
- Confirmation: `confirm_name`
- Runs as a task: no

## When to use it

Delete one of your company's custom roles that nobody holds. Ask the person you act for first, then send
`confirm_name` set to the role's name, exactly. This is `DELETE /api/roles/{id}/delete`.

## Inputs

- `role_id` (integer, ≥ 1, required): the custom role's id from corestack_team_roles_list.
- `confirm_name` (string, up to 255 characters, required): the role's name, exactly.

### Input schema

```json
{
  "additionalProperties": false,
  "properties": {
    "confirm_name": {
      "description": "The role's name, exactly.",
      "maxLength": 255,
      "type": "string"
    },
    "role_id": {
      "description": "The custom role's id (corestack_team_roles_list).",
      "minimum": 1,
      "type": "integer"
    }
  },
  "required": [
    "role_id",
    "confirm_name"
  ],
  "type": "object"
}
```

## Refusals

- `confirm_mismatch`: `confirm_name` is not the role's name; nothing was deleted.
- `in_use`: somebody still holds the role; take it from them first.
- `forbidden`: you may not delete roles (an owner, or the Delete Roles permission, may).
- The refusals every tool can answer: `invalid_arguments`, `tenant_mismatch`, `scope_required`, `pin_refused`, `rate_limited`, `temporarily_unavailable`, `internal_error` (corestack://guides/how-this-server-works).

## Example

```json
{
  "name": "corestack_team_role_delete",
  "arguments": {
    "role_id": 77,
    "confirm_name": "Release managers"
  }
}
```

## Prompt

```text
Using the Corefinity MCP server, call corestack_team_role_delete with role_id 77. (Delete a custom role.) Tell me what it returned.
```

## The same task elsewhere

- Endpoint: [DELETE /api/roles/{id}/delete](https://docs.corefinity.com/api/reference/organisation/delete-custom-role.md)
- Guide: [Users and invitations](https://docs.corefinity.com/guides/organisation/people/users-and-invitations.md)
