adding retrieve skill to work-iq

plugins/workiq-preview/skills/workiq-preview/SKILL.md

@@ -1,23 +1,24 @@
 ---
 name: workiq-preview
-description: WorkIQ - Microsoft 365 tool surface for agents. Use for any workplace question or write action where data lives in M365. Supports semantic `ask` plus structured tools (`fetch`, create/update/delete, actions, functions, path/schema discovery) for mail, meetings/calendar, documents/files, Teams chats/channels, OneDrive/SharePoint, and people. Read triggers, "what did [person] say", priorities/top of mind, meeting decisions/action items, summarize thread/chat, find emails/docs, list meetings/messages/files/channels, project status/updates, "what changed since". Write triggers, send/reply/forward email, create/update/accept/decline meetings, mark read, delete drafts/items, send/post/reply/react in Teams, set presence, upload/download via web URL. Discovery triggers, available endpoints/paths, fields, required/updatable properties, request body, operation parameters, schema/data model. When in doubt about workplace context, try WorkIQ first. Prefer `ask` for synthesis; use entity tools for exact reads/writes.
+description: WorkIQ - Microsoft 365 tool surface for agents. Use for any workplace question or write action where data lives in M365. Supports `retrieve` for structured search (natural-language queries, structured hits), semantic `ask`, plus entity tools (`fetch`, create/update/delete, actions, functions, path/schema discovery) for mail, meetings, files, Teams, OneDrive/SharePoint, people. Read triggers, "what did [person] say", top of mind, meeting decisions/action items, summarize thread, find emails/docs, list meetings/messages/files/channels, project status, "what changed since". Write triggers, send/reply/forward email, create/update/accept meetings, mark read, delete items, post/react in Teams, set presence. Discovery triggers, endpoints/paths, fields, request body, schema. Prefer `retrieve` as default for M365 search/find/lookup — always when caller is an agent/LLM/MCP/tool or a human wants structured/JSON output; use `ask` only when a human needs synthesized prose; use entity tools for exact reads/writes.
 compatibility: >
   Uses the hosted WorkIQ MCP endpoint. No local package is required for MCP
   tool calls.
 ---
 
 # WorkIQ
 
-WorkIQ connects AI agents to Microsoft 365 Copilot for workplace intelligence grounded in organizational data. This skill teaches the model how to use the full WorkIQ toolset: the agentic `ask` tool for semantic questions and the fast **entity tools** for direct structured access to M365 data (`fetch`, `create_entity`, `update_entity`, `delete_entity`, `do_action`, `call_function`, `search_paths`, `get_schema`).
+WorkIQ connects AI agents to Microsoft 365 Copilot for workplace intelligence grounded in organizational data. This skill teaches the model how to use the full WorkIQ toolset: the agentic `ask` tool for semantic questions, the `retrieve` tool for structured M365 resource retrieval, and the fast **entity tools** for direct structured access to M365 data (`fetch`, `create_entity`, `update_entity`, `delete_entity`, `do_action`, `call_function`, `search_paths`, `get_schema`).
 
 ## 🛑 STOP — Read This Before Your First Tool Call
 
-The tools in this skill are documented by their **logical names** (`ask`, `fetch`, etc.), but your MCP host almost certainly exposes them under a **prefixed** name.
+The tools in this skill are documented by their **logical names** (`retrieve`,`ask`, `fetch`, etc.), but your MCP host almost certainly exposes them under a **prefixed** name.
 
 **The MCP server is named `workiq-preview`. Tool prefixes are derived from the MCP server name — never from the name of this skill or its containing folder.**
 
 ❌ **DO NOT** derive a prefix from this skill's name or folder.
 ❌ **DO NOT** call `ask` verbatim and assume it will work.
