Azure DevOps Boards Tools - Genesis Computing

Overview

Before using this tool group, save an Azure DevOps connection as described in Azure DevOps. If connection_id is omitted, the tools use the effective default azure_devops connection for the current user (My default, then Role default). Actions that need a project use the explicit project parameter first and otherwise fall back to the connection’s saved default project. When multiple role defaults conflict, pass connection_id explicitly or set a user default. See Default connection layers.

Tool Name

azure_devops_boards_tools

Purpose

The azure_devops_boards_tools group integrates Genesis with Azure DevOps Boards. Create and update work items (including sprint moves), link work items to each other or to pull requests, read single or batched work item details, search with structured filters or WIQL, list sprints and boards, read comments and revision history, inspect links and text attachments, and retrieve sprint capacity for a specific team iteration. Successful agent writes also record best-effort observations on the Requests page when that feature is enabled.

Key Features

Create and update work items

Open new Azure DevOps work items, patch standard fields (including sprint moves via iteration_path), add comments, and link items to parents, children, related work, or pull requests.

Read issue context

Fetch one work item or up to 100 ids per batch; read comments, revision history, grouped links, and text attachments.

Query Boards data

Find work items with structured filters (ado_find_work_items) or hand-written WIQL (ado_search_work_items).

Explore team structure

List iterations (sprints), Kanban boards, and backlog levels for a team.

Inspect sprint capacity

Retrieve team capacity for a specific iteration to support planning.

Track managed work on Requests

When Requests is enabled, agent creates, updates, comments, and links through the write tools appear on the Activity tab with deep links back to Azure DevOps. Assignment automation can also poll for work items assigned to the connection identity and open orchestrator threads without an explicit agent tool call.

Requests page tracking

When Requests is enabled (GENESIS_SHOW_WORK), successful agent writes through ado_create_work_item, ado_update_work_item, and ado_link_work_items record observations in the Genesis ticket ledger. Each tracked row shows the Azure DevOps state, a normalized Genesis lifecycle state, the agent executor, the Genesis thread when one exists, and a deep link to the work item in Azure DevOps. Azure DevOps remains the system of record — ledger emission is observability only and never affects tool success.

Work items appear when an agent manages them through these write tools, or when Azure DevOps assignment automation picks up a work item assigned to the connection identity. Genesis does not bulk-import a backlog.
ado_get_work_item refreshes provider state for items Genesis already tracks; read-only lookups never import untracked backlog items.
Failed writes against an already-tracked item record an error on its timeline; failed writes against untracked ids are not imported.
State changes applied through state or fields={"System.State": ...} emit status-change events; comment-only updates keep the item in a working state so later observations can close the loop.

See Requests for the Activity and Health tabs and Ticket automation endpoints for the read API.

Input Parameters for Each Function

`ado_create_work_item`

Name	Type	Default	Definition
`work_item_type`	String	none	Required. Azure DevOps work item type such as `Task`, `Issue`, `Bug`, `Epic`, or a project-specific type.
`title`	String	none	Required. Work item title.
`description`	String	`None`	Optional work item description.
`project`	String	connection default project when available	Optional Azure DevOps project.
`assigned_to`	String	`None`	Optional assignee display name or email.
`tags`	String	`None`	Optional semicolon-separated Azure DevOps tags.
`area_path`	String	`None`	Optional Azure DevOps area path.
`iteration_path`	String	`None`	Optional Azure DevOps iteration path.
`priority`	Integer	`None`	Optional priority value written to `Microsoft.VSTS.Common.Priority`.
`parent_id`	Integer	`None`	Optional parent work item id. In v1, Genesis returns this as a `next_steps` hint instead of creating the relation automatically.
`fields`	Object	`None`	Optional map of additional Azure DevOps field reference-name/value pairs.
`connection_id`	String	default `azure_devops` connection	Optional saved Azure DevOps connection name.

`ado_update_work_item`

Name	Type	Default	Definition
`work_item_id`	Integer	none	Required. Azure DevOps work item id.
`project`	String	connection default project when available	Optional Azure DevOps project. Required when `comment` is set unless the connection has a default project (the comments API is project-scoped). Field updates resolve the work item by `work_item_id` without this parameter.
`state`	String	`None`	Optional new state.
`assigned_to`	String	`None`	Optional new assignee display name or email.
`iteration_path`	String	`None`	Optional new iteration path to move the item to a sprint.
`comment`	String	`None`	Optional comment to add after field updates.
`fields`	Object	`None`	Optional map of additional Azure DevOps field reference-name/value pairs to update.
`connection_id`	String	default `azure_devops` connection	Optional saved Azure DevOps connection name.

