Use the retrieve tool in Work IQ MCP

The Work IQ MCP retrieve tool searches data that the signed-in user can access and returns grounding content for an AI agent. Use it when your application needs source content and metadata that it can pass to a model, evaluate, rerank, audit, or use in a multistep agentic workflow.

Unlike the ask tool, retrieve doesn't produce a final answer to the user's question. It returns:

• Model-friendly Markdown with inline citations.
• Structured metadata for each cited source.
• A terminal status and result count.

The retrieve tool can search Microsoft 365 data such as email, files, meetings, Teams messages, and people. By using the copilot strategy, it can also search connected enterprise sources available to Microsoft 365 Copilot.

Before you begin

Complete the following prerequisites:

• Enable your tenant for Work IQ.
• Set up usage-based billing for Copilot Credits and assign the calling users to a spending policy that includes Work IQ API.
• Register a client application and grant the delegated WorkIQAgent.Ask permission. For more information, see Work IQ API permissions reference.
• Connect an MCP client to https://workiq.svc.cloud.microsoft/mcp.
• If your organization uses Work IQ MCP policy, confirm that Work IQ MCP is enabled. For more information, see Policy governance for Work IQ MCP.

Call tools/list after connecting and confirm that retrieve is available. Tool availability and schemas can evolve, so use the schema returned by tools/list as the source of truth instead of hard-coding a locally copied schema.

Choose a retrieval strategy

The strategy parameter controls where Work IQ searches.

If you omit strategy, Work IQ uses grounding.

The GraphConnectors capability isn't supported with grounding. Use copilot when you include it.

Run a basic retrieval

The following example searches Microsoft 365 indexed content.

{
  "method": "tools/call",
  "params": {
    "name": "retrieve",
    "arguments": {
      "query": "What are the approved customer identity requirements for Project Northwind?",
      "strategy": "grounding"
    }
  }
}

Search across connected enterprise sources

Use copilot when the source is unknown or might be outside the Microsoft 365 index.

{
  "method": "tools/call",
  "params": {
    "name": "retrieve",
    "arguments": {
      "query": "Find the latest Project Northwind launch risks across company sources.",
      "strategy": "copilot"
    }
  }
}

Limit a request to specific source types

Use capabilities to provide a source allow list for one retrieval request. If you omit capabilities or pass an empty array, Work IQ searches all sources available to the selected agent and strategy.

Supported capability names are:

• People
• Meetings
• OneDriveAndSharePoint
• Email
• TeamsMessages
• GraphConnectors

The schema also includes a Dataverse capability name, but Dataverse isn't currently a supported retrieval source. Don't use it to imply current support.

Search a SharePoint site, SharePoint Embedded container, or OneDrive location

Use OneDriveAndSharePoint with items_by_url. Supply a canonical SharePoint or OneDrive URL, not a sharing link.

{
  "method": "tools/call",
  "params": {
    "name": "retrieve",
    "arguments": {
      "query": "Summarize the approved customer identity requirements.",
      "strategy": "grounding",
      "capabilities": [
        {
          "name": "OneDriveAndSharePoint",
          "items_by_url": [
            {
              "url": "https://contoso.sharepoint.com/sites/ProjectNorthwind"
            }
          ]
        }
      ]
    }
  }
}

You can also scope SharePoint and OneDrive retrieval by SharePoint IDs with items_by_sharepoint_ids.

The retrieve tool supports SharePoint Embedded content that the signed-in user can access. Scope SharePoint Embedded retrieval with the OneDriveAndSharePoint capability and the supported URL or SharePoint ID fields.

Search selected email locations

Use the Email capability to limit retrieval to a shared mailbox, group mailboxes, or specific folders.

{
  "method": "tools/call",
  "params": {
    "name": "retrieve",
    "arguments": {
      "query": "Find the latest customer escalation about Project Northwind.",
      "strategy": "grounding",
      "capabilities": [
        {
          "name": "Email",
          "shared_mailbox": "support@contoso.com"
        }
      ]
    }
  }
}

Search a Microsoft Graph connector

Use GraphConnectors with the copilot strategy. The following example limits retrieval to one connector and adds connector-specific search terms.

{
  "method": "tools/call",
  "params": {
    "name": "retrieve",
    "arguments": {
      "query": "Find open Project Northwind launch risks.",
      "strategy": "copilot",
      "capabilities": [
        {
          "name": "GraphConnectors",
          "connections": [
            {
              "connection_id": "contoso-project-tracker",
              "additional_search_terms": "project:northwind status:open"
            }
          ]
        }
      ]
    }
  }
}

