Tools

Every tool returns JSON. Prose fields — description, acceptance criteria, repro steps, comment bodies — come back as plain text, not HTML.

Reads

| Tool | Returns | |---|---| | get_work_item(id) | One work item in full — fields, parent id, and every relation | | list_comments(id, limit?) | Discussion oldest-first. limit returns the most recent N of the thread; 200 is both the default and the cap | | list_updates(id, limit?) | Revision history — field diffs plus parent/child link events. Default 50 revisions | | list_children(id) | Child items in full. Hierarchy-Forward relations only | | query_work_items(wiql, limit?) | Compact row per match, in the query’s ORDER BY. Capped at 200 | | get_work_item_context(id, comments_limit?, updates_limit?) | The first four above in one call, fetched concurrently. Bounded: 30 most recent comments, and children as compact rows | | list_boards(team?) | Boards with their columns and state mappings | | list_iterations(team?, timeframe?) | Sprints with dates. timeframe is past, current, or future |

Writes

| Tool | Does | |---|---| | create_work_item(type, title, description?, parent_id?, fields?) | Creates an item, optionally under a parent | | update_work_item(id, fields) | Sets fields by Azure DevOps reference name | | transition_state(id, state, reason?) | Moves state, optionally with a reason | | add_comment(id, text) | Adds a comment to the discussion |

Field names

fields keys are full reference names — System.Title, System.AssignedTo, Microsoft.VSTS.Common.Priority, Custom.FunctionsRequired. A short name like Title is rejected. Board fields such as WEF_<guid>_Kanban.Column are accepted.

Prose is plain text everywhere

create_work_item’s description, add_comment’s text, and the HTML-typed fields in either tool’s fields — description, acceptance criteria, repro steps, system info, discussion. Blank-line paragraphs, - and 1. lists, **bold**, *italic*, and [text](url) links are converted; anything else is escaped, so raw HTML shows literally.

The conversion consumes the markers, so text you read back and re-send loses its *. Every other field — a custom HTML-typed one included — is sent verbatim, so supply HTML for those.

Orienting on a ticket

get_work_item_context is the one to reach for — it issues the four read calls concurrently and returns them merged, so the agent has the whole ticket in one round-trip:

Pull the context for DevOps 115551 and tell me what's left to do.

Each section carries its own error field, so a failure in one still returns the other three.

Querying the board

WIQL queries need scoping or they scan the whole organisation. The @project macro resolves to the project in your config:

Query DevOps for my open items:
SELECT [System.Id] FROM WorkItems
WHERE [System.TeamProject] = @project
  AND [System.State] <> 'Closed'
  AND [System.AssignedTo] = @Me
ORDER BY [System.ChangedDate] DESC

Always include the [System.TeamProject] clause, and exclude Closed items unless you want them.

States are per type, not universal

Don’t guess state names. Call list_boards and read the column state_mappings — they’re keyed by work item type, so the same column resolves to a different state depending on what you’re moving. A Requirements board may resolve “Ready for QA” to Ready For Testing for a Requirement but QA for a Bug, while “Done” resolves to Done for a Requirement and Ready For Production for a Bug.

transition_state passes your value straight through to Azure DevOps, so a wrong state produces a rejection rather than a silent no-op.