+✅ **DO** scan your available tools list for an entry whose name **ends with** `retrieve` and call that exact name. In Copilot CLI this will be `workiq-preview-retrieve`.
 ✅ **DO** scan your available tools list for an entry whose name **ends with** `ask` and call that exact name. In Copilot CLI this will be `workiq-preview-ask`.
 
 See [Resolving tool names in your host](#resolving-tool-names-in-your-host) below for the full resolution algorithm. If you skip this step, your first tool call will fail with "tool does not exist."
@@ -28,22 +29,32 @@ See [Resolving tool names in your host](#resolving-tool-names-in-your-host) belo
 
 **USE WorkIQ for ANY workplace-related question.** If the answer might exist in Microsoft 365 data, try WorkIQ first.
 
-**Choosing the right tool:** Use `ask` when the question requires **semantic understanding, synthesis, or reasoning** across M365 data ("what did someone say", "what's the status", "summarize"). Use `fetch` (or another entity tool) when the question is a **literal lookup of structured data** with a known shape ("list my meetings on Monday", "show me unread emails from X"). Entity tools return in under a second; `ask` typically takes 10–60 seconds per call and broad questions can run several minutes.
+**Choosing the right tool — decide by *who is consuming the answer*, not by how the question is phrased.**
+
+Both `retrieve` and `ask` accept natural-language queries. The real question is whether the caller needs **conversational synthesis** (prose) or **structured hits** (data). Use that to pick.
+
+1. **`retrieve` is the default for any search, find, lookup, or "what/who/where" question against M365 data** (emails, files, meetings, Teams messages, people). It accepts the same natural-language queries as `ask`, but returns structured per-source hits plus a grounding markdown summary instead of a synthesized narrative. It is faster than `ask` because it skips conversational synthesis.
+   - **Prefer `retrieve` when conversational synthesis is not needed and a structured response is more useful.** This is almost always true when the caller is an **agent, LLM, MCP client, downstream tool, RAG pipeline, or any programmatic consumer** — they want raw hits + citations to process themselves, not prose. It is also true when a human explicitly asks for structured output (JSON, table, CSV, list of records, "return as JSON", schema-shaped output) or hands you a structured prompt (JSON/YAML/schema).
+   - Use `retrieve` even for "what did X say", "summarize the thread", "find docs about Y", "status of Z" — the grounding markdown is usually enough to answer directly, and the structured hits are ready to hand off to another agent or tool.
+2. **Use `ask` only when the *end consumer is a human* who wants a synthesized, conversational answer** and `retrieve`'s hits + grounding markdown are not enough on their own — e.g., multi-step reasoning across many sources, or an agentic narrative the caller cannot compose themselves. If `retrieve` returns useful hits, prefer citing them over escalating to `ask`. Do **not** use `ask` when the caller is another agent/tool or wants JSON/structured output — use `retrieve`.
+3. **Use `fetch` (or another entity tool) for literal structured lookups with a known shape and path** ("list my meetings on Monday", "show me unread emails from X", "get event by ID"). Entity tools return in under a second and are the right tool once you know the exact path/ID.
+
+Latency: entity tools < 1 s; `retrieve` typically 10–60 s; `ask` 10–60 s and broad questions can run several minutes.
 
 **ALWAYS use WorkIQ when the user asks about:**
 
 | User Question Pattern | Example | Action |
 |-----------------------|---------|--------|
-| What someone said/shared/communicated | "What did Rob say about the API design?" | `ask` |
-| Someone's priorities/concerns/focus | "What's top of mind for Sarah?" | `ask` |
-| Meeting content/decisions/action items | "What was decided in yesterday's standup?" | `ask` |
-| Summarizing email threads or conversations | "Summarize the deadline thread with John" | `ask` |
-| Synthesizing Teams chat activity | "What's the team's take on the release?" | `ask` |
-| Finding documents by topic | "Where is the design doc for Project X?" | `ask` |
-| Colleague expertise or ownership | "Who owns the billing system?" | `ask` |
-| Organizational context / goals | "What are the team's Q1 goals?" | `ask` |
-| Project status or updates | "What's the status of Project X?" | `ask` |
-| Open-ended "any updates" / catch-up questions | "Any updates I should know about?" | `ask` |
+| What someone said/shared/communicated | "What did Rob say about the API design?" | `retrieve`  |
+| Someone's priorities/concerns/focus | "What's top of mind for Sarah?" | `retrieve`  |
+| Meeting content/decisions/action items | "What was decided in yesterday's standup?" | `retrieve`  |
+| Summarizing email threads or conversations | "Summarize the deadline thread with John" | `retrieve`  |
+| Synthesizing Teams chat activity | "What's the team's take on the release?" | `retrieve`  |
+| Finding documents by topic | "Where is the design doc for Project X?" | `retrieve` |
+| Colleague expertise or ownership | "Who owns the billing system?" | `retrieve`  |
+| Organizational context / goals | "What are the team's Q1 goals?" | `retrieve`  |
+| Project status or updates | "What's the status of Project X?" | `retrieve`  |
+| Open-ended "any updates" / catch-up questions | "Any updates I should know about?" | `retrieve`  |
 | Listing meetings on a known date/range | "What meetings do I have Monday?" | `fetch` (`/me/calendarView`) |
 | Listing emails with concrete filters | "Show my unread emails from Rob this week" | `fetch` (`/me/messages`) |
 | Listing Teams chats / channels / members | "List the channels in the DevX team" | `fetch` |
@@ -163,7 +174,7 @@ If a WorkIQ MCP call fails because the user is not signed in, the token is stale
 
 ## Resolving tool names in your host
 
-Throughout this skill (and its `references/*.md`), MCP tools are referred to by their **logical names** — for example `ask`, `fetch`, `search_paths`, etc.
+Throughout this skill (and its `references/*.md`), MCP tools are referred to by their **logical names** — for example `retrieve` `ask`, `fetch`, `search_paths`, etc.
 
 > **⚠️ Common pitfall:** Tool prefixes come from the **MCP server name** (`workiq-preview`) — never from the name of this skill or its containing folder. Do not construct a prefix from the skill name.
 
@@ -187,7 +198,7 @@ If you call the logical name verbatim and get a "tool does not exist" error, thi
 
 ### `ask` — Agentic natural language M365 queries
 
-The primary tool. Ask any workplace question in plain English. This is an **agentic tool** — it orchestrates multi-step operations internally (searching emails, meetings, Teams chats, documents, people) to answer complex questions. Use it when you need intelligence, synthesis, or semantic understanding across M365 data.
+The primary conversational tool. Ask any workplace question in plain English. This is an **agentic tool** — it orchestrates multi-step operations internally (searching emails, meetings, Teams chats, documents, people) to answer complex questions. Use it when you need intelligence, synthesis, or semantic understanding across M365 data.
 
 > **⏱️ High latency:** A call typically takes **10–60 seconds** as the agent performs multiple backend operations, and broad questions can run several minutes (the hard limit is ~300s). Avoid calling it in tight loops or for simple data retrieval — use the entity tools below for that instead. If a question is broad, split it into scoped sub-questions rather than one mega-question.
 
@@ -206,6 +217,29 @@ For detailed usage and examples, read `references/ask-work-iq.md`.
 
 ---
 
+### `retrieve` — Structured M365 resource retrieval
+
+The primary tool for search and retrieval. Search across the user's M365 data (emails, files, meetings, Teams messages, people) and return structured results with a model-friendly grounding summary. `retrieve` accepts the same natural-language queries as `ask`, but instead of a synthesized conversational answer it returns **raw retrieval hits** — per-source references with rich metadata (resource type, URL, author, timestamps, sensitivity label) plus a grounding markdown — optimized for programmatic consumption, RAG pipelines, and agent-to-agent grounding. **Prefer `retrieve` over `ask` whenever conversational synthesis is not needed and a structured response is more useful** — which is almost always true when the caller is another agent, LLM, MCP client, or external tool, and also true when a human explicitly asks for structured (JSON/table/CSV) output or provides a structured (JSON/YAML/schema) prompt.
+
+> **⏱️ Latency:** Typically 10–60 seconds — lower than `ask` because it skips conversational synthesis. Prefer `retrieve` over `ask` for programmatic/structured consumers; reserve `ask` for humans who need a synthesized narrative.
+>
+> **📄 Consuming the response:** The `markdown` field is the **preferred** output — a model-friendly grounding summary with inline `[^id]` citations that map to `retrievalHits[*].id`. Emit it verbatim to the caller; do not paraphrase it or rebuild a summary from `retrievalHits`. Reach into the structured `retrievalHits` payload only for specific fields the markdown doesn't already expose (e.g., a raw `webUrl` or `sensitivityLabel` for one hit).
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `query` | string[] | Yes | One or more natural-language search queries. At least one non-empty entry required. |
+| `strategy` | string | No | `copilot` (default — M365 indexed content plus connected data sources, federated connectors, MCP tools) or `orchestratedSearch` (M365 indexed content only). Any other value is rejected. |
+| `includeDeveloperCard` | boolean | No | When `true`, includes orchestration diagnostics in the response. Defaults to `false`. |
+| `agentId` | string | No | Only `bizchat-as-gpt-scenario` is accepted; any other value is rejected. |
+
+```json
+{ "query": ["design doc for authentication", "auth spec Project X"] }
+```
+
+For detailed usage, response structure, strategy guidance, and faceted metadata, read `references/retrieve-work-iq.md`.
+
+---
+
 ## Entity Tools
 
 Entity tools provide **fast, direct access to specific M365 data** via Work IQ APIs. They return structured results quickly but have **no intelligence** — they don't interpret, synthesize, or reason about the data. Use them when you know exactly what you want and where it lives.
@@ -214,7 +248,8 @@ Entity tools provide **fast, direct access to specific M365 data** via Work IQ A
 
 | Scenario | Use |
 |----------|-----|
-| Open-ended question, semantic search, synthesis | `ask` (slow but smart) |
+| Search / find / lookup M365 references (default for reads) | "Find emails about WorkIQ", "who talked about deployment rollback?" | `retrieve` (structured hits + grounding markdown) |
+| Open-ended question requiring synthesis beyond `retrieve`'s markdown | Multi-source narrative, agentic reasoning | `ask` (slow but smart — only when `retrieve` is insufficient) |
 | Fetch a known list, apply a filter, get structured data | entity tools (fast but literal) |
 
 **Recommended workflow:** for **well-known paths, go direct** — call the read/write tool immediately (use the cheat sheet below). Only fall back to `search_paths` → `get_schema` → tool when the path is genuinely unknown or a write body shape is unfamiliar. Do **not** reflexively run `search_paths`/`get_schema` before every common operation.
@@ -392,4 +427,5 @@ Read the relevant reference file for full parameter details and examples:
 - `references/update-entity-work-iq.md` — if you need to update fields on an existing entity
 - `references/delete-entity-work-iq.md` — if you need to delete an entity
 - `references/do-action-work-iq.md` — if you need to send mail, accept/decline meetings, copy/move messages
+- `references/retrieve-work-iq.md` — if you need to retrieve structured M365 references (emails, files, meetings, Teams messages, people) for programmatic use, RAG, or agent grounding
 - `references/troubleshooting.md` — if a tool call fails unexpectedly, returns an error, or behaves differently than documented