Update a device remark

Tool Name: airdroid_business_update_device_remark

Risk Level: 🟠 Medium Risk

Execution Mode: ⚡ Synchronous

Category: Device Management

Quick Start (Copy & Use)

Summary: Update a device's note/remarks information.

Prerequisites: DeviceId (device ID) + Note (note content, can be empty to clear notes).

Success Criteria: StatusCode == 200 and ErrorMessage is empty string.

What to Do Next: Use Get All Devices to verify the note has been updated.

Minimal Request Example:

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "Note": "This is a sales department device"
}

Minimal Response Example:

{
  "StatusCode": 200,
  "ErrorMessage": ""
}

Recipes (Common Recipes)

Recipe 1: Add Device Usage Description

When to use: Record the device's usage scenario and responsible person.

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "Note": "Sales demo device. Contact: John (ext. 1234)"
}

Recipe 2: Add Maintenance Record

When to use: Record the device's maintenance history.

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "Note": "Last maintenance: 2024-01-15. Battery replaced."
}

Recipe 3: Clear Device Note

When to use: Remove the device's note information.

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "Note": ""
}

Note: Passing an empty string clears the device note.

1. Overview

1.1 Description

Update the note/remarks information of a specified device. Notes are used to store additional descriptions, usage records, or other custom information about the device.

1.2 When to Use

• Record the device's purpose, responsible person, or location information
• Add maintenance records or issue descriptions
• Store any custom notes related to the device

1.3 Execution Mode and Response

This operation is synchronous and returns results immediately.

1.4 Prerequisites

1.5 Prerequisite Tools

2. Inputs

2.1 Parameter List

2.2 Parameter Details

`DeviceId`

Device unique identifier.

• Type: string
• Format: Non-empty string
• Source:

How to obtain:

1. Via Get All Devices tool - use the device_id field from the response
2. Via Get a Device by Name tool - exact name query

The device_id field from the output can be used directly as this parameter.

• Example:

  "fa6edcff65ab444e8b5e0eb08df4175d"

`Note`

Device note content.

• Type: string
• Format:
  • Can be an empty string (to clear the note)
  • Recommended length: within 500 characters
  • Maximum length: 1024 characters
  • Special characters not allowed: / \ < > &
• Notes:
  • Passing an empty string "" clears the device note
  • The new note completely replaces the original note (full overwrite)
• Example:

  "This is a sales department device. Contact: John (ext. 1234)"

  "Last maintenance: 2024-01-15. Issues: Battery drains fast."

  ""

2.3 Parameter Combination Logic

• DeviceId is required
• Note is optional; omitting it or passing an empty string both clear the note

3. Outputs

3.1 Response Example

Success response:

{
  "StatusCode": 200,
  "ErrorMessage": ""
}

Error response:

{
  "StatusCode": -1,
  "ErrorMessage": "Invalid device_id."
}

3.2 Field Descriptions

4. Examples

4.1 Basic Example: Add Device Note

Request Parameters:

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "Note": "Sales demo device. Contact: John (ext. 1234)"
}

Response:

{
  "StatusCode": 200,
  "ErrorMessage": ""
}

4.2 Advanced Example: Add Detailed Maintenance Record

Request Parameters:

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "Note": "Assigned to: Marketing Team\nLocation: Building A, Floor 3\nPurchase Date: 2023-06-15\nLast Maintenance: 2024-01-10\nNotes: Screen protector replaced"
}

Response:

{
  "StatusCode": 200,
  "ErrorMessage": ""
}

4.3 Clear Note Example

Request Parameters:

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "Note": ""
}

Response:

{
  "StatusCode": 200,
  "ErrorMessage": ""
}

5. Error Handling

5.1 AB Three-Layer Error Codes

5.2 Common Errors

5.3 Agent Self-Healing Decision Table

6. Best Practices

6.1 Performance Optimization

• Single device operation: This tool can only update one device at a time; batch updates require loop calls
• Control length: Recommended to keep notes within 500 characters; maximum is 1024 characters

6.2 Security Considerations

🟡 Write operation:

• Full overwrite: The new note completely replaces the original note
• Sensitive information: Avoid storing passwords or other sensitive information in notes
• Confirm target: Verify DeviceId is correct before updating

6.3 Idempotency

This operation is naturally idempotent. Multiple calls with the same Note have no side effects; the device note remains unchanged.

7. Related Tools

7.1 Prerequisite Tools

7.2 Follow-up Tools

7.3 Similar Tool Comparison

8. Tool Chains

8.1 Find Device by Name and Add Note

Scenario: You know the device name and need to add a note.

Tool Chain:

Get a Device by Name → Update a Device Note

Steps:

1. Call Get a Device by Name to get the device's DeviceId
2. Use the returned DeviceId to call Update a Device Note

8.2 Batch Add Notes to Devices

Scenario: Add notes to multiple devices in batch.

Tool Chain:

Get All Devices → [Loop] Update a Device Note

Steps:

1. Call Get All Devices to get the device list
2. Iterate through the device list
3. Call Update a Device Note for each device

8.3 Update and Verify

Scenario: Update the note and confirm the operation succeeded.

Tool Chain:

Update a Device Note → Get All Devices (verify)

Steps:

1. Call Update a Device Note to update the note
2. Confirm ErrorMessage is empty
3. Call Get All Devices to query the device and confirm the note field has been updated

Appendix Reference:

• Field Reference: https://www.goinsight.ai/tools/field-reference/
• Error Code Quick Reference: https://www.goinsight.ai/tools/error-codes/