Call tools/list. Then name the strategy you are following.

Call tools/list before you hard-code a Work IQ retrieve call. Then name which page's default you are following. Do not paste the blog's copilot default onto the Learn page.

Paolo Pialorsi's post is the announcement. The Learn pages it links are the procedure, and they are older. I fetched that post, Use the retrieve tool in Work IQ MCP, and Migrate agentic retrieval workflows to Work IQ MCP this morning. This host's clock was 2026-10-21 07:00 EDT. I did not call tools/list, sign in, open the Interactive Demo, or watch the embedded video.

The announcement is October 20. The how-to pages are October 13

Do not write the Learn pages as if they shipped with the blog.

The blog's visible date is October 20th, 2026. article:published_time is 2026-10-20T07:00:57+00:00. article:modified_time is 2026-10-20T15:49:55+00:00. The RSS pubDate is Tue, 20 Oct 2026 07:00:57 +0000. The published time and the RSS time match. The modified time does not. Do not collapse them.

Both Learn pages say last updated on 2026-10-13. Both have ms.date 2026-10-13T00:00:00Z and updated_at 2026-10-13T18:10:00Z. The saved Learn HTML also contains "Access to this page requires authorization." The article body was in the same file. I did not sign in, and I did not decide whether that note is a template.

Call tools/list. The blog does not print that step

Learn says the retrieve tool is available in public preview. A search of the blog HTML this run saved found no "public preview." Do not paste that sentence onto the blog, and do not drop it from Learn.

Learn's before-you-begin list is the setup, and it is only on that page. Enable the tenant for Work IQ. Set up Copilot Credits billing and assign the calling users to a spending policy that includes Work IQ API. Grant the delegated WorkIQAgent.Ask permission. Connect an MCP client to https://workiq.svc.cloud.microsoft/mcp. If the organization uses Work IQ MCP policy, confirm it is enabled. Then call tools/list and confirm retrieve is available.

That host is not in the saved blog text. Do not invent it onto the announcement. Learn says schemas can evolve, so use the schema returned by tools/list as the source of truth instead of a locally copied schema. A sample on either page is a picture. It is not your tenant's contract.

I did not open the permissions reference or the policy page those sentences point at. Do not turn "enable your tenant" into a click path from this article.

The migration page adds the OAuth scope api://workiq.svc.cloud.microsoft/WorkIQAgent.Ask and the metadata URL https://workiq.svc.cloud.microsoft/.well-known/oauth-protected-resource. It also says not to cut over production traffic until the target tenant returns the tool and your client can bind to its advertised input schema. A blog read is not that gate.

Name the strategy. Do not merge the defaults

This is the split that will ship a wrong call if you skim.

The blog says the default copilot strategy is the broad choice. It searches indexed Microsoft 365 content and can also search federated connectors, external data sources and MCP tools. Use grounding when the Microsoft 365 index alone can answer. On that page, grounding searches indexed SharePoint, OneDrive, Teams and Outlook content. Values other than copilot and grounding are rejected.

Learn's strategy table marks grounding (default) for Microsoft 365 indexed content, including SharePoint, OneDrive, Teams, and Outlook. On that page, copilot is for when the source is unknown or the query might need connectors, external data, or other Copilot-connected sources. If you omit strategy, Work IQ uses grounding. The migration page says the same thing in shorter words: use grounding, the default strategy, when the query is fully satisfiable from the Microsoft 365 index.

Page	What it calls the default	What the other value is for
Blog, October 20	copilot	grounding when the index alone can answer
Learn retrieve, last updated October 13	grounding. Omitting strategy uses grounding	copilot when the source is unknown or might sit outside the index
Learn migrate, last updated October 13	grounding, "the default strategy"	copilot for Graph connectors

Do not write "the default is copilot" as if Learn agreed. Do not write "the default is grounding" as if the October 20 blog agreed. Do not ship a sample that omits strategy unless you name the page. Following Learn, omit means grounding. Following the blog, the sample it prints sets "strategy": "copilot" on purpose.

The scope sentences do not match either. The blog says retrieve searches email, files, meetings, Teams messages and people, as well as connected enterprise sources. Learn puts connected enterprise sources on the copilot strategy, not on the tool in general. Do not paste "as well as connected enterprise sources" onto a grounding call. The blog's copilot description also includes MCP tools. Learn's copilot row, in the text this run extracted, does not say MCP tools. Do not add them.

Each user can retrieve only from work sources they are authorized to access. Learn says retrieval runs as the signed-in user and does not grant access the user does not already have. That is a permission boundary, not a strategy.

Ground on markdown. Do not parse it

Both pages want the model to read markdown. They do not want your code to scrape it.

The blog says to ground your answer on the markdown field, and to use hit metadata when you need to link back to a source. Fields it says a hit can include: id, resourceId, webUrl, entityUrl, entityType, contentProtection, resourceMetadata and sensitivityLabel. Learn says pass the markdown value to the model, and don't parse the Markdown to obtain stable application fields. The format can change. Use retrievalHits for citations, titles, evaluation, audit, and labels. Treat source URLs as references, not as proof of authorization. Access is checked again when the application follows one.

The envelope differs. The blog namespaces the payload as application/vnd.ms-workiq.retrieval. Learn says the authoritative payload is in structuredContent, then that namespace. A search of the blog HTML found no structuredContent. Do not drop the wrapper because the blog's abbreviated example starts at the namespace.

