Add WIQL query tool and update documentation for work items (#1118)

This pull request introduces a new tool for executing WIQL (Work Item
Query Language) queries against Azure DevOps work items, along with
comprehensive documentation and test coverage. The main changes are the
addition of the `wit_query_by_wiql` tool, updates to documentation, and
new tests to ensure correct behavior and error handling.

## GitHub issue number
N/A

## **Associated Risks**

Poorly created WIQL could have an effect on rate limits

## ✅ **PR Checklist**

- [x] **I have read the [contribution
guidelines](https://github.com/microsoft/azure-devops-mcp/blob/main/CONTRIBUTING.md)**
- [x] **I have read the [code of conduct
guidelines](https://github.com/microsoft/azure-devops-mcp/blob/main/CODE_OF_CONDUCT.md)**
- [x] Title of the pull request is clear and informative.
- [x] 👌 Code hygiene
- [x] 🔭 Telemetry added, updated, or N/A
- [x] 📄 Documentation added, updated, or N/A
- [x] 🛡️ Automated tests added, or N/A

## 🧪 **How did you test it?**

ran several manual tests and generated auto tests

Author: danhellem

docs/TOOLSET.md

@@ -81,6 +81,7 @@
 | Work Items        | [mcp_ado_wit_list_backlog_work_items](#mcp_ado_wit_list_backlog_work_items)                               | Get work items in a backlog                              |
 | Work Items        | [mcp_ado_wit_get_query](#mcp_ado_wit_get_query)                                                           | Get a work item query by ID or path                      |
 | Work Items        | [mcp_ado_wit_get_query_results_by_id](#mcp_ado_wit_get_query_results_by_id)                               | Execute a query and get results                          |
+| Work Items        | [mcp_ado_wit_query_by_wiql](#mcp_ado_wit_query_by_wiql)                                                   | Execute a WIQL query and return matching work items      |
 | Work Items        | [mcp_ado_wit_get_work_item_attachment](#mcp_ado_wit_get_work_item_attachment)                             | Download a work item attachment as base64                |
 | Work              | [mcp_ado_work_list_iterations](#mcp_ado_work_list_iterations)                                             | List all iterations in a project                         |
 | Work              | [mcp_ado_work_create_iterations](#mcp_ado_work_create_iterations)                                         | Create new iterations in a project                       |
@@ -670,6 +671,13 @@ Retrieve the results of a work item query given the query ID.
 - **Required**: `id`
 - **Optional**: `project`, `responseType`, `team`, `timePrecision`, `top`
 
+### mcp_ado_wit_query_by_wiql
+
+Execute a WIQL (Work Item Query Language) query and return the matching work items. If a project is not specified, you will be prompted to select one.
+
+- **Required**: `wiql`
+- **Optional**: `project`, `team`, `timePrecision`, `top`
+
 ### mcp_ado_wit_get_work_item_attachment
 
 Download a work item attachment by its ID and return the content as a base64-encoded resource. Useful for viewing images (e.g. screenshots) attached to work items such as bugs.

src/tools/work-items.ts

@@ -7,6 +7,8 @@ import { WorkItemExpand, WorkItemRelation } from "azure-devops-node-api/interfac
 import { QueryExpand } from "azure-devops-node-api/interfaces/WorkItemTrackingInterfaces.js";
 import { z } from "zod";
 import { batchApiVersion, markdownCommentsApiVersion, getEnumKeys, safeEnumConvert, encodeFormattedValue } from "../utils.js";
+import { elicitProject } from "../shared/elicitations.js";
+import { createExternalContentResponse } from "../shared/content-safety.js";
 
 const WORKITEM_TOOLS = {
   my_work_items: "wit_my_work_items",
@@ -31,6 +33,7 @@ const WORKITEM_TOOLS = {
   work_item_unlink: "wit_work_item_unlink",
   add_artifact_link: "wit_add_artifact_link",
   get_work_item_attachment: "wit_get_work_item_attachment",
+  query_by_wiql: "wit_query_by_wiql",
 };
 
 function getLinkTypeFromName(name: string) {
@@ -1267,6 +1270,43 @@ function configureWorkItemTools(server: McpServer, tokenProvider: () => Promise<
     }
   );
 
+  server.tool(
+    WORKITEM_TOOLS.query_by_wiql,
+    "Execute a WIQL (Work Item Query Language) query and return the matching work items. If a project is not specified, you will be prompted to select one.",
+    {
+      wiql: z.string().max(32768).describe('The WIQL query string to execute, e.g., "SELECT [System.Id], [System.Title] FROM WorkItems WHERE [System.TeamProject] = @project"'),
+      project: z.string().optional().describe("The name or ID of the Azure DevOps project. Reuse from prior context if already known. If not provided, a project selection prompt will be shown."),
+      team: z.string().optional().describe("The name or ID of the Azure DevOps team. If not provided, the default team context will be used."),
+      timePrecision: z.boolean().optional().describe("Whether to include time precision in date fields. Defaults to false."),
+      top: z.coerce.number().default(50).describe("The maximum number of results to return. Defaults to 50."),
+    },
+    async ({ wiql, project, team, timePrecision, top }) => {
+      try {
+        const connection = await connectionProvider();
+        let resolvedProject = project;
+
+        if (!resolvedProject) {
+          const result = await elicitProject(server, connection, "Select the Azure DevOps project to run the WIQL query against.");
+          if ("response" in result) return result.response;
+          resolvedProject = result.resolved;
+        }
+
+        const workItemApi = await connection.getWorkItemTrackingApi();
+        const teamContext = { project: resolvedProject, team };
+        const queryResult = await workItemApi.queryByWiql({ query: wiql }, teamContext, timePrecision, top);
+
+        return createExternalContentResponse(queryResult, "wiql query results");
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : "Unknown error occurred";
+
+        return {
+          content: [{ type: "text", text: `Error executing WIQL query: ${errorMessage}` }],
+          isError: true,
+        };
+      }
+    }
+  );
+
   server.tool(
     WORKITEM_TOOLS.get_work_item_attachment,
     "Download a work item attachment by its ID and return the content as a base64-encoded resource. Useful for viewing images (e.g. screenshots) attached to work items such as bugs.",

test/mocks/work-items.ts

@@ -663,3 +663,37 @@ export const _mockWorkItemRevisions = [
     url: "https://dev.azure.com/fabrikam/_apis/wit/workItems/299/revisions/2",
   },
 ];
+
+export const _mockWiqlQueryResults = {
+  queryType: 1,
+  queryResultType: 1,
+  asOf: "2026-04-07T00:00:00.000Z",
+  columns: [
+    {
+      referenceName: "System.Id",
+      name: "ID",
+      url: "https://dev.azure.com/fabrikam/_apis/wit/fields/System.Id",
+    },
+    {
+      referenceName: "System.Title",
+      name: "Title",
+      url: "https://dev.azure.com/fabrikam/_apis/wit/fields/System.Title",
+    },
+    {
+      referenceName: "System.State",
+      name: "State",
+      url: "https://dev.azure.com/fabrikam/_apis/wit/fields/System.State",
+    },
+  ],
+  sortColumns: [],
+  workItems: [
+    {
+      id: 297,
+      url: "https://dev.azure.com/fabrikam/_apis/wit/workItems/297",
+    },
+    {
+      id: 299,
+      url: "https://dev.azure.com/fabrikam/_apis/wit/workItems/299",
+    },
+  ],
+};

test/src/tools/work-items.test.ts

@@ -11,6 +11,7 @@ import {
   _mockBacklogs,
   _mockQuery,
   _mockQueryResults,
+  _mockWiqlQueryResults,
   _mockWorkItem,
   _mockWorkItemComment,
   _mockWorkItemComments,
@@ -42,12 +43,14 @@ interface WorkItemTrackingApiMock {
   getWorkItemType: jest.Mock;
   getQuery: jest.Mock;
   queryById: jest.Mock;
+  queryByWiql: jest.Mock;
   getAttachmentContent: jest.Mock;
 }
 
 interface MockConnection {
   getWorkApi: jest.Mock;
   getWorkItemTrackingApi: jest.Mock;
+  getCoreApi: jest.Mock;
   serverUrl?: string;
 }
 
@@ -61,7 +64,7 @@ describe("configureWorkItemTools", () => {
   let mockWorkItemTrackingApi: WorkItemTrackingApiMock;
 
   beforeEach(() => {
-    server = { tool: jest.fn() } as unknown as McpServer;
+    server = { tool: jest.fn(), server: { elicitInput: jest.fn() } } as unknown as McpServer;
     tokenProvider = jest.fn();
 
     mockWorkApi = {
@@ -83,12 +86,14 @@ describe("configureWorkItemTools", () => {
       getWorkItemType: jest.fn(),
       getQuery: jest.fn(),
       queryById: jest.fn(),
+      queryByWiql: jest.fn(),
       getAttachmentContent: jest.fn(),
     };
 
     mockConnection = {
       getWorkApi: jest.fn().mockResolvedValue(mockWorkApi),
       getWorkItemTrackingApi: jest.fn().mockResolvedValue(mockWorkItemTrackingApi),
+      getCoreApi: jest.fn().mockResolvedValue({ getProjects: jest.fn() }),
     };
 
     connectionProvider = jest.fn().mockResolvedValue(mockConnection);
@@ -3749,4 +3754,138 @@ describe("configureWorkItemTools", () => {
       expect(result.content[0].text).toBe("Error retrieving work item attachment: Not found");
     });
   });
+
+  describe("query_by_wiql tool", () => {
+    it("should call queryByWiql with correct params when project is provided", async () => {
+      configureWorkItemTools(server, tokenProvider, connectionProvider, userAgentProvider);
+
+      const call = (server.tool as jest.Mock).mock.calls.find(([toolName]) => toolName === "wit_query_by_wiql");
+      if (!call) throw new Error("wit_query_by_wiql tool not registered");
+      const [, , , handler] = call;
+
+      (mockWorkItemTrackingApi.queryByWiql as jest.Mock).mockResolvedValue(_mockWiqlQueryResults);
+
+      const params = {
+        wiql: "SELECT [System.Id], [System.Title] FROM WorkItems WHERE [System.TeamProject] = @project",
+        project: "Contoso",
+        team: undefined,
+        timePrecision: undefined,
+        top: 50,
+      };
+
+      const result = await handler(params);
+
+      expect(mockWorkItemTrackingApi.queryByWiql).toHaveBeenCalledWith({ query: params.wiql }, { project: params.project, team: undefined }, undefined, 50);
+      expect(result.content[0].text).toContain("UNTRUSTED");
+      expect(result.content[0].text).toContain(JSON.stringify(_mockWiqlQueryResults, null, 2));
+    });
+
+    it("should call queryByWiql with all optional params when provided", async () => {
+      configureWorkItemTools(server, tokenProvider, connectionProvider, userAgentProvider);
+
+      const call = (server.tool as jest.Mock).mock.calls.find(([toolName]) => toolName === "wit_query_by_wiql");
+      if (!call) throw new Error("wit_query_by_wiql tool not registered");
+      const [, , , handler] = call;
+
+      (mockWorkItemTrackingApi.queryByWiql as jest.Mock).mockResolvedValue(_mockWiqlQueryResults);
+
+      const params = {
+        wiql: "SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = @project AND [System.State] = 'Active'",
+        project: "Contoso",
+        team: "Fabrikam",
+        timePrecision: true,
+        top: 100,
+      };
+
+      const result = await handler(params);
+
+      expect(mockWorkItemTrackingApi.queryByWiql).toHaveBeenCalledWith({ query: params.wiql }, { project: "Contoso", team: "Fabrikam" }, true, 100);
+      expect(result.content[0].text).toContain("UNTRUSTED");
+      expect(result.content[0].text).toContain(JSON.stringify(_mockWiqlQueryResults, null, 2));
+    });
+
+    it("should elicit project when project is not provided and user accepts", async () => {
+      configureWorkItemTools(server, tokenProvider, connectionProvider, userAgentProvider);
+
+      const call = (server.tool as jest.Mock).mock.calls.find(([toolName]) => toolName === "wit_query_by_wiql");
+      if (!call) throw new Error("wit_query_by_wiql tool not registered");
+      const [, , , handler] = call;
+
+      const mockCoreApi = { getProjects: jest.fn().mockResolvedValue([{ id: "proj-1", name: "Contoso" }]) };
+      (mockConnection.getCoreApi as jest.Mock).mockResolvedValue(mockCoreApi);
+
+      ((server as unknown as { server: { elicitInput: jest.Mock } }).server.elicitInput as jest.Mock).mockResolvedValue({
+        action: "accept",
+        content: { project: "Contoso" },
+      });
+
+      (mockWorkItemTrackingApi.queryByWiql as jest.Mock).mockResolvedValue(_mockWiqlQueryResults);
+
+      const params = {
+        wiql: "SELECT [System.Id] FROM WorkItems",
+        project: undefined,
+        team: undefined,
+        timePrecision: undefined,
+        top: 50,
+      };
+
+      const result = await handler(params);
+
+      expect((server as unknown as { server: { elicitInput: jest.Mock } }).server.elicitInput).toHaveBeenCalled();
+      expect(mockWorkItemTrackingApi.queryByWiql).toHaveBeenCalledWith({ query: params.wiql }, { project: "Contoso", team: undefined }, undefined, 50);
+      expect(result.content[0].text).toContain("UNTRUSTED");
+      expect(result.content[0].text).toContain(JSON.stringify(_mockWiqlQueryResults, null, 2));
+    });
+
+    it("should return cancellation message when user declines project elicitation", async () => {
+      configureWorkItemTools(server, tokenProvider, connectionProvider, userAgentProvider);
+
+      const call = (server.tool as jest.Mock).mock.calls.find(([toolName]) => toolName === "wit_query_by_wiql");
+      if (!call) throw new Error("wit_query_by_wiql tool not registered");
+      const [, , , handler] = call;
+
+      const mockCoreApi = { getProjects: jest.fn().mockResolvedValue([{ id: "proj-1", name: "Contoso" }]) };
+      (mockConnection.getCoreApi as jest.Mock).mockResolvedValue(mockCoreApi);
+
+      ((server as unknown as { server: { elicitInput: jest.Mock } }).server.elicitInput as jest.Mock).mockResolvedValue({
+        action: "decline",
+      });
+
+      const params = {
+        wiql: "SELECT [System.Id] FROM WorkItems",
+        project: undefined,
+        team: undefined,
+        timePrecision: undefined,
+        top: 50,
+      };
+
+      const result = await handler(params);
+
+      expect(mockWorkItemTrackingApi.queryByWiql).not.toHaveBeenCalled();
+      expect(result.content[0].text).toBe("Project selection cancelled.");
+    });
+
+    it("should return an error when queryByWiql throws", async () => {
+      configureWorkItemTools(server, tokenProvider, connectionProvider, userAgentProvider);
+
+      const call = (server.tool as jest.Mock).mock.calls.find(([toolName]) => toolName === "wit_query_by_wiql");
+      if (!call) throw new Error("wit_query_by_wiql tool not registered");
+      const [, , , handler] = call;
+
+      (mockWorkItemTrackingApi.queryByWiql as jest.Mock).mockRejectedValue(new Error("WIQL syntax error"));
+
+      const params = {
+        wiql: "INVALID WIQL",
+        project: "Contoso",
+        team: undefined,
+        timePrecision: undefined,
+        top: 50,
+      };
+
+      const result = await handler(params);
+
+      expect(result.isError).toBe(true);
+      expect(result.content[0].text).toBe("Error executing WIQL query: WIQL syntax error");
+    });
+  });
 });