ado_update_work_item requires at least one field update or a comment. When comment is set, Genesis posts through the project-scoped comments API — pass project or save a default project on the connection. Write operations require a PAT with Work Items (Read & Write); a read-only PAT returns error_type: permission.

`ado_link_work_items`

Name	Type	Default	Definition
`work_item_id`	Integer	none	Required. ADO work item id the link is added to.
`link_type`	String	none	Required. Link kind: `parent` (target becomes this item’s parent), `child`, `related`, or `pull_request`.
`target_work_item_id`	Integer	`None`	Other work item id. Required for `parent`, `child`, and `related` links.
`repo`	String	`None`	Repository name or id. Required for `pull_request` links.
`pull_request_id`	Integer	`None`	Pull request id. Required for `pull_request` links.
`comment`	String	`None`	Optional note stored on the link.
`project`	String	`None`	Optional ADO project for `pull_request` repo lookup.
`connection_id`	String	default `azure_devops` connection	Optional saved Azure DevOps connection name.

link_type semantics: parent makes target_work_item_id the parent of work_item_id; child makes it a child; related adds a plain relation; pull_request attaches the PR named by repo and pull_request_id as an artifact link. A work item cannot be linked to itself. Requires a PAT with Work Items (Read & Write).

`ado_get_work_item`

Name	Type	Default	Definition
`work_item_id`	Integer	none	Required. Azure DevOps work item id.
`project`	String	`None`	Optional project parameter kept for signature consistency.
`include_relations`	Boolean	`false`	Include work item relations in the response.
`include_comments`	Boolean	`false`	If `true`, expand all work item data (fields, relations, links). Comment text still requires `ado_get_work_item_comments`.
`connection_id`	String	default `azure_devops` connection	Optional saved Azure DevOps connection name.

`ado_get_work_items_batch`

Name	Type	Default	Definition
`work_item_ids`	Array of integers	none	Required. Work item ids to fetch (1–100 per call).
`fields`	Array of strings	`None`	Optional Azure DevOps field reference names to return (for example `System.Title`). Omit for all fields.
`include_relations`	Boolean	`false`	Include each item’s relations. Ignored when `fields` is set.
`connection_id`	String	default `azure_devops` connection	Optional saved Azure DevOps connection name.

`ado_search_work_items`

Name	Type	Default	Definition
`wiql`	String	none	Required. WIQL query string.
`project`	String	connection default project when available	Optional Azure DevOps project. Required for WIQL using the `@Project` macro.
`team`	String	`None`	Optional Azure DevOps team. Required for WIQL using the `@CurrentIteration` macro.
`top`	Integer	`50`	Maximum number of work items to return. Genesis clamps the value between `1` and `200`.
`connection_id`	String	default `azure_devops` connection	Optional saved Azure DevOps connection name.

ado_search_work_items returns id/url references in query_result.workItems only. Fetch full fields with ado_get_work_items_batch. Invalid WIQL returns error_type: invalid_wiql with the parser message. For common searches (for example “bugs assigned to me”), prefer ado_find_work_items.

`ado_find_work_items`

Name	Type	Default	Definition
`work_item_types`	Array of strings	`None`	Work item types to match, for example `['Bug']` or `['User Story', 'Task']`.
`states`	Array of strings	`None`	States to match, for example `['Active', 'New']`.
`assigned_to`	String	`None`	Assignee filter: `'@me'` for the connection’s authenticated identity, or a display name/email.
`created_by`	String	`None`	Creator filter: `'@me'` or a display name/email.
`priority_at_most`	Integer	`None`	Inclusive priority ceiling, `1` (highest) to `4`; use `2` for high-priority items.
`iteration`	String	`None`	Iteration path, or `'current'` for the active sprint (requires `team`).
`area_path`	String	`None`	Area path subtree to search under.
`tags`	Array of strings	`None`	Match work items carrying any of these tags.
`text_contains`	String	`None`	Substring matched against title or description.
`created_after`	String	`None`	Only items created on or after this ISO date (`YYYY-MM-DD`).
`changed_after`	String	`None`	Only items changed on or after this ISO date (`YYYY-MM-DD`).
`order_by`	String	`'changed'`	Sort order: `'changed'`, `'created'`, `'priority'`, or `'id'`.
`top`	Integer	`50`	Maximum number of work items to return. Genesis clamps the value between `1` and `200`.
`include_details`	Boolean	`true`	When `true`, fetch full fields for matches; when `false`, return id/url references only.
`project`	String	connection default project when available	Optional Azure DevOps project.
`team`	String	`None`	Optional Azure DevOps team. Required when `iteration` is `'current'`.
`connection_id`	String	default `azure_devops` connection	Optional saved Azure DevOps connection name.

`ado_list_iterations`

