add_parent_child_link
Establish parent-child relationships between work items in Azure DevOps to organize hierarchies, create structured breakdowns, and enable progress tracking. Ensures child items appear under parents in backlogs and boards.
Instructions
Adds a parent-child relationship between two work items.
Use this tool when you need to:
- Establish hierarchy between work items
- Organize epics, features, user stories, and tasks
- Create a structured breakdown of work
- Enable rollup of effort and progress tracking
IMPORTANT: The child work item will immediately appear under the parent
in hierarchical views. This relationship affects how the items are
displayed in backlogs and boards. In Azure DevOps, a work item can have
only one parent but multiple children.
Args:
parent_id: ID of the parent work item
child_id: ID of the child work item
project: Optional project name or ID
Returns:
Formatted string containing the updated child work item details
showing the new parent relationship, formatted as markdown
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| child_id | Yes | ||
| parent_id | Yes | ||
| project | No |
Implementation Reference
- Main handler function for the 'add_parent_child_link' tool, registered via @mcp.tool() decorator. Handles input validation via type hints and orchestrates the link creation by calling the helper implementation.@mcp.tool() def add_parent_child_link( parent_id: int, child_id: int, project: Optional[str] = None, ) -> str: """ Adds a parent-child relationship between two work items. Use this tool when you need to: - Establish hierarchy between work items - Organize epics, features, user stories, and tasks - Create a structured breakdown of work - Enable rollup of effort and progress tracking IMPORTANT: The child work item will immediately appear under the parent in hierarchical views. This relationship affects how the items are displayed in backlogs and boards. In Azure DevOps, a work item can have only one parent but multiple children. Args: parent_id: ID of the parent work item child_id: ID of the child work item project: Optional project name or ID Returns: Formatted string containing the updated child work item details showing the new parent relationship, formatted as markdown """ try: wit_client = get_work_item_client() return _add_link_to_work_item_impl( source_id=child_id, target_id=parent_id, link_type="System.LinkTypes.Hierarchy-Reverse", wit_client=wit_client, project=project ) except AzureDevOpsClientError as e: return f"Error: {str(e)}" except Exception as e: return f"Error creating parent-child link: {str(e)}"
- Core helper function that executes the Azure DevOps API call to add the parent-child link to the child work item using the Hierarchy-Reverse link type.def _add_link_to_work_item_impl( source_id: int, target_id: int, link_type: str, wit_client: WorkItemTrackingClient, project: Optional[str] = None, ) -> str: """ Implementation of adding a link between work items. Args: source_id: ID of the source work item target_id: ID of the target work item link_type: Type of link to create wit_client: Work item tracking client project: Optional project name or ID Returns: Formatted string containing the updated work item details """ # Get organization URL from environment org_url = _get_organization_url() # Build link document with the full URL link_document = _build_link_document(target_id, link_type, org_url) # Update the work item to add the link updated_work_item = wit_client.update_work_item( document=link_document, id=source_id, project=project ) return format_work_item(updated_work_item)