update_work_item
Modify work item fields and properties directly in Azure DevOps, including status, assignment, description, priority, and more. Ensures immediate updates and triggers notifications or workflows. Specify at least one field to update.
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 |
|---|---|---|---|
| area_path | No | ||
| assigned_to | No | ||
| description | No | ||
| fields | No | ||
| id | Yes | ||
| iteration_path | No | ||
| priority | No | ||
| project | No | ||
| state | No | ||
| story_points | No | ||
| tags | No | ||
| title | No |
Implementation Reference
- Primary MCP tool handler for 'update_work_item'. Decorated with @mcp.tool(), processes parameters into fields dict, handles errors, and delegates to _update_work_item_impl.@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 implementing the work item update logic: builds 'replace' JsonPatch document from fields and executes wit_client.update_work_item Azure DevOps API call.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 utility to construct JsonPatchOperation list from field dictionary, prefixing paths with /fields/.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
- Module-level registration aggregator that calls register_tools on all sub-modules, including create.register_tools(mcp) which registers 'update_work_item'.def register_tools(mcp) -> None: """ Register all work item tools with the MCP server. Args: mcp: The FastMCP server instance """ query.register_tools(mcp) read.register_tools(mcp) comments.register_tools(mcp) create.register_tools(mcp) types.register_tools(mcp) templates.register_tools(mcp) process.register_tools(mcp)
- src/mcp_azure_devops/features/work_items/__init__.py:5-12 (registration)Feature-level registration entrypoint that invokes tools.register_tools(mcp) to register all work items tools including 'update_work_item'.def register(mcp): """ Register all work items components with the MCP server. Args: mcp: The FastMCP server instance """ tools.register_tools(mcp)