Name	Type	Default	Definition
`team`	String	project’s default team	Optional Azure DevOps team.
`timeframe`	String	`None`	Set to `'current'` to return only the active sprint.
`project`	String	connection default project when available	Optional Azure DevOps project.
`connection_id`	String	default `azure_devops` connection	Optional saved Azure DevOps connection name.

`ado_list_boards`

Name	Type	Default	Definition
`team`	String	project’s default team	Optional Azure DevOps team.
`project`	String	connection default project when available	Optional Azure DevOps project.
`connection_id`	String	default `azure_devops` connection	Optional saved Azure DevOps connection name.

`ado_list_backlogs`

Name	Type	Default	Definition
`team`	String	project’s default team	Optional Azure DevOps team.
`project`	String	connection default project when available	Optional Azure DevOps project.
`connection_id`	String	default `azure_devops` connection	Optional saved Azure DevOps connection name.

`ado_get_work_item_comments`

Name	Type	Default	Definition
`work_item_id`	Integer	none	Required. Azure DevOps work item id.
`top`	Integer	`None`	Maximum comments per page. Genesis clamps the value between `1` and `200` when set.
`continuation_token`	String	`None`	Continuation token from a previous page to fetch the next one.
`project`	String	connection default project when available	Optional Azure DevOps project.
`connection_id`	String	default `azure_devops` connection	Optional saved Azure DevOps connection name.

`ado_get_work_item_history`

Name	Type	Default	Definition
`work_item_id`	Integer	none	Required. Azure DevOps work item id.
`top`	Integer	`None`	Maximum revisions to return. Genesis clamps the value between `1` and `200` when set.
`skip`	Integer	`None`	Number of revisions to skip (for paging).
`connection_id`	String	default `azure_devops` connection	Optional saved Azure DevOps connection name.

`ado_get_work_item_links`

Name	Type	Default	Definition
`work_item_id`	Integer	none	Required. Azure DevOps work item id.
`connection_id`	String	default `azure_devops` connection	Optional saved Azure DevOps connection name.

`ado_download_attachment`

Name	Type	Default	Definition
`attachment_id`	String	none	Required. Attachment id (GUID) from `ado_get_work_item_links`.
`file_name`	String	`None`	Optional attachment file name hint.
`connection_id`	String	default `azure_devops` connection	Optional saved Azure DevOps connection name.

`ado_get_sprint_capacity`

Name	Type	Default	Definition
`team`	String	none	Required. Azure DevOps team name.
`iteration`	String	none	Required. Azure DevOps iteration id.
`project`	String	connection default project when available	Optional Azure DevOps project.
`connection_id`	String	default `azure_devops` connection	Optional saved Azure DevOps connection name.

Workflow/How It Works

Configure your effective default azure_devops connection in Azure DevOps, or pass connection_id.
Use ado_create_work_item to open new tasks, bugs, or other work items.
Use ado_get_work_item, ado_get_work_items_batch, and ado_update_work_item to inspect and modify existing work (including sprint moves with iteration_path).
Use ado_link_work_items to relate work items or attach a pull request; use ado_get_work_item_links to inspect existing relationships.
Use ado_find_work_items for structured searches (for example bugs assigned to you in the current sprint) or ado_search_work_items for hand-written WIQL.
Use ado_list_iterations, ado_list_boards, and ado_list_backlogs to discover team structure; use ado_get_sprint_capacity for planning data.
Use ado_get_work_item_comments, ado_get_work_item_history, and ado_download_attachment for discussion, audit, and attachment context.

Examples

# Create a bug in Azure DevOps Boards
ado_create_work_item(
    work_item_type="Bug",
    title="Retry pipeline logs on transient 429 responses",
    project="Platform",
    assigned_to="[email protected]",
    tags="incident;platform",
    priority=1,
)

# Move a work item to a sprint and mark it done
ado_update_work_item(
    work_item_id=42,
    project="Platform",
    iteration_path="Platform\\Sprint 25",
    state="Done",
    comment="Shipped in Sprint 25.",
)

# Make work item 12 a child of epic 10
ado_link_work_items(
    work_item_id=12,
    link_type="child",
    target_work_item_id=10,
)

# Attach a pull request to a work item
ado_link_work_items(
    work_item_id=55,
    link_type="pull_request",
    repo="platform-api",
    pull_request_id=123,
    project="Platform",
)

# Find high-priority bugs assigned to the connection identity
ado_find_work_items(
    work_item_types=["Bug"],
    assigned_to="@me",
    priority_at_most=2,
    project="Platform",
    team="Platform Team",
    top=25,
)

