update_work_item
Modify existing Azure DevOps work items to change status, assign tasks, update details, or adjust priorities directly in the system.
Instructions
Modifies an existing work item's fields and properties.
Use this tool when you need to:
- Change the status or state of a work item
- Reassign work to a different team member
- Update the description or details of a requirement
- Modify effort estimates or priority levels
- Add or change classification (area/iteration)
- Update any field supported by the work item type
IMPORTANT: This tool updates the work item directly in Azure DevOps.
Changes will be immediately visible to all users with access to the
work item and will trigger any configured notifications or workflows.
You must specify at least one field to update.
Args:
id: The ID of the work item to update
fields: Optional dictionary of field name/value pairs to update
project: Optional project name or ID
title: Optional new title for the work item
description: Optional new description
state: Optional new state
assigned_to: Optional user email to assign to
iteration_path: Optional new iteration path
area_path: Optional new area path
story_points: Optional new story points value
priority: Optional new priority value
tags: Optional new tags as comma-separated string
Returns:
Formatted string containing the updated work item details with
all current field values, formatted as markdown
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| fields | No | ||
| project | No | ||
| title | No | ||
| description | No | ||
| state | No | ||
| assigned_to | No | ||
| iteration_path | No | ||
| area_path | No | ||
| story_points | No | ||
| priority | No | ||
| tags | No |
Implementation Reference
- The main @mcp.tool()-decorated 'update_work_item' function serving as the MCP tool handler. Processes parameters into standard Azure DevOps field names, handles custom fields, validates inputs, and invokes the core update implementation.
@mcp.tool() def update_work_item( id: int, fields: Optional[Dict[str, Any]] = None, project: Optional[str] = None, title: Optional[str] = None, description: Optional[str] = None, state: Optional[str] = None, assigned_to: Optional[str] = None, iteration_path: Optional[str] = None, area_path: Optional[str] = None, story_points: Optional[float] = None, priority: Optional[int] = None, tags: Optional[str] = None, ) -> str: """ Modifies an existing work item's fields and properties. Use this tool when you need to: - Change the status or state of a work item - Reassign work to a different team member - Update the description or details of a requirement - Modify effort estimates or priority levels - Add or change classification (area/iteration) - Update any field supported by the work item type IMPORTANT: This tool updates the work item directly in Azure DevOps. Changes will be immediately visible to all users with access to the work item and will trigger any configured notifications or workflows. You must specify at least one field to update. Args: id: The ID of the work item to update fields: Optional dictionary of field name/value pairs to update project: Optional project name or ID title: Optional new title for the work item description: Optional new description state: Optional new state assigned_to: Optional user email to assign to iteration_path: Optional new iteration path area_path: Optional new area path story_points: Optional new story points value priority: Optional new priority value tags: Optional new tags as comma-separated string Returns: Formatted string containing the updated work item details with all current field values, formatted as markdown """ try: wit_client = get_work_item_client() # Start with standard fields all_fields = _prepare_standard_fields( title, description, state, assigned_to, iteration_path, area_path, story_points, priority, tags ) # Add custom fields if provided if fields: for field_name, field_value in fields.items(): field_name = _ensure_system_prefix(field_name) all_fields[field_name] = field_value if not all_fields: return "Error: At least one field must be specified for update" return _update_work_item_impl( id=id, fields=all_fields, wit_client=wit_client, project=project ) except AzureDevOpsClientError as e: return f"Error: {str(e)}" except Exception as e: return f"Error updating work item: {str(e)}" - Core helper function '_update_work_item_impl' that constructs the JSON patch document using 'replace' operations for updated fields and executes the Azure DevOps 'update_work_item' API call, then formats the result.
def _update_work_item_impl( id: int, fields: Dict[str, Any], wit_client: WorkItemTrackingClient, project: Optional[str] = None, ) -> str: """ Implementation of updating a work item. Args: id: The ID of the work item to update fields: Dictionary of field name/value pairs to update wit_client: Work item tracking client project: Optional project name or ID Returns: Formatted string containing the updated work item details """ document = _build_field_document(fields, "replace") # Update the work item updated_work_item = wit_client.update_work_item( document=document, id=id, project=project ) return format_work_item(updated_work_item) - Helper '_prepare_standard_fields' that converts tool parameters to proper Azure DevOps field reference names and handles type conversions for common work item fields.
def _prepare_standard_fields( title: Optional[str] = None, description: Optional[str] = None, state: Optional[str] = None, assigned_to: Optional[str] = None, iteration_path: Optional[str] = None, area_path: Optional[str] = None, story_points: Optional[float] = None, priority: Optional[int] = None, tags: Optional[str] = None, ) -> Dict[str, Any]: """ Prepare fields dictionary with standard fields for work item creation/update. Args: title: The title of the work item description: Optional description of the work item state: Optional initial state for the work item assigned_to: Optional user email to assign the work item to iteration_path: Optional iteration path for the work item area_path: Optional area path for the work item story_points: Optional story points value priority: Optional priority value tags: Optional tags as comma-separated string Returns: Dictionary of field name/value pairs """ fields = {} if title: fields["System.Title"] = title if description: fields["System.Description"] = description if state: fields["System.State"] = state if assigned_to: fields["System.AssignedTo"] = assigned_to if iteration_path: fields["System.IterationPath"] = iteration_path if area_path: fields["System.AreaPath"] = area_path if story_points is not None: # Convert float to string to avoid type errors fields["Microsoft.VSTS.Scheduling.StoryPoints"] = str(story_points) if priority is not None: fields["Microsoft.VSTS.Common.Priority"] = str(priority) if tags: fields["System.Tags"] = tags return fields - Utility '_build_field_document' that converts field dictionaries into Azure DevOps JsonPatchOperation lists, ensuring proper '/fields/' paths and operation types.
def _build_field_document(fields: Dict[str, Any], operation: str = "add") -> list: """ Build a document of JsonPatchOperations from a dictionary of fields. Args: fields: Dictionary of field name/value pairs operation: The operation to perform (add or replace) Returns: List of JsonPatchOperation objects """ document = [] for field_name, field_value in fields.items(): # Ensure field names are prefixed with /fields/ path = (field_name if field_name.startswith("/fields/") else f"/fields/{field_name}") document.append( JsonPatchOperation( op=operation, path=path, value=field_value ) ) return document - Registration invocation 'create.register_tools(mcp)' which triggers the definition and registration of the 'update_work_item' tool via its @mcp.tool() decorator.
create.register_tools(mcp)