Use a declarative agent

By default, retrieval uses the built-in Microsoft 365 Copilot agent. To retrieve through another available declarative agent, pass its identifier in agentId.

{
  "method": "tools/call",
  "params": {
    "name": "retrieve",
    "arguments": {
      "query": "What product guidance applies to this customer scenario?",
      "agentId": "<declarative-agent-id>",
      "strategy": "copilot"
    }
  }
}

Don't combine a nondefault agentId with a nonempty capabilities array. The declarative agent defines its own data scope, and Work IQ rejects requests that attempt to add a separate capability scope.

Process the response

The authoritative retrieval payload is in:

structuredContent
  -> application/vnd.ms-workiq.retrieval

The response returns grounding content and source metadata together in each results entry.

Read retrieved content from structuredContent["application/vnd.ms-workiq.retrieval"].results, not from the MCP content array. The content array can be empty even when results are returned.

Structured results

The results array replaces the earlier top-level markdown and retrievalHits properties. Update clients to read each result's markdown and source metadata from the same entry.

The following example shows a successful response with an empty MCP content array.

{
  "content": [],
  "structuredContent": {
    "application/vnd.ms-workiq.retrieval": {
      "results": [
        {
          "id": "h1",
          "markdown": "Project Northwind requires phishing-resistant authentication... [^h1]",
          "resourceId": "01ABC...",
          "webUrl": "https://contoso.sharepoint.com/sites/ProjectNorthwind/...",
          "entityUrl": "/drives/{drive-id}/items/{item-id}",
          "entityType": "Files",
          "driveId": "b!example",
          "itemId": "01ABC...",
          "contentProtection": "allowed",
          "resourceMetadata": {
            "document": {
              "title": "Customer identity requirements",
              "authorName": "Adele Vance",
              "occurrenceTime": "2026-09-28T16:30:00Z"
            }
          },
          "sensitivityLabel": {
            "displayName": "Confidential"
          },
          "relevanceScore": 0.92
        }
      ],
      "resultCount": 1,
      "searchMetadata": {
        "queryAlterationResponse": {
          "alteredQuery": "Project Northwind customer identity requirements"
        }
      },
      "stoppedReason": "completed",
      "conversationId": "d488527d-9d34-4e47-a0a8-9c58e46d7252"
    }
  },
  "isError": false
}

Each results entry can contain the following properties. Metadata fields depend on the source type and are included only when available.

Use Markdown for model grounding

Pass each results[].markdown value to the model as grounding context. Use metadata from the same result to identify and link to the source, evaluate results, and record audit data. An empty results array means no results were returned.

Don't parse the Markdown to obtain stable application fields. Its format is optimized for model consumption and can change.

Use source metadata for application logic

Use results for programmatic operations such as:

• Resolving citations to source URLs.
• Displaying source titles and authors.
• Evaluating or reranking results.
• Recording audit and evaluation data.
• Applying application-specific redaction or filtering.
• Navigating to Microsoft Graph entities when entityUrl is available.
• Inspecting sensitivity-label metadata.

Treat entityUrl, source URLs, and source identifiers as references, not as proof of authorization. The user's access is checked again when your application follows a reference.

When conversationId is returned, preserve it if your application needs to associate the retrieval turn with subsequent operations or diagnostics.

Handle errors

Treat either of the following conditions as failed retrieval:

• The MCP tool result has isError: true.
• The retrieval payload has stoppedReason: "error".

Depending on the deployed response contract, the structured payload can also include:

• error
• errorCode
• recoveryAction
• retryAfterSeconds

Don't automatically retry a policy-denied request. Policy denials require the user or an administrator to review access, consent, billing assignment, or Work IQ MCP policy.

Common causes of failure include:

Design agentic workflows with retrieval

For reliable agentic workflows:

1. Discover the retrieve schema through tools/list.
2. Choose grounding when the request is fully satisfiable from the Microsoft 365 index; otherwise use copilot.
3. Use capabilities for explicit source constraints.
4. Pass each result's markdown to the model and use metadata from that same result to identify and link to the source.
5. Use results for code, citations, evaluation, and auditing.
6. Preserve source security metadata such as sensitivity labels.
7. Treat an empty result as a valid retrieval outcome, not automatically as a system failure.
8. Surface policy denials and authentication failures instead of retrying them as transient errors.

Related content

• Work IQ MCP overview
• Work IQ MCP tool reference
• Work IQ API permissions reference
• Policy governance for Work IQ MCP
• Migrate agentic retrieval workflows to Work IQ MCP