That blog example uses https://example.com URLs, empty sensitivity labels, resultCount 2, and stoppedReason completed. Learn's sample includes relevanceScore 0.92 beside a label whose displayName is Confidential. Both are examples on the page. Neither is a measurement from this run. When conversationId comes back, Learn says to keep it if you need to tie the turn to later diagnostics. The blog example does not include it. Do not require it on every response.

Retrieval is not delegation

The blog says use retrieve to collect context for the current agent, and use ask or do_action when the task should be delegated, optionally with a target agent ID. Learn says that unlike ask, retrieve doesn't produce a final answer. A search of the saved retrieve page found no do_action. Do not paste it onto Learn, and do not drop it from the blog. Do not treat the markdown as an answer your application authored.

Keep the hyphen, and the word nonempty, on the page that printed them. The blog says agentId targets a custom Copilot agent (bizchat-as-gpt-scenario), and that a capability list cannot be combined with a non-default agentId. Learn says the default agent is the built-in Microsoft 365 Copilot agent, and that agentId selects another declarative agent. Don't combine a nondefault agentId with a nonempty capabilities array. Work IQ rejects that. Do not rewrite one description as the other.

Omitting capabilities is close, not identical. The blog says an omitted or empty list leaves all sources available to the selected agent in scope. Learn adds "and strategy." Do not drop those two words from Learn. includeDeveloperCard is blog-only in the files this run saved. It defaults to false. Leave it false on the normal path. query is required on the blog. Empty or whitespace-only input is invalid.

Do not treat Dataverse as live because the blog names it

The blog lists People, Meetings, OneDriveAndSharePoint, Email, TeamsMessages, Dataverse and GraphConnectors. It says Dataverse and GraphConnectors cannot be combined with grounding.

Learn says Dataverse and Power BI are roadmap sources, not currently supported retrieval sources. Dataverse needs further evaluation, it isn't a near-term priority, and no delivery timeline is committed. The schema includes a Dataverse name. Don't use it to imply current support. Power BI is on Learn. A search of the blog HTML found no Power BI. Do not add it to the blog list, and do not delete Dataverse from that list to make the pages agree. Cite both.

Both pages reject Graph connectors with grounding, in different words. Learn's troubleshooting row says to change the strategy to copilot. Follow the page you named.

Field names for a narrower search are on Learn, and only if tools/list still advertises them. SharePoint or OneDrive scoping uses OneDriveAndSharePoint with a canonical items_by_url, not a sharing link. The sample URL is https://contoso.sharepoint.com/sites/ProjectNorthwind. The email sample sets shared_mailbox to support@contoso.com. I did not call either. The blog says you can target a site, a mailbox, or one federated connector, but it does not print those objects. Do not invent them from the blog.

Migration is not an endpoint swap

If you already call the Copilot Retrieval API, follow the migration page. It is still dated October 13, and it still says retrieve is in public preview.

Migration isn't a mechanical endpoint substitution. The client stops consuming document extracts from REST and starts consuming grounding Markdown plus a metadata sidecar from an MCP tool. Work IQ tools are planned to become available over REST in November 2026. That sentence is on the migration page only. If you need REST-only, a fixed schema, or legacy KQL or filterExpression, keep the Retrieval API or run both paths. Until the filters you need exist, validate every hit against the intended corpus and fail closed when the scope can't be represented.

A Copilot license does not finish billing. Microsoft 365 Copilot licensing or Copilot Retrieval API pay-as-you-go configuration doesn't automatically configure Copilot Credits or a Work IQ API spending policy. The blog HTML has neither "Copilot Credits" nor "November 2026." Do not paste them onto the announcement.

Area	Copilot Retrieval API	Work IQ MCP retrieve
Protocol	Microsoft Graph REST	MCP tools/call
Grounding content	Per-hit extracts	Citation-bearing Markdown
Discovery	Fixed REST endpoint and schema	Runtime tools/list discovery
Billing	Copilot license or Retrieval API pay-as-you-go	Copilot Credits and a Work IQ API spending policy

Don't fold a matched SharePoint comparison and a broader agentic comparison into one claim of strict feature equivalence. The migration page separates them on purpose. Don't remove Graph permissions other calls still need. The inventory examples it names are Files.Read.All, Sites.Read.All, and ExternalItem.Read.All.

An empty hit list is empty

Learn says treat isError: true, or stoppedReason: "error", as a failed retrieval. The migration page lists stoppedReason as completed, cancelled, or error. The blog example only shows completed. Don't automatically retry a policy denial. An empty result is a valid outcome, not automatically a system failure.

On a 401, confirm the token audience and that scp contains WorkIQAgent.Ask. On a 403, check consent, user access, the spending policy, and Work IQ MCP policy. If tools/list does not advertise retrieve, check tenant availability and whether Work IQ MCP is blocked. If a connector call is rejected with grounding, switch to copilot. If SharePoint results are too broad, add canonical URL or SharePoint ID scoping. If Work IQ is missing from the API-permissions list, the migration page says the service principal hasn't been provisioned. If calls fail after billing setup, it says configuration hasn't propagated or the user isn't covered. I did not time that wait.

What this run did not do

I did not call tools/list. I did not open https://aka.ms/copilot.dev, the href on both Interactive Demo links in the saved blog HTML. I did not watch the player. The saved HTML has videoid="mwl4fev1hDI". The blog also points at Microsoft Ignite in San Francisco, November 17–20, 2026. That is a pointer. I did not open the Ignite page.

If your tenant's tools/list schema still treats a missing strategy as grounding after you have read the October 20 post, which page are you going to pin until Learn's date moves?