# Search recent active bugs with WIQL
ado_search_work_items(
    wiql=(
        "SELECT [System.Id], [System.Title], [System.State] "
        "FROM WorkItems "
        "WHERE [System.TeamProject] = @project "
        "AND [System.WorkItemType] = 'Bug' "
        "AND [System.State] <> 'Closed' "
        "ORDER BY [System.ChangedDate] DESC"
    ),
    project="Platform",
    top=25,
)

# Inspect sprint capacity for one team iteration
ado_get_sprint_capacity(
    team="Platform Team",
    iteration="Platform\\Sprint 24",
    project="Platform",
)

Output

ado_create_work_item returns the created work_item. When parent_id is supplied and creation succeeds, the response can also include next_steps that remind the caller to link the parent work item in Azure DevOps.
ado_update_work_item returns success: true plus the updated work_item when fields were patched, and comment when a comment was added.
ado_link_work_items returns success: true, the updated work_item, and the link relation that was added.
ado_get_work_item returns work_item with every system and custom field. include_relations adds the raw relations array.
ado_get_work_items_batch returns work_items, count, and missing_ids for ids Azure DevOps did not return (deleted or not visible to the PAT).
ado_search_work_items returns the raw Azure DevOps query_result whose workItems are id/url references only. When you pass project, Genesis also echoes project in the response.
ado_find_work_items returns wiql, count, work_items (full details by default, or id/url references when include_details is false), and optionally missing_ids or detail_fetch_error.
ado_list_iterations returns iterations with id, name, path, and start/finish dates.
ado_list_boards returns boards with id, name, and url.
ado_list_backlogs returns backlogs with id, name, rank, and accepted work item types.
ado_get_work_item_comments returns comments, count, total_count, and continuation_token for paging.
ado_get_work_item_history returns revisions (field snapshots, oldest first) and count.
ado_get_work_item_links returns links grouped as parent, children, related, pull_requests, commits, attachments, hyperlinks, and other, plus per-group counts.
ado_download_attachment returns text (UTF-8, truncated past 100,000 characters), size_bytes, and truncated.
ado_get_sprint_capacity returns capacity.

Configuration Details

fields uses Azure DevOps field reference names such as System.Title, System.State, or Microsoft.VSTS.Common.Priority.
Calls that resolve a project require either an explicit project parameter or a default project on the saved connection.

Limitations or Notes

ado_get_work_item accepts project for signature consistency; the work item is resolved by work_item_id. On ado_update_work_item, project (or a connection default) is required when comment is set because Azure DevOps serves the comments API only under a project URL.
Comment text is never inlined by ado_get_work_item — use ado_get_work_item_comments for discussion content.
ado_search_work_items and ado_find_work_items (with include_details=false) return id/url references; fetch full records with ado_get_work_items_batch (up to 100 ids per call).
ado_find_work_items with iteration='current' requires team because Azure DevOps resolves the active sprint per team.
ado_download_attachment reads text attachments only. Binary attachments (images, archives, office documents) return an error — open the attachment URL in Azure DevOps instead.
parent_id on ado_create_work_item adds a follow-up hint only. Use ado_link_work_items with link_type='parent' or link_type='child' to create the hierarchy after creation.
ado_update_work_item and ado_link_work_items are write operations. A PAT with Work Items read-only access returns error_type: permission (Azure DevOps may answer with HTTP 401 for insufficient scope).
Requests-page tracking is best-effort. Ledger emission is guarded so malformed Azure DevOps payloads or ledger unavailability never change tool success responses.

​Overview

​Tool Name

​Purpose

​Key Features

​Requests page tracking

​Input Parameters for Each Function

​ado_create_work_item

​ado_update_work_item

​ado_link_work_items

​ado_get_work_item

​ado_get_work_items_batch

​ado_search_work_items

​ado_find_work_items

​ado_list_iterations

​ado_list_boards

​ado_list_backlogs

​ado_get_work_item_comments

​ado_get_work_item_history

​ado_get_work_item_links

​ado_download_attachment

​ado_get_sprint_capacity

​Workflow/How It Works

​Examples

​Output

​Configuration Details

​Limitations or Notes

​Related Pages

Overview

Tool Name

Purpose

Key Features

Requests page tracking

Input Parameters for Each Function

`ado_create_work_item`

`ado_update_work_item`

`ado_link_work_items`

`ado_get_work_item`

`ado_get_work_items_batch`

`ado_search_work_items`

`ado_find_work_items`

`ado_list_iterations`

`ado_list_boards`

`ado_list_backlogs`

`ado_get_work_item_comments`

`ado_get_work_item_history`

`ado_get_work_item_links`

`ado_download_attachment`

`ado_get_sprint_capacity`

Workflow/How It Works

Examples

Output

Configuration Details

Limitations or Notes

Related Pages