{"id":26252,"date":"2026-10-20T00:00:57","date_gmt":"2026-10-20T07:00:57","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/?p=26252"},"modified":"2026-10-20T08:49:55","modified_gmt":"2026-10-20T15:49:55","slug":"work-iq-retrieve-october-2026","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/work-iq-retrieve-october-2026\/","title":{"rendered":"Work IQ: the new retrieve tool"},"content":{"rendered":"<p>The new Work IQ Retrieve tool grounds agents in the context of work, helping them reason over the right information and deliver more relevant, trustworthy responses. With one retrieval layer across work sources, developers can give agents richer organizational context without building separate search systems.<\/p>\n<article>\n<section aria-labelledby=\"retrieve\">\n<h2 id=\"retrieve\">Retrieve: grounded answers across work sources<\/h2>\n<p>The new MCP tool named <code>retrieve<\/code> searches a user&#8217;s workplace data\u2014including email, files, meetings, Teams messages and people, as well as connected enterprise sources. As with any other tool offered by Work IQ, each user will be able to retrieve information only from work sources they are authorized to access. Security and access control always come first when consuming organizational intelligence with Work IQ.<\/p>\n<aside class=\"video-hook\" aria-label=\"YouTube live demo\"><strong>Watch the live demo: &#8220;Work IQ: MCP Retrieve Tool&#8221;<\/strong><\/aside>\n<aside class=\"video-hook\" aria-label=\"YouTube live demo\">See a short video with an interactive demonstration of the Work IQ Retrieve Tool in action.<\/p>\n<p class=\"small\"><iframe loading=\"lazy\" title=\"YouTube video player\" src=\"https:\/\/www.youtube.com\/embed\/mwl4fev1hDI?si=G6xtLFIWMNQh3PI2\" width=\"560\" height=\"315\" frameborder=\"0\" allowfullscreen=\"allowfullscreen\" data-mce-fragment=\"1\"><\/iframe><\/p>\n<\/aside>\n<p>This new MCP tool <a href=\"https:\/\/learn.microsoft.com\/en-us\/microsoft-365\/copilot\/extensibility\/work-iq\/mcp\/migrate-retrieval-api\">evolves the Copilot Retrieval API<\/a> to reshape retrieval for agentic consumption: optimized for agents and designed to scale as they ground decisions in work context.<\/p>\n<p>The tool returns two main components: raw per-source retrieval hits and a model-friendly grounding markdown with inline citations. Each hit carries structured metadata (URL, sensitivity label). Ground your answer on the <code>markdown<\/code> field.<\/p>\n<p>This is more than a ranked list of documents. The response contains both a readable grounding representation and structured hit records. The <code>markdown<\/code> is the model-facing context to use when composing an answer; its inline citation IDs correspond to the individual hits, whose fields can include <code>id<\/code>, <code>resourceId<\/code>, <code>webUrl<\/code>, <code>entityUrl<\/code>, <code>entityType<\/code>, <code>contentProtection<\/code>, <code>resourceMetadata<\/code> and <code>sensitivityLabel<\/code>. Preserve citations when summarizing, and use hit metadata when the application needs to link back to a source or apply source-aware handling.<\/p>\n<p>Retrieval and delegation are separate operations. Use <code>retrieve<\/code> to collect relevant context for the current agent; use <code>ask<\/code> or <code>do_action<\/code> when the task should be delegated to another agent, optionally selecting a target agent ID. This keeps the retrieval query focused on finding evidence rather than implicitly routing work.<\/p>\n<h3>More about the tool parameters<\/h3>\n<p>The tool supports a <code>strategy<\/code> setting that reflects what you know about the data location. The default <code>copilot<\/code> strategy is the broad choice: it searches indexed Microsoft 365 content and can also search federated connectors, external data sources and MCP tools. Use <code>grounding<\/code> when the request can be answered from the Microsoft 365 index alone. It searches indexed SharePoint, OneDrive, Teams and Outlook content. Values other than <code>copilot<\/code> and <code>grounding<\/code> are rejected.<\/p>\n<p>For applications that need narrower source selection, you can also rely on the <code>capabilities<\/code> parameter. It accepts an optional allow-list using the Declarative Agent capability shape. It can restrict retrieval to capability families such as <code>Email<\/code>, <code>TeamsMessages<\/code>, or <code>OneDriveAndSharePoint<\/code>, with capability-specific scope fields where applicable. With this parameter you can also target a specific SharePoint site, OneDrive location, SharePoint Embedded container, a shared mailbox or specific mail folders, or a single Federated connector. Omitting the list, or passing an empty list, leaves all sources available to the selected agent in scope.<\/p>\n<div class=\"table-wrap\">\n<table>\n<thead>\n<tr>\n<th>Parameter<\/th>\n<th>What it controls<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td><code>query<\/code><\/td>\n<td>Required. A natural-language description of what to find; empty or whitespace-only input is invalid.<\/td>\n<\/tr>\n<tr>\n<td><code>includeDeveloperCard<\/code><\/td>\n<td>Optional orchestration diagnostics from the backend, including agent metadata, tool invocation details and a retrieval summary. Defaults to <code>false<\/code>.<\/td>\n<\/tr>\n<tr>\n<td><code>agentId<\/code><\/td>\n<td>Targets a custom Copilot agent (<code>bizchat-as-gpt-scenario<\/code>); the ID is included in the request.<\/td>\n<\/tr>\n<tr>\n<td><code>strategy<\/code><\/td>\n<td><code>copilot<\/code> (default) searches indexed Microsoft 365 content plus federated connectors, external sources and MCP tools. Use it when the location is unknown or may be outside the index. <code>grounding<\/code> limits retrieval to indexed SharePoint, OneDrive, Teams and Outlook content. Other values are rejected.<\/td>\n<\/tr>\n<tr>\n<td><code>capabilities<\/code><\/td>\n<td>An optional Declarative Agent capability allow-list, including any capability-specific scopes: <code>People<\/code>, <code>Meetings<\/code>, <code>OneDriveAndSharePoint<\/code>, <code>Email<\/code>, <code>TeamsMessages<\/code>, <code>Dataverse<\/code> and <code>GraphConnectors<\/code>. Omit it or pass an empty list to search all sources available to the selected agent. It cannot be combined with a non-default <code>agentId<\/code>; <code>Dataverse<\/code> and <code>GraphConnectors<\/code> cannot be combined with <code>grounding<\/code>.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/div>\n<h3>Try it in the Interactive Demo<\/h3>\n<p>Open the <a href=\"https:\/\/aka.ms\/copilot.dev\" target=\"_blank\" rel=\"noopener\">Interactive Demo<\/a> and explore the Work IQ MCP tools. A query that spans different work artifacts makes the distinction between broad and index-only retrieval concrete. For example, this conceptual request uses the broad default strategy and leaves the source set to the selected agent:<\/p>\n<pre><code>{\r\n  \"query\": \"Find the latest launch decision, who owns the follow-up, and the meeting or document it came from\",\r\n  \"strategy\": \"copilot\",\r\n  \"includeDeveloperCard\": false\r\n}<\/code><\/pre>\n<p><a href=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2026\/10\/Interactive-Demo-Retrieve.webp\"><img decoding=\"async\" class=\"alignnone wp-image-26256\" src=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2026\/10\/Interactive-Demo-Retrieve-300x149.webp\" alt=\"Interactive Demo Retrieve tool in action\" width=\"749\" height=\"372\" srcset=\"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2026\/10\/Interactive-Demo-Retrieve-300x149.webp 300w, https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2026\/10\/Interactive-Demo-Retrieve-1024x507.webp 1024w, https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2026\/10\/Interactive-Demo-Retrieve-768x380.webp 768w, https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2026\/10\/Interactive-Demo-Retrieve-1536x761.webp 1536w, https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-content\/uploads\/sites\/73\/2026\/10\/Interactive-Demo-Retrieve.webp 1918w\" sizes=\"(max-width: 749px) 100vw, 749px\" \/><\/a><\/p>\n<p>To constrain a query to the Microsoft 365 index, set <code>\"strategy\": \"grounding\"<\/code>. To narrow further, supply <code>capabilities<\/code> as a JSON array of capability objects\u2014for example, an <code>Email<\/code> capability with its supported scope fields. Do not combine a capability list with a non-default <code>agentId<\/code>, or include <code>Dataverse<\/code> or <code>GraphConnectors<\/code> with the <code>grounding<\/code> strategy. Use <code>includeDeveloperCard: true<\/code> while debugging orchestration to request backend diagnostics; leave it false for the normal retrieval path.<\/p>\n<p>In the response, ground the answer on <code>markdown<\/code>, then resolve the inline citation IDs against <code>retrievalHits<\/code>. The payload is namespaced as <code>application\/vnd.ms-workiq.retrieval<\/code>. The following abbreviated example illustrates its shape; real responses can contain many more hits and richer resource-specific metadata:<\/p>\n<pre><code>{\r\n  \"application\/vnd.ms-workiq.retrieval\": {\r\n    \"markdown\": \"## Files\\n- **Launch decision** [^h1]\\n\\n## Meetings\\n- **Follow-up owner** [^h2]\",\r\n    \"retrievalHits\": [\r\n      {\r\n        \"id\": \"h1\",\r\n        \"webUrl\": \"https:\/\/example.com\/sites\/project\/decision\",\r\n        \"entityType\": \"Files\",\r\n        \"sensitivityLabel\": {}\r\n      },\r\n      {\r\n        \"id\": \"h2\",\r\n        \"webUrl\": \"https:\/\/example.com\/meetings\/project\/recap\",\r\n        \"entityType\": \"Meetings\",\r\n        \"sensitivityLabel\": {}\r\n      }\r\n    ],\r\n    \"resultCount\": 2,\r\n    \"stoppedReason\": \"completed\"\r\n  }\r\n}<\/code><\/pre>\n<\/section>\n<section aria-labelledby=\"closing\">\n<h2 id=\"closing\">Build your intelligent agents with Work IQ<\/h2>\n<p>Try the pattern in the Interactive Demo: use <code>retrieve<\/code> when an agent needs cited context across work sources. Experiment with deliberate strategy and source choices, inspect the returned grounding and metadata, and see how source-aware retrieval can shape your own agent architecture.<\/p>\n<p>For more insights about Work IQ, join us at <strong>Microsoft Ignite in San Francisco, November 17\u201320, 2026<\/strong>. Watch the <a href=\"https:\/\/ignite.microsoft.com\/\" target=\"_blank\" rel=\"noopener\">Microsoft Ignite site<\/a> for event details and roadmap updates, and bring your questions about the future of Work IQ.<\/p>\n<\/section>\n<section aria-labelledby=\"links\">\n<h2 id=\"links\">Useful links<\/h2>\n<p>Here you can find some useful links:<\/p>\n<ul>\n<li><a href=\"https:\/\/learn.microsoft.com\/en-us\/microsoft-365\/copilot\/extensibility\/work-iq\/mcp\/retrieve\">Use the retrieve tool in Work IQ MCP<\/a><\/li>\n<li><a href=\"https:\/\/learn.microsoft.com\/en-us\/microsoft-365\/copilot\/extensibility\/work-iq\/mcp\/migrate-retrieval-api\">Migrate agentic retrieval workflows to Work IQ MCP<\/a><\/li>\n<li><a href=\"https:\/\/aka.ms\/copilot.dev\" target=\"_blank\" rel=\"noopener\">Explore the Interactive Demo<\/a><\/li>\n<li><a href=\"https:\/\/ignite.microsoft.com\/\" target=\"_blank\" rel=\"noopener\">Learn more about Microsoft Ignite<\/a><\/li>\n<\/ul>\n<\/section>\n<\/article>\n<p>&nbsp;<\/p>\n","protected":false},"excerpt":{"rendered":"<p>The new Work IQ Retrieve tool grounds agents in the context of work, helping them reason over the right information and deliver more relevant, trustworthy responses. With one retrieval layer across work sources, developers can give agents richer organizational context without building separate search systems. Retrieve: grounded answers across work sources The new MCP tool [&hellip;]<\/p>\n","protected":false},"author":193750,"featured_media":26281,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[390,1],"tags":[398,414,435],"class_list":["post-26252","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-microsoft-365-copilot","category-microsoft-365-developer","tag-mcp","tag-retrieval-api","tag-work-iq"],"acf":[],"blog_post_summary":"<p>The new Work IQ Retrieve tool grounds agents in the context of work, helping them reason over the right information and deliver more relevant, trustworthy responses. With one retrieval layer across work sources, developers can give agents richer organizational context without building separate search systems. Retrieve: grounded answers across work sources The new MCP tool [&hellip;]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/26252","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/users\/193750"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/comments?post=26252"}],"version-history":[{"count":2,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/26252\/revisions"}],"predecessor-version":[{"id":26340,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/posts\/26252\/revisions\/26340"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media\/26281"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/media?parent=26252"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/categories?post=26252"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/wp-json\/wp\/v2\/tags?post=26252"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}