Agent-Oriented Task Update

Operational guidance for AI systems that need to understand when and how to update a TaskSocial task.

Agent-Oriented Task Update

This guide provides operational instructions for an AI system or agent that needs to understand how to update a TaskSocial task.

The API reference describes the technical contract of an operation, including the endpoint, HTTP method, parameters, request body, and response codes.

This guide adds another layer of context. It explains:

• When the operation should be used
• When it should not be used
• What conditions should be checked first
• What information is required
• What side effects the operation has
• How an AI system should handle ambiguity
• How an AI system should respond to common errors

Operation

Tool concept: update_task

Underlying API endpoint:

PUT /api/v1/tasks/{id}

Purpose

Use this operation to update an existing TaskSocial task.

A task may have its:

• Title updated
• Description updated
• Status changed

The technical API allows an authenticated task owner to modify their existing task.

When to use this operation

Use the update operation when all of the following conditions are true:

• The authenticated user explicitly wants to modify an existing task.
• The target task can be identified.
• The task ID is available.
• The authenticated user owns the task.
• At least one valid field needs to be updated.

For example:

Change my task title to “Finish the TaskSocial documentation.”

Or:

Mark my documentation task as completed.

In these cases, the user’s intention is to modify an existing task.

When not to use this operation

Do not use the update operation when:

• The user is only asking for information about a task.
• The user wants to create a new task.
• The user wants to delete a task.
• The target task is unclear.
• Multiple tasks could match the user’s request.
• The requested change is unclear or ambiguous.
• The authenticated user does not own the task.

For example:

Update my task.

This request does not clearly identify the task or explain what should be changed.

The agent should ask for clarification instead of making an arbitrary update.

Preconditions

Before updating a task, the following conditions should be checked:

1. The user is authenticated.
2. The target task can be identified.
3. The task ID is available.
4. The authenticated user owns the task.
5. At least one valid field is provided for the update.

If these conditions are not satisfied, the agent should not blindly perform the operation.

Required input

The operation requires the following path parameter:

Input	Type	Required	Description
id	string	Yes	MongoDB ObjectId of the task to update

Optional input

The request body may contain one or more of the following fields:

Field	Type	Description
title	string	New title for the task
description	string	New description for the task
status	string	Task status: pending or completed

At least one valid field should be provided when performing an update.

Example request

{
  "title": "Finish TaskSocial documentation",
  "status": "completed"
}

Expected result

If the update is successful, the API returns a 200 OK response.

The response contains the updated task.

Possible errors

Status	Meaning	Recommended agent behavior
403	The authenticated user does not own the task	Do not retry the same update. Inform the user that they cannot update a task they do not own.
404	The task does not exist	Do not retry with the same task ID. Inform the user that the task could not be found.
Authentication error	The user is not authenticated	Ask the user to authenticate before attempting an authenticated operation again.

Side effects

This operation modifies existing data.

Depending on the request, it can change:

• The task title
• The task description
• The task status

Because the operation changes stored data, the intended task and requested changes should be clear before calling the API.

Handling ambiguity

Explicit confirmation is not necessarily required for every update, but the requested action should be clear.

For example:

Mark task 123 as completed.

The target task and requested change are clear.

However, consider this request:

Update my documentation task.

The agent may not know:

• Which documentation task the user means
• What field should be changed
• What the new value should be

If multiple tasks could match the request, the agent should ask the user for clarification.

The agent should not choose a task arbitrarily.

For example:

Which task would you like to update, and what would you like to change?

Recommended decision process

Before calling the update operation, an AI system can follow this process:

User requests a task update
        ↓
Is the user authenticated?
        ↓
Can the target task be identified?
        ↓
Does the user own the task?
        ↓
Are the requested changes clear?
        ↓
Are the update fields valid?
        ↓
Call PUT /api/v1/tasks/{id}
        ↓
Return the result to the user

Example scenarios

Scenario 1: Clear request

User:

Mark my task with ID 123 as completed.

The agent can:

1. Verify that the user is authenticated.
2. Identify task ID 123.
3. Attempt to update the status field to completed.
4. Return the result of the operation.

Scenario 2: Ambiguous request

User:

Update my task.

The agent should not immediately call the update operation.

Instead, it should ask:

Which task would you like to update, and what would you like to change?

The operation should only be performed after the intended task and requested changes are clear.

Scenario 3: User does not own the task

If the API returns:

403 Forbidden

The agent should explain that the authenticated user does not have permission to update that task.

It should not repeatedly retry the same operation.

Scenario 4: Task does not exist

If the API returns:

404 Not Found

The agent should inform the user that the task could not be found.

The agent can then ask the user to provide or identify the correct task.

Traditional API documentation

A traditional API reference focuses on the technical contract.

For this operation, it answers questions such as:

• Which endpoint should be called?
• Which HTTP method is used?
• What path parameter is required?
• What request body fields are accepted?
• What responses can be returned?

For example:

PUT /api/v1/tasks/{id}

This information is essential for a developer or system that needs to technically call the API.

Agent-oriented documentation

Agent-oriented documentation adds operational context.

It answers additional questions such as:

• When should this operation be used?
• When should it not be used?
• What conditions should be checked first?
• What should happen when the user’s request is ambiguous?
• What should the agent do after receiving an error?
• What data does the operation modify?

This additional context helps describe not only how to call an API, but also how an AI system should reason about whether it should call the API.

The relationship between the two

OpenAPI describes the technical contract.

The API reference presents that contract in a format developers can read and interact with.

Agent-oriented documentation adds operational instructions, business context, preconditions, and guidance about how an AI system should behave.

Together, the documentation can be viewed as:

OpenAPI
    +
API reference
    +
Human-readable guides
    +
Business rules
    +
Preconditions
    +
Error-handling guidance
    +
Operational instructions
        ↓
More complete documentation
for humans and AI systems

Key idea

OpenAPI tells a system what an API technically accepts.

Agent-oriented documentation adds context about when the operation should be used, when it should not be used, and what should happen before and after the operation.

This does not turn TaskSocial into an autonomous AI agent.

Instead, it is an experiment showing how documentation can move beyond endpoint descriptions and include the operational context that an AI system may need before taking an action.

View the Update Task API Reference

View the technical API contract, request parameters, request body, and response codes for updating a TaskSocial task.