Delete Tag

Tool Name: airdroid_business_tag_delete

Risk Level: 🔴 High-Risk

Execution Mode: ⚡ Synchronous (with optional confirmation gate)

Category: Device Management (Tags)

Quick Start (Copy & Use)

Summary: Permanently delete one organization tag; it is removed from all devices and workflows that use it.

Prerequisites: TagId (positive integer). Default RequireConfirmation=true pauses the workflow until a human completes the confirmation form (including Reason) or until the wait expires (up to 24 hours). Deletion does not run until confirmation succeeds.

Success Criteria: StatusCode == 200 and ErrorMessage is empty. Do not treat -2 / -3 or non-empty ErrorMessage as success.

Agent note: With default confirmation, one tool invocation cannot finish the delete by itself—the run waits for human approval. Use RequireConfirmation=false only when explicit approval was already recorded outside this tool (writes a fixed audit reason; see §2.4).

What to Do Next: Verify tags on devices via List Devices if needed; do not reuse the deleted TagId.

Minimal Request Example:

{
  "TagId": 4103,
  "RequireConfirmation": true
}

Minimal Response Example:

{
  "Hint": "",
  "Retryable": false,
  "OriginalStatusCode": 200,
  "StatusCode": 200,
  "ErrorMessage": ""
}

Recipes (Common Recipes)

Recipe 1: Standard Delete (With Confirmation)

When to use: Production workflows; operator must approve in the confirmation step.

{
  "TagId": 4103,
  "RequireConfirmation": true
}

When the confirmation task opens, the operator must enter Reason in the form (not in the Start node JSON). The workflow waits up to 24 hours for approval.

Recipe 2: Pre-Approved Delete (Skip Confirmation)

When to use: Explicit user approval was already collected outside the tool.

{
  "TagId": 4103,
  "RequireConfirmation": false
}

The delete runs without pausing. The audit reason recorded upstream is the fixed string: Confirmation skipped by RequireConfirmation=false.

Recipe 3: Resolve ID Then Delete

When to use: You know the tag name, not the ID.

1. Batch Resolve Tag IDs by Name with the tag name.
2. Delete Tag with the resolved TagId.

1. Overview

1.1 Description

Deletes a single device tag from the organization. Side effect: the tag is stripped from every device and workflow that referenced it.

1.2 When to Use

• Retire obsolete classification tags
• Clean up mistakenly created tags (after removing assignments if needed)

1.3 When Not to Use

• You only need to add, replace, or clear tags on devices without deleting the tag definition — use Batch Set Device Tags (or Set Tags) instead.

1.4 Execution Mode and Response

Synchronous after confirmation (when enabled). No tag payload is returned on success—only status fields.

1.5 Prerequisites

1.6 Prerequisite Tools

1.7 Similar Tools

2. Inputs

2.1 Parameter List

2.2 Parameter Details

`TagId`

• Type: number (positive integer, not boolean)
• Obtain via: Batch Resolve Tag IDs by Name — use the tag unique identifier returned for an existing name.
• Example: 4103
• Fill in a GI workflow node:
  • Constants: Enter a numeric literal, for example 4103.
  • Reference upstream output: Map the resolved ID from Batch Resolve Tag IDs by Name (for example {{upstream.tag_id}} depending on your node output shape).

`RequireConfirmation`

• true (default): Human-in-the-loop — workflow creates a confirmation task, collects Reason in the form, and waits up to 24 hours before delete runs or times out.
• false: Skips the confirmation UI; delete proceeds when the code node runs. Use only when approval was already obtained elsewhere. Audit reason: Confirmation skipped by RequireConfirmation=false.
• Fill in a GI workflow node:
  • Constants: true (recommended for production) or false (pre-approved flows only).
  • Reference upstream: Rare; use a boolean from a prior approval step only if your process defines one.

2.3 Parameter Combination Logic

• TagId is always required.
• When confirmation is enabled, deletion does not run until confirmation succeeds; rejection or timeout yields StatusCode -2 or -3 with no upstream delete call.

2.4 Confirmation Gate (Not Standard `Confirm` / `Reason` Start Inputs)

This high-risk action uses RequireConfirmation on the Start node plus a Reason field on the confirmation form (create-task / wait-task), not Confirm and Reason as Start parameters.

Pre-delete checklist (recommended)

1. Confirm TagId resolves to the intended tag name (Batch Resolve Tag IDs by Name).
2. Confirm org impact: tag removed from all devices and workflows that use it.
3. Keep default confirmation in automated flows unless policy documents out-of-band approval for RequireConfirmation=false.

3. Outputs

3.1 Response Examples

Success:

{
  "Hint": "",
  "Retryable": false,
  "OriginalStatusCode": 200,
  "StatusCode": 200,
  "ErrorMessage": ""
}

Tag not found (business failure):

StatusCode stays 200, but ErrorMessage is copied from the upstream msg field (wording not fixed). Use Hint and non-empty ErrorMessage to detect failure—do not match ErrorMessage text literally.

{
  "Hint": "Tag was not found; obtain a valid TagId via 'Batch Resolve Tag IDs by Name', then retry.",
  "Retryable": false,
  "OriginalStatusCode": 200,
  "StatusCode": 200,
  "ErrorMessage": "<upstream message; not a fixed tool string>"
}

Validation failure (invalid TagId):

{
  "Hint": "Provide an existing Tag ID, then retry.",
  "Retryable": false,
  "OriginalStatusCode": 0,
  "StatusCode": -1,
  "ErrorMessage": "TagId must be a positive integer."
}

Confirmation canceled by user (StatusCode -2):

{
  "Hint": "Do not retry automatically; the user canceled this action.",
  "Retryable": false,
  "OriginalStatusCode": -2,
  "StatusCode": -2,
  "ErrorMessage": "The user canceled execution before the tool ran."
}

Confirmation timed out (StatusCode -3):

{
  "Hint": "Ask for confirmation again only if the user still wants this action.",
  "Retryable": false,
  "OriginalStatusCode": -3,
  "StatusCode": -3,
  "ErrorMessage": "Confirmation timed out before execution."
}

3.2 Field Descriptions

3.3 Status Values in Payload

Not applicable—successful delete returns no tag object, only status fields.

4. Examples

4.1 Delete After Resolving Name

Step 1 – resolve: Batch Resolve Tag IDs by Name → TagId = 4103

Step 2 – delete:

{ "TagId": 4103, "RequireConfirmation": true }

4.2 Invalid TagId

Request: { "TagId": 0 }

Response: See validation example in §3.1 (TagId must be a positive integer.).

4.3 Confirmation Canceled or Timed Out

Request: { "TagId": 4103, "RequireConfirmation": true } with user cancel or 24h timeout

Response: See §3.1 -2 / -3 examples. Do not assume the tag was deleted.

5. Error Handling

5.1 StatusCode Semantics (This Action)

HTTP mapping (tool layer uses StatusCode 500, not 403/401):

5.2 Common Errors

5.3 Agent Self-Healing

6. Best Practices

6.1 Security

• 🔴 Irreversible org-wide impact—confirm TagId and use default confirmation in automated flows unless policy allows bypass.

6.2 Idempotency

• Not idempotent: second delete of the same ID fails after the tag is gone (often not-found in ErrorMessage).

7. Related Tools

8. Tool Chains

8.1 Safe Delete by Name

Batch Resolve Tag IDs by Name → Delete Tag (RequireConfirmation true)

Appendix Reference:

• Field Reference
• Error Codes