Status: Public Preview — behaviour may change.

What it does

retrieve is a tool on the Work IQ MCP server that searches whatever the signed-in user can already see and hands back grounding content for your own agent or application to reason over. Unlike the ask tool it doesn't write the final answer; it returns citation-bearing Markdown, structured metadata for each source, a result count and a terminal status. It is also Microsoft's stated destination for delegated, agentic apps currently built on the Copilot Retrieval API.

Key facts

• Endpoint and auth. Connect an MCP client to https://workiq.svc.cloud.microsoft/mcp, authenticate as the user, and register an app with the delegated WorkIQAgent.Ask permission (admin consent needed). Retrieval runs as the user and never widens their access.
• Billing is separate from licensing. Calling users need a spending policy that includes Work IQ API under usage-based billing for Copilot Credits. A Microsoft 365 Copilot licence or an existing Retrieval API pay-as-you-go setup doesn't configure that for you.
• Two strategies. grounding (the default) searches the Microsoft 365 index: SharePoint, OneDrive, Teams, Outlook. copilot adds the connected enterprise sources available to Copilot. The GraphConnectors capability only works with copilot.
• Scoping is by capability allow list. Names are People, Meetings, OneDriveAndSharePoint, Email, TeamsMessages and GraphConnectors. Leave it empty and everything the agent can reach is searched. SharePoint and OneDrive scoping takes a canonical site, library or folder URL (not a sharing link) or SharePoint IDs; SharePoint Embedded is covered the same way. Email can be narrowed to a shared mailbox, group mailboxes or folders.
• Declarative agents. Pass agentId to retrieve through another declarative agent. That agent defines its own data scope, so a non-default agentId plus a non-empty capabilities array is rejected.
• Dataverse and Power BI are not supported sources. The schema includes a Dataverse capability name, but Microsoft says it isn't a supported retrieval source, needs further evaluation and has no committed date. Power BI is likewise roadmap only.
• Response. The payload lives under structuredContent > application/vnd.ms-workiq.retrieval: markdown (inline [^h1] references), retrievalHits[] (URLs, entity IDs, titles, authors, sensitivity label, relevance), resultCount, stoppedReason (completed, cancelled, error) and sometimes conversationId.
• Failure is two signals. isError: true on the tool result, or stoppedReason: "error" in the payload. Policy denials must not be auto-retried.
• Migration from the Copilot Retrieval API is documented as a separate guide. It is a rewrite of request and response handling, not an endpoint swap. Microsoft says to keep the old integration if you need a REST-only fixed schema (Work IQ tools are planned for REST in November 2026) or depend on KQL/filterExpression, for which extra retrieve filtering is only on the roadmap.

When to use / skip

Use it when you're building your own agent loop that needs permission-trimmed grounding across files, mail, meetings, Teams and people, and you want the model fed Markdown with citations rather than raw extracts. Skip it if you need a fixed REST contract today, rely on KQL filtering, or expected Dataverse or Power BI data to come back; none of those is available.

Configuration decisions

• grounding or copilot. Default to grounding when the answer is definitely in the Microsoft 365 index. Reach for copilot when the source is unknown or sits in a connector.
• Which capabilities to allow-list. An empty list means broad search. Decide per use case, not globally.
• Who gets the spending policy. Pilot with one security group so cost and relevance can be measured before everyone is included.
• Work IQ MCP policy. If your organisation has policy governance for Work IQ MCP, confirm it's switched on before you debug anything else.
• Rollback window. Keep the old Retrieval API path alive for a defined period after cutover.

Gotchas

• The schema from tools/list is the source of truth. Don't hard-code a copied schema; tool availability and shapes are still moving.
• Don't parse the Markdown for application fields. It's tuned for models and its format can change. Citations, URLs, labels and audit data come from retrievalHits.
• Returned URLs and entity references aren't proof of authorisation. Access is re-checked when your app follows them.
• A scope you can't express has to fail closed. Until the missing filters land, validate every hit against the corpus you intended.
• An empty result is a valid outcome, not an outage. Don't alert on it.
• A 401 is usually the token audience or a missing WorkIQAgent.Ask in the scp claim; a 403 is more often consent, spending-policy assignment or MCP policy.

Consultant notes

• Billing is the surprise. Clients assume the Copilot licence covers it, then hit a denied call at UAT because nobody assigned the spending policy. Put it in the readiness checklist.
• For migrations, insist on two separate test sets: a matched SharePoint comparison for compatibility, and a wider agentic comparison for the new sources. Merging them into a single "equivalent" claim won't survive a sceptical architect.
• Sensitivity labels come through in the hit metadata. Decide at design time what your app does with them (redact, filter, or just display) rather than discovering the question at security review.
• It's preview, and the REST arrival and filter support are both dated vaguely. Build behind a thin interface so you can swap transport without touching the agent logic.

---

Worth revisiting when the REST availability planned for November 2026 and the extra filter support land.