From bde24d5303bd2f0397b9db1f3df890fed3213161 Mon Sep 17 00:00:00 2001 From: Steve Calvert Date: Tue, 17 Nov 2026 09:20:12 -0700 Subject: [PATCH 1/2] fix(skills): name optional Glean tools with a fallback A Glean MCP server's tools/list is the only complete list of its tools, and it differs between deployments: admins add and remove toolsets, and some deployments serve a tool under another name. Skills listed tools such as code_search, meeting_lookup and the email tools as if every deployment had them. Skills now name search, read_document, chat and employee_search freely, and name any other Glean tool only with a fallback for when it is missing. using-glean says that tools/list is the source of truth, splits its routing table into core tools and tools to use if available, and drops the host-specific mcp__glean tool prefix. It also gains rules to run independent calls in parallel, stop once the question is answered, retry a search at most twice, and say when sources are stale or disagree. --- .../skills/skill-creation-guide/SKILL.md | 10 +-- shared/glean/skills/plan-prep/SKILL.md | 6 +- .../glean/skills/project-awareness/SKILL.md | 4 +- shared/glean/skills/project-handoff/SKILL.md | 2 +- .../skills/skill-creation-guide/SKILL.md | 16 +++-- shared/glean/skills/using-glean-code/SKILL.md | 2 + .../using-glean-code/reference/exploration.md | 2 + .../using-glean-code/reference/plan-prep.md | 2 +- .../skills/using-glean-productivity/SKILL.md | 4 +- .../reference/priorities.md | 6 +- shared/glean/skills/using-glean/SKILL.md | 65 +++++++++++-------- .../using-glean/reference/agents-as-tools.md | 2 +- .../using-glean/reference/employee-search.md | 4 +- .../using-glean/reference/gmail-search.md | 4 +- .../using-glean/reference/meeting-lookup.md | 4 +- .../skills/using-glean/reference/memory.md | 4 +- .../using-glean/reference/outlook-search.md | 10 +-- .../using-glean/reference/read-document.md | 2 +- .../skills/using-glean/reference/search.md | 6 +- .../skills/using-glean/reference/synthesis.md | 18 ++--- .../using-glean/reference/user-activity.md | 2 +- 21 files changed, 98 insertions(+), 77 deletions(-) diff --git a/overrides/codex/glean/skills/skill-creation-guide/SKILL.md b/overrides/codex/glean/skills/skill-creation-guide/SKILL.md index 04e4e1e..b30e68e 100644 --- a/overrides/codex/glean/skills/skill-creation-guide/SKILL.md +++ b/overrides/codex/glean/skills/skill-creation-guide/SKILL.md @@ -42,9 +42,10 @@ When the user asks what they should automate, analyze their work patterns first. Requires the Glean MCP tools. If they aren't visible, ask the user to set up Glean by prompting the harness (for example, `Set up Glean for me`). -1. Gather context with Glean: `memory` (roles, responsibilities, active - projects), `user_activity` (past ~2 weeks), and `search` for process docs - (`"runbook OR checklist OR process owner:me"`). +1. Gather context with Glean: `search` for process docs + (`"runbook OR checklist OR process owner:me"`), plus `memory` (roles, + responsibilities, active projects) and `user_activity` (past ~2 weeks) if + they are in your tool list. 2. If subagent tools are available, delegate this analysis to a general subagent with the gathered context and recurrence/value tests. Otherwise analyze the patterns directly in the current task. @@ -52,8 +53,7 @@ Glean by prompting the harness (for example, `Set up Glean for me`). rejected candidates with reasons. A few high-quality candidates beat many weak ones — "no automatable patterns" is a valid outcome. -See `using-glean/reference/` for the param shape of `memory`, `user_activity`, -and `search`. +See `using-glean/reference/` for the param shape of each tool. ## Workflow B — Generate a skill diff --git a/shared/glean/skills/plan-prep/SKILL.md b/shared/glean/skills/plan-prep/SKILL.md index fdfe1c4..ee2811a 100644 --- a/shared/glean/skills/plan-prep/SKILL.md +++ b/shared/glean/skills/plan-prep/SKILL.md @@ -44,9 +44,9 @@ Filter aggressively for relevant, current information. | Research Need | Glean Tool | |---------------|-----------| | Find design docs, RFCs, architecture | `search` | -| Find similar code implementations | `code_search` | -| Find code owners and stakeholders | `code_search` + `employee_search` | -| Find related/dependent systems | `code_search` | +| Find similar code implementations | `code_search` if available; otherwise `search` | +| Find code owners and stakeholders | `employee_search`, plus `code_search` if available | +| Find related/dependent systems | `code_search` if available; otherwise `search` | | Read full document content | `read_document` | ## Workflow diff --git a/shared/glean/skills/project-awareness/SKILL.md b/shared/glean/skills/project-awareness/SKILL.md index c235ff9..790b311 100644 --- a/shared/glean/skills/project-awareness/SKILL.md +++ b/shared/glean/skills/project-awareness/SKILL.md @@ -11,7 +11,7 @@ Determine the project or topic from the user's request. If no project name is cl ## Tools -This skill drives the standard Glean MCP tools. For full param shape and pitfalls of `chat`, `search`, `employee_search`, and `meeting_lookup`, see the using-glean reference at `using-glean/reference/`. +This skill drives the standard Glean MCP tools. For full param shape and pitfalls of `chat`, `search`, `employee_search`, and (if it is available) `meeting_lookup`, see the using-glean reference at `using-glean/reference/`. ## When This Applies @@ -70,7 +70,7 @@ chat "What is the current status of [project]? Who owns it and what are the rece For deeper investigation, combine: - `search` for project documentation - `employee_search` for people -- `meeting_lookup` for recent discussions +- `meeting_lookup` for recent discussions, if it is available ## Query Patterns diff --git a/shared/glean/skills/project-handoff/SKILL.md b/shared/glean/skills/project-handoff/SKILL.md index ab07b75..f5459fe 100644 --- a/shared/glean/skills/project-handoff/SKILL.md +++ b/shared/glean/skills/project-handoff/SKILL.md @@ -21,7 +21,7 @@ This skill drives the standard Glean MCP tools. If the host exposes the `project-synthesizer` agent, use it for project research. Otherwise delegate to a suitable research subagent when subagents are available, or gather the same material directly. For the param shape and pitfalls of `search`, `chat`, -`meeting_lookup`, and `employee_search`, see the using-glean reference at +`employee_search`, and (if it is available) `meeting_lookup`, see the using-glean reference at `using-glean/reference/`. If no Glean tools are visible, ask the user to set up Glean by prompting the harness (for example, `Set up Glean for me`). diff --git a/shared/glean/skills/skill-creation-guide/SKILL.md b/shared/glean/skills/skill-creation-guide/SKILL.md index e8fad98..b5686c6 100644 --- a/shared/glean/skills/skill-creation-guide/SKILL.md +++ b/shared/glean/skills/skill-creation-guide/SKILL.md @@ -46,9 +46,10 @@ When the user asks what they should automate, analyze their work patterns first. Requires the Glean MCP tools. If they aren't visible, ask the user to set up Glean by prompting the harness (for example, `Set up Glean for me`). -1. Gather context with Glean: `memory` (roles, responsibilities, active - projects), `user_activity` (past ~2 weeks), and `search` for process docs - (`"runbook OR checklist OR process owner:me"`). +1. Gather context with Glean: `search` for process docs + (`"runbook OR checklist OR process owner:me"`), plus `memory` (roles, + responsibilities, active projects) and `user_activity` (past ~2 weeks) if + they are in your tool list. 2. Spawn the `work-pattern-analyzer` agent to identify repeated queries, frequent contexts, workflow sequences, and manual processes — and to vet each candidate against the recurrence/value tests above. @@ -56,8 +57,7 @@ Glean by prompting the harness (for example, `Set up Glean for me`). rejected candidates with reasons. A few high-quality candidates beat many weak ones — "no automatable patterns" is a valid outcome. -See `using-glean/reference/` for the param shape of `memory`, `user_activity`, -and `search`. +See `using-glean/reference/` for the param shape of each tool. ## Workflow B — Generate a skill @@ -102,8 +102,10 @@ Brief overview of what this skill does. 2. **Progressive disclosure.** Essential action first; detail and edge cases below. Push deep, load-on-demand material into `reference/*.md`. 3. **Actionable, imperative content.** "Search for X", not "Searches for X." -4. **Name the tools** the skill uses (e.g. Glean `search`, `memory`; or `Grep`, - `Read`). +4. **Name the tools** the skill uses (e.g. Glean `search`, `read_document`; or + `Grep`, `Read`). Glean's tool list differs between deployments, so for any + Glean tool beyond `search`, `read_document`, `chat`, and `employee_search`, + say what to do when it is missing. 5. **Stay host-agnostic.** Don't hard-code one host's slash-command syntax or install paths; describe the capability and let each host resolve it. diff --git a/shared/glean/skills/using-glean-code/SKILL.md b/shared/glean/skills/using-glean-code/SKILL.md index c256bb5..17a4952 100644 --- a/shared/glean/skills/using-glean-code/SKILL.md +++ b/shared/glean/skills/using-glean-code/SKILL.md @@ -7,6 +7,8 @@ description: Search and analyze internal source code across the organization's r Glean indexes source code across the organization's connected repositories. Local tools (`Grep`, `Glob`, `Read`) see only the current repo; this skill is for everything else. +This skill needs `code_search`. If `code_search` is not in your tool list, use `search` instead, and tell the user that the results come from document search, not code search. + ## When to reach for this - **Finding the system** — "Where does our payments code live?" diff --git a/shared/glean/skills/using-glean-code/reference/exploration.md b/shared/glean/skills/using-glean-code/reference/exploration.md index f956e32..d193355 100644 --- a/shared/glean/skills/using-glean-code/reference/exploration.md +++ b/shared/glean/skills/using-glean-code/reference/exploration.md @@ -2,6 +2,8 @@ When the user wants to understand a system, pattern, or piece of code that may live anywhere across the org's repositories. +This workflow uses `code_search` when it is in your tool list. If it is missing, use `search` for each step and tell the user that code search isn't available. + ## When this applies - Locating an unfamiliar system: "Where does the billing reconciliation code live?" diff --git a/shared/glean/skills/using-glean-code/reference/plan-prep.md b/shared/glean/skills/using-glean-code/reference/plan-prep.md index 0a356e2..d9974f8 100644 --- a/shared/glean/skills/using-glean-code/reference/plan-prep.md +++ b/shared/glean/skills/using-glean-code/reference/plan-prep.md @@ -22,7 +22,7 @@ When the user is about to enter plan mode for architectural or strategic work, g ``` Note proposals that were *rejected* — they record constraints worth respecting. -2. **Code patterns & implementations.** Use `code_search` for similar solutions across the org: +2. **Code patterns & implementations.** If `code_search` is available, use it for similar solutions across the org; otherwise use `search`: ``` code_search(query="[similar component or pattern]") code_search(query="[interface or library being affected]") diff --git a/shared/glean/skills/using-glean-productivity/SKILL.md b/shared/glean/skills/using-glean-productivity/SKILL.md index ac7c8a6..d194d48 100644 --- a/shared/glean/skills/using-glean-productivity/SKILL.md +++ b/shared/glean/skills/using-glean-productivity/SKILL.md @@ -5,7 +5,7 @@ description: Synthesize the user's own work activity, priorities, and recent con # Using Glean for Personal Productivity -This skill drives queries about the user's own work life — their recent activity, what they accomplished, what's pending, what's urgent. It pulls from `user_activity`, `meeting_lookup`, `search` (with `from:me` / `owner:me`), and `memory` to assemble a personal view rather than an enterprise-wide one. +This skill drives queries about the user's own work life — their recent activity, what they accomplished, what's pending, what's urgent. It pulls from `search` (with `from:me` / `owner:me`) to assemble a personal view rather than an enterprise-wide one. It also uses `user_activity`, `meeting_lookup`, and `memory` when they are in your tool list; if one is missing, use `search` for that part, and say what you couldn't check. ## Two shapes of question @@ -21,7 +21,7 @@ The two overlap (a recent activity feed is the substrate for triaging priorities `user_activity`, `memory`, `search`, and `meeting_lookup` are documented canonically in the `using-glean` skill: - [`../using-glean/reference/user-activity.md`](../using-glean/reference/user-activity.md) — date-range mechanics, the inclusive/exclusive end-date pitfall -- [`../using-glean/reference/memory.md`](../using-glean/reference/memory.md) — `memory` + `memory_schema` for personalization +- [`../using-glean/reference/memory.md`](../using-glean/reference/memory.md) — `memory` + `memory_schema` for personalization, if available - [`../using-glean/reference/search.md`](../using-glean/reference/search.md) — for documents the user authored or was mentioned in - [`../using-glean/reference/meeting-lookup.md`](../using-glean/reference/meeting-lookup.md) — for meetings the user attended diff --git a/shared/glean/skills/using-glean-productivity/reference/priorities.md b/shared/glean/skills/using-glean-productivity/reference/priorities.md index f2d8362..609dad1 100644 --- a/shared/glean/skills/using-glean-productivity/reference/priorities.md +++ b/shared/glean/skills/using-glean-productivity/reference/priorities.md @@ -17,10 +17,10 @@ Prospective questions: what needs the user's attention right now. | Source | What it surfaces | |---|---| | `search` for direct mentions of the user | People tagging or @-mentioning them | -| `meeting_lookup` for recent meetings | Action items assigned to them | +| `meeting_lookup` for recent meetings, if available | Action items assigned to them | | `search` for "urgent" / "ASAP" / "blocking" + their name | Explicit urgency markers | -| Email tools (`gmail_search` / `outlook_search`) with `is:important is:unread` | Unread important threads | -| `user_activity` (recent) | Threads they have been engaged in | +| Email tools (`gmail_search` / `outlook_search`) with `is:important is:unread`, if available | Unread important threads | +| `user_activity` (recent), if available | Threads they have been engaged in | ## Workflow diff --git a/shared/glean/skills/using-glean/SKILL.md b/shared/glean/skills/using-glean/SKILL.md index 60d8702..96a01bd 100644 --- a/shared/glean/skills/using-glean/SKILL.md +++ b/shared/glean/skills/using-glean/SKILL.md @@ -5,50 +5,63 @@ description: Use Glean MCP tools to answer questions about company documents, in # Using Glean -The Glean MCP server exposes a family of tools that let the assistant query the user's company knowledge: documents, people, meetings, email, internal code, the user's activity feed, structured memory, and the knowledge graph. This skill is the entry point. It maps a user's question to the right tool, names the rules that apply across all of them, and links to per-tool reference files that carry the deep syntax. +The Glean MCP server gives the assistant tools that query the user's company knowledge: documents, people, meetings, email, code, the user's activity, and more. This skill maps a question to the right tool, gives the rules that apply to every tool, and links to per-tool reference files. -## Where these tools live +## Which tools you have -The tools listed below come from the user's Glean MCP server connection. Refer to them by their bare names (`search`, `employee_search`, `meeting_lookup`, …) — the assistant resolves them against the active tool inventory. +The Glean server's tool list (`tools/list`) is the only complete list of the tools you can call. It differs between deployments. Admins add and remove toolsets, and some deployments serve a tool under another name. For example, where `enterprise_search` is in the tool list, it is `search`. -In the raw MCP tool list, Glean tools appear as `mcp__glean_[server-name]__[tool]` where `[server-name]` is the user's configured server identifier (e.g., `default`, `production`, `acme`). The tool suffix after the final `__` is always consistent across deployments. Use whatever Glean server is visible in your tool inventory. +- The tools this skill names are examples, not a full list. Before you plan, check which Glean tools are in your tool list. +- Refer to tools by their bare names. Hosts add their own prefixes; match on the tool name at the end. +- Call only tools you can see. If a tool this skill names is missing, use its fallback, or tell the user that their Glean deployment doesn't offer it. +- Read the description of any Glean tool you don't recognize. It may be a platform agent or a newer tool; see [agents-as-tools.md](reference/agents-as-tools.md). -If no Glean tools are visible, ask the user to set up Glean by prompting the -harness (for example, `Set up Glean for me`). +If no Glean tools are visible, ask the user to set up Glean by prompting the harness (for example, `Set up Glean for me`). -## Intent → tool decision tree +## Core tools + +Most deployments serve these. | The user is asking about... | Reach for | Reference | |---|---|---| -| Documents, wikis, policies, RFCs, specs | `search` | [search.md](reference/search.md) | +| Documents, wikis, policies, RFCs, specs, messages, tickets | `search` | [search.md](reference/search.md) | +| A specific URL or document | `read_document` | [read-document.md](reference/read-document.md) | | A complex question that needs synthesis across sources | `chat` | [chat.md](reference/chat.md) | -| Internal source code, files, commits across repos | `code_search` | [code-search.md](reference/code-search.md) | | People, teams, org structure, reporting lines | `employee_search` | [employee-search.md](reference/employee-search.md) | -| Meetings, transcripts, decisions, action items | `meeting_lookup` | [meeting-lookup.md](reference/meeting-lookup.md) | -| Gmail messages, threads, attachments | `gmail_search` | [gmail-search.md](reference/gmail-search.md) | -| Outlook messages, threads, attachments | `outlook_search` | [outlook-search.md](reference/outlook-search.md) | -| Reading a specific URL / document | `read_document` | [read-document.md](reference/read-document.md) | -| The user's own recent activity (standup, weekly summary) | `user_activity` | [user-activity.md](reference/user-activity.md) | -| The user's stored memories / personalization | `memory` (+ `memory_schema`) | [memory.md](reference/memory.md) | -| Structured entity / relationship queries | `knowledge_graph_query` (+ `knowledge_graph_schema`) | [knowledge-graph.md](reference/knowledge-graph.md) | -The reference files are loaded only when needed. Open the relevant one before invoking a tool you haven't used recently — each file carries the exact param shape, the filter syntax, and the pitfalls that have bitten previous calls. +## Other tools, if available + +Use these only when they are in your tool list. Otherwise use the fallback. + +| The user is asking about... | Tool, if available | Fallback | Reference | +|---|---|---|---| +| Internal source code, files, commits | `code_search` | `search`, and say the results come from document search, not code search | [code-search.md](reference/code-search.md) | +| Meetings, transcripts, decisions, action items | `meeting_lookup` | `search` for meeting notes and recaps | [meeting-lookup.md](reference/meeting-lookup.md) | +| Gmail messages and threads | `gmail_search` | Say that email search isn't available | [gmail-search.md](reference/gmail-search.md) | +| Outlook messages and threads | `outlook_search` | Say that email search isn't available | [outlook-search.md](reference/outlook-search.md) | +| The user's own recent activity | `user_activity` | `search` with `from="me"` and a date filter | [user-activity.md](reference/user-activity.md) | +| The user's stored memories and preferences | `memory` (with `memory_schema`) | Skip personalization | [memory.md](reference/memory.md) | +| Entity and relationship queries | `knowledge_graph_query` (with `knowledge_graph_schema`) | `search` and `employee_search` | [knowledge-graph.md](reference/knowledge-graph.md) | + +The reference files load only when needed. Open the relevant one before you call a tool you haven't used recently. Each file has the parameters, the filter syntax, and known pitfalls. ## Cross-tool rules -These apply regardless of which Glean tool is active. Internalize them, don't re-derive per call. +These apply to every Glean tool. -1. **Never use `search` for people lookups.** It searches documents; it doesn't index people. Use `employee_search`. -2. **Cite every claim with a URL.** Glean returns links; surface them so the user can verify. No URL → likely fabricated. -3. **Permission-empty results are valid signals.** If a tool returns nothing, that often means the user lacks access — not that the information is missing. Don't pad with weak alternatives; report empty cleanly. -4. **Prefer recent over old.** Glean returns by relevance; for currency-sensitive questions, add a date filter or sort by recency rather than presenting stale top hits as authoritative. -5. **Vet before presenting.** Apply the criteria in [reference/vetting.md](reference/vetting.md) — relevance, freshness, authority. Better to return three vetted results than ten unfiltered ones. +1. **Don't use `search` for people.** It searches documents and doesn't index people. Use `employee_search`. +2. **Cite every claim with a URL.** Glean returns links; show them so the user can check. A claim with no URL is likely made up. +3. **Treat empty results as a signal.** An empty result often means the user lacks access, not that the information doesn't exist. Report it plainly instead of padding with weak results. +4. **Prefer recent sources.** Glean ranks by relevance. For time-sensitive questions, add a date filter or sort by recency. Say so when sources are stale or disagree. +5. **Vet before presenting.** Apply the criteria in [reference/vetting.md](reference/vetting.md): relevance, freshness, and authority. Three vetted results beat ten unfiltered ones. +6. **Use as few calls as the question needs.** Run independent calls in parallel. Stop when the question is answered. +7. **Retry a search at most twice.** Change the keywords or filters each time. If you still have nothing, say what you tried. ## Cross-cutting reference -- **[synthesis.md](reference/synthesis.md)** — patterns for combining multiple Glean tools when a single tool doesn't answer the question. -- **[vetting.md](reference/vetting.md)** — how to evaluate source quality, freshness, and authority; when to communicate confidence to the user. +- **[synthesis.md](reference/synthesis.md)**: patterns for combining Glean tools when one tool doesn't answer the question. +- **[vetting.md](reference/vetting.md)**: how to judge source quality, freshness, and authority, and when to tell the user how confident you are. ## Glean platform agents -If the user's Glean instance has platform agents enabled, those agents may surface as additional MCP tools alongside the built-in tools above. The set is org-specific and can change at any time. See [agents-as-tools.md](reference/agents-as-tools.md) for how to recognize, introspect, and invoke them. +If the user's Glean instance has platform agents enabled, they may appear as more tools in the tool list. The set is specific to the organization and can change at any time. See [agents-as-tools.md](reference/agents-as-tools.md) for how to recognize, inspect, and call them. diff --git a/shared/glean/skills/using-glean/reference/agents-as-tools.md b/shared/glean/skills/using-glean/reference/agents-as-tools.md index d07b448..b445f72 100644 --- a/shared/glean/skills/using-glean/reference/agents-as-tools.md +++ b/shared/glean/skills/using-glean/reference/agents-as-tools.md @@ -8,7 +8,7 @@ The set of agent tools is **org-specific and dynamic**: it varies by deployment Glean agent tools appear alongside the built-in ones in the active tool inventory. They typically: -- Have names that aren't on the built-in list (`search`, `chat`, `read_document`, `code_search`, `employee_search`, `gmail_search`, `outlook_search`, `meeting_lookup`, `user_activity`, `memory`, `memory_schema`, `knowledge_graph_query`, `knowledge_graph_schema`) +- Have names that aren't built-in Glean tools. The built-in set differs between deployments, so judge by the description, not by a fixed list of names - Carry org-specific names (e.g., `qbr_summarizer`, `customer_health_check`, `sales_brief`) - Have descriptions describing a workflow, not a primitive query operation diff --git a/shared/glean/skills/using-glean/reference/employee-search.md b/shared/glean/skills/using-glean/reference/employee-search.md index a65a086..dbcdd8c 100644 --- a/shared/glean/skills/using-glean/reference/employee-search.md +++ b/shared/glean/skills/using-glean/reference/employee-search.md @@ -12,7 +12,7 @@ Find people in the user's organization: names, teams, roles, reporting lines, hi **Don't** use for: - Document authorship (use `search` with `owner:` filter) -- Code authorship (use `code_search` with `owner:` filter) +- Code authorship (use `code_search` with an `owner:` filter if it is available) - "Who knows about X?" expertise — combine multiple signals; see [synthesis.md](synthesis.md) ## Parameters @@ -50,7 +50,7 @@ employee_search(query="data scientist sortby:hire_date_descending") ## Typical follow-up -For "who actually knows about X" rather than "who has the title", combine `employee_search` with `code_search` (code authorship) and `search` with `owner:` (doc authorship). See [synthesis.md](synthesis.md). +For "who actually knows about X" rather than "who has the title", combine `employee_search` with `search` and `owner:` (doc authorship), and with `code_search` (code authorship) if it is available. See [synthesis.md](synthesis.md). ## Expertise vetting (for "who knows about X" queries) diff --git a/shared/glean/skills/using-glean/reference/gmail-search.md b/shared/glean/skills/using-glean/reference/gmail-search.md index 38de62f..c8aa38f 100644 --- a/shared/glean/skills/using-glean/reference/gmail-search.md +++ b/shared/glean/skills/using-glean/reference/gmail-search.md @@ -10,8 +10,8 @@ Search the user's Gmail inbox: messages, threads, attachments, labels. Requires - "Unread important emails" — status filters **Don't** use for: -- Outlook / Microsoft 365 email — use `outlook_search` -- Calendar invites as content — use `meeting_lookup` +- Outlook / Microsoft 365 email — use `outlook_search` if it is available +- Calendar invites as content — use `meeting_lookup` if it is available - Slack DMs — use `search` with `app:slack` ## Parameters diff --git a/shared/glean/skills/using-glean/reference/meeting-lookup.md b/shared/glean/skills/using-glean/reference/meeting-lookup.md index 00cf955..cd5e632 100644 --- a/shared/glean/skills/using-glean/reference/meeting-lookup.md +++ b/shared/glean/skills/using-glean/reference/meeting-lookup.md @@ -12,7 +12,7 @@ Find calendar meetings and (optionally) extract their transcripts. Scope: the us **Don't** use for: - Documents *attached* to meetings (the linked docs are reachable via `search`) -- Email threads about meetings (use `gmail_search` / `outlook_search`) +- Email threads about meetings (use `gmail_search` / `outlook_search` if available) ## Parameters @@ -51,7 +51,7 @@ meeting_lookup(query="design review", extract_transcript=true, exhaustive=true) ## Typical follow-up -Action items from a transcript usually need follow-on `search` (the doc they reference) or `gmail_search` (the email thread). For multi-source synthesis, see [synthesis.md](synthesis.md). +Action items from a transcript usually need follow-on `search` (the doc they reference) or `gmail_search` (the email thread) if it is available. For multi-source synthesis, see [synthesis.md](synthesis.md). ## When to extract transcripts diff --git a/shared/glean/skills/using-glean/reference/memory.md b/shared/glean/skills/using-glean/reference/memory.md index ea39718..d0a0641 100644 --- a/shared/glean/skills/using-glean/reference/memory.md +++ b/shared/glean/skills/using-glean/reference/memory.md @@ -20,7 +20,7 @@ The two tools are paired: **Don't** use for: - Other people's memory (memory is calling-user only) - General company knowledge (use `search` / `chat`) -- Real-time activity (use `user_activity`) +- Real-time activity (use `user_activity` if it is available) ## Schema-then-act pattern @@ -98,4 +98,4 @@ A successful `add`/`update` returns the stored entry **including its `id`** (plu ## Typical follow-up -For status reports / weekly summaries, pair `memory` (what the user *says* they work on) with `user_activity` ([user-activity.md](user-activity.md), what they actually touched) and surface any drift. +For status reports / weekly summaries, pair `memory` (what the user *says* they work on) with `user_activity` ([user-activity.md](user-activity.md), what they actually touched) if it is available, and surface any drift. diff --git a/shared/glean/skills/using-glean/reference/outlook-search.md b/shared/glean/skills/using-glean/reference/outlook-search.md index 79df8ca..f7043fb 100644 --- a/shared/glean/skills/using-glean/reference/outlook-search.md +++ b/shared/glean/skills/using-glean/reference/outlook-search.md @@ -1,6 +1,6 @@ # `outlook_search` — Outlook / Microsoft 365 email -Search the user's Outlook mailbox: messages, threads, attachments. The Microsoft 365 counterpart to `gmail_search`. Requires the user's org to be on M365. +Search the user's Outlook mailbox: messages, threads, attachments. The Microsoft 365 counterpart to Gmail search ([gmail-search.md](gmail-search.md)). Requires the user's org to be on M365. ## When to use @@ -9,8 +9,8 @@ Search the user's Outlook mailbox: messages, threads, attachments. The Microsoft - "Find that report I got from finance" — attachment lookup **Don't** use for: -- Gmail / Google Workspace email — use `gmail_search` -- Calendar invites as content — use `meeting_lookup` +- Gmail / Google Workspace email — use `gmail_search` if it is available +- Calendar invites as content — use `meeting_lookup` if it is available ## Picking the right tool @@ -24,7 +24,7 @@ If the user has only one of `gmail_search` / `outlook_search` available in the a ## Inline filters -The filter vocabulary largely parallels `gmail_search`: +The filters mostly match the Gmail ones in [gmail-search.md](gmail-search.md): | Filter | Example | Meaning | |---|---|---| @@ -34,7 +34,7 @@ The filter vocabulary largely parallels `gmail_search`: | `has:` | `has:attachment` | Attachment presence | | `after:` / `before:` | `after:2025-01-15` | YYYY-MM-DD | -Differences from `gmail_search`: +Differences from Gmail: - No `label:` taxonomy — Outlook uses folders. The standard folders (Inbox, Sent, Deleted) are searched by default. - No Gmail-specific `is:starred` / `is:snoozed`. `is:unread` and `is:read` typically work; verify against the live tool list before relying on others. diff --git a/shared/glean/skills/using-glean/reference/read-document.md b/shared/glean/skills/using-glean/reference/read-document.md index 5cce12f..8a2c2f1 100644 --- a/shared/glean/skills/using-glean/reference/read-document.md +++ b/shared/glean/skills/using-glean/reference/read-document.md @@ -1,6 +1,6 @@ # `read_document` — fetch full content by URL -Retrieve the complete content of one or more URLs (internal Glean-indexed resources or public web pages). The natural follow-up to `search`, `code_search`, `gmail_search`, etc., when you have a URL and need the body. +Retrieve the complete content of one or more URLs (internal Glean-indexed resources or public web pages). The natural follow-up to `search`, or to any other Glean search tool you have, when you have a URL and need the body. ## When to use diff --git a/shared/glean/skills/using-glean/reference/search.md b/shared/glean/skills/using-glean/reference/search.md index db0de3f..fb4b1ee 100644 --- a/shared/glean/skills/using-glean/reference/search.md +++ b/shared/glean/skills/using-glean/reference/search.md @@ -9,7 +9,7 @@ Search documents across all the user's Glean-indexed sources (Confluence, Google - Any "where is the doc about …" question - Starting point before reading individual documents with `read_document` -**Don't** use `search` for people (use `employee_search`), code (`code_search`), email (`gmail_search` / `outlook_search`), or meetings (`meeting_lookup`). +**Don't** use `search` for people; use `employee_search`. For code, email, or meetings, use `code_search`, `gmail_search` / `outlook_search`, or `meeting_lookup` if they are in your tool list; if they are missing, `search` is the fallback. ## Parameter shape @@ -61,9 +61,9 @@ search(query="quarterly planning", updated="past_2_weeks", exhaustive=true) After `search` returns candidates, fetch full content with `read_document` (see [read-document.md](read-document.md)) for the URLs you need to quote or analyze. For multi-source synthesis, see [synthesis.md](synthesis.md). Before presenting, apply [vetting.md](vetting.md). -## Cross-tool filter style reference +## Filter style by tool, if available -Different Glean tools accept filters in different places. This matters: putting an inline filter in `search`'s `query` string won't work; putting a structured parameter in a code_search query string will silently fail. +Use only the tools in your tool list. Different Glean tools accept filters in different places. This matters: putting an inline filter in `search`'s `query` string won't work; putting a structured parameter in a code_search query string will silently fail. | Tool | Filter style | Example | |------|-------------|---------| diff --git a/shared/glean/skills/using-glean/reference/synthesis.md b/shared/glean/skills/using-glean/reference/synthesis.md index 970ddef..b0569fc 100644 --- a/shared/glean/skills/using-glean/reference/synthesis.md +++ b/shared/glean/skills/using-glean/reference/synthesis.md @@ -12,15 +12,17 @@ Some questions can't be answered by a single Glean tool. Use this file when the ## Choose tools by information type +Use only the tools in your tool list. When a tool is missing, use the fallback. + | What you need | Reach for | |---|---| | Authoritative doc (RFC, policy, spec) | `search` | | Synthesized overview across many sources | `chat` | -| Recent discussion / decisions | `meeting_lookup` | +| Recent discussion / decisions | `meeting_lookup` if available; otherwise `search` for meeting notes | | Org structure, role, reporting | `employee_search` | -| Code-level truth (what's actually built) | `code_search` | -| User's own context / personalization | `memory`, `user_activity` | -| Structured entity / relationship | `knowledge_graph_query` | +| Code-level truth (what's actually built) | `code_search` if available; otherwise `search` | +| User's own context / personalization | `memory` and `user_activity` if available; otherwise `search` with `from="me"` | +| Structured entity / relationship | `knowledge_graph_query` if available; otherwise `search` and `employee_search` | ## Patterns @@ -36,22 +38,22 @@ Some questions can't be answered by a single Glean tool. Use this file when the Title alone is weak signal. Combine: 1. `employee_search` — who has the role -2. `code_search` with `owner:` — who has been writing code on it +2. `code_search` with `owner:`, if available — who has been writing code on it 3. `search` with `owner:` — who has been authoring docs on it 4. Rank by how many signals overlap. People with multiple signals are the real experts; single-signal hits are weaker. ### "What's the status of project Y?" 1. `chat` — current-status summary -2. `meeting_lookup` — recent decisions +2. `meeting_lookup`, if available — recent decisions 3. `search` with `app:jira` or `app:notion` — tracking docs 4. Recency-weight: a 2-day-old meeting beats a 6-month-old wiki page. ### "How do we do X?" 1. `search` — process docs -2. `code_search` — what the code actually does -3. `meeting_lookup` — recent changes to the process +2. `code_search`, if available — what the code actually does +3. `meeting_lookup`, if available — recent changes to the process 4. Reconcile: doc + code + recent updates. Flag any drift. ## Reconciling conflicts diff --git a/shared/glean/skills/using-glean/reference/user-activity.md b/shared/glean/skills/using-glean/reference/user-activity.md index 2fd9732..2452fd1 100644 --- a/shared/glean/skills/using-glean/reference/user-activity.md +++ b/shared/glean/skills/using-glean/reference/user-activity.md @@ -46,4 +46,4 @@ user_activity(start_date="2025-10-01", end_date="2025-11-01") // October ## Typical follow-up -For "what did I work on?" reports, combine `user_activity` (what they touched) with `memory` ([memory.md](memory.md), what their stated active projects are) for thematic grouping. For accomplishment summaries, vet results per [vetting.md](vetting.md) — exclude trivial views, surface decisions and shipped work. +For "what did I work on?" reports, combine `user_activity` (what they touched) with `memory` ([memory.md](memory.md), what their stated active projects are) for thematic grouping, if `memory` is available. For accomplishment summaries, vet results per [vetting.md](vetting.md) — exclude trivial views, surface decisions and shipped work. From 9bb6573b5fac6703aaafcf4c010806323bcfbf03 Mon Sep 17 00:00:00 2001 From: Steve Calvert Date: Tue, 17 Nov 2026 09:20:13 -0700 Subject: [PATCH 2/2] ci: check how skills name Glean tools Add scripts/check-skill-tool-names.mjs (npm run check:skill-tools) and run it in CI with its tests (npm run test:scripts). It fails when a skill names a non-core Glean tool without saying the tool may be missing, or uses a host-specific mcp__glean prefix. --- .github/workflows/test.yml | 6 + package.json | 2 + scripts/check-skill-tool-names.mjs | 259 ++++++++++++++++++++++++ scripts/check-skill-tool-names.test.mjs | 127 ++++++++++++ 4 files changed, 394 insertions(+) create mode 100644 scripts/check-skill-tool-names.mjs create mode 100644 scripts/check-skill-tool-names.test.mjs diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 93f3795..b426d6c 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -35,6 +35,12 @@ jobs: - name: Check release version targets run: npm run check:release-version + - name: Check how skills name Glean tools + run: npm run check:skill-tools + + - name: Test repo scripts + run: npm run test:scripts + - name: Typecheck server bundle run: npm run typecheck:bundle diff --git a/package.json b/package.json index b9b6dbb..9ce956f 100644 --- a/package.json +++ b/package.json @@ -16,6 +16,8 @@ "check:no-shell": "node scripts/check-no-shell-scripts.mjs", "check:plugin-changelogs": "node scripts/check-plugin-changelogs.mjs", "check:release-version": "node scripts/check-release-version.mjs", + "check:skill-tools": "node scripts/check-skill-tool-names.mjs", + "test:scripts": "node --test \"scripts/*.test.mjs\"", "prune": "pluginpack prune", "typecheck:bundle": "tsc --noEmit -p shared/glean/mcp/tsconfig.json", "test:bundle": "vitest run --root shared/glean/mcp", diff --git a/scripts/check-skill-tool-names.mjs b/scripts/check-skill-tool-names.mjs new file mode 100644 index 0000000..fb168d8 --- /dev/null +++ b/scripts/check-skill-tool-names.mjs @@ -0,0 +1,259 @@ +#!/usr/bin/env node +// Check how skills name Glean MCP tools. +// +// The tools a Glean MCP server serves come from its `tools/list`, and that +// list differs between deployments: admins add and remove toolsets, and some +// deployments serve a tool under another name. A skill can't know the list, +// so it must not read as if it does. The rules: +// +// 1. A core tool (CORE_TOOLS) may be named anywhere. These are on nearly +// every deployment. +// 2. Any other known Glean tool (OPTIONAL_TOOLS) may be named only where the +// text says the tool might be missing, so the agent has a fallback: +// - in a paragraph, list item or table row that has a sentence naming the +// tool with an availability condition ("if `code_search` is +// available", "use `meeting_lookup` when it is in your tool list"), +// - under a heading that says "if available", +// - anywhere in a file whose opening text (before the first `##` heading) +// names the tool with a condition, or +// - in the tool's own reference file (`reference/code-search.md` for +// `code_search`, `reference/memory.md` for `memory` and `memory_schema`). +// 3. No host-specific tool prefixes such as `mcp__glean_default__search`. +// Hosts name MCP tools differently; skills use the bare tool name. +// +// Only names in backticks count as tool names. Add new Glean tool names to +// OPTIONAL_TOOLS when they ship. +import fs from "node:fs"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; +import YAML from "yaml"; + +export const CORE_TOOLS = new Set([ + "search", + "chat", + "read_document", + "employee_search", +]); + +export const OPTIONAL_TOOLS = new Set([ + "enterprise_search", + "code_search", + "meeting_lookup", + "gmail_search", + "outlook_search", + "user_activity", + "memory", + "memory_schema", + "knowledge_graph_query", + "knowledge_graph_schema", +]); + +const SCAN_ROOTS = ["shared", "overrides"]; +const SKIP_DIRS = new Set(["node_modules", "dist", ".git"]); + +// "if `x` is available", "when it is missing", "if your tool list has it", +// "where the deployment serves `x`". +const CONDITION = + /\b(if|when|where|unless)\b[^.!?]*?\b(available|missing|tool list|tools\/list|serves?|offers?)\b/i; +const CONDITION_HEADING = /\bif available\b/i; +const HOST_PREFIX = /mcp__glean/; +const INLINE_CODE = /`([^`\n]+)`/g; + +/** Tool names in backticks in `text`, in order, without duplicates. */ +function toolNames(text) { + const names = []; + for (const match of text.matchAll(INLINE_CODE)) { + const name = match[1].trim(); + if (OPTIONAL_TOOLS.has(name) && !names.includes(name)) names.push(name); + } + return names; +} + +/** Tools named in a sentence of `text` that also states an availability condition. */ +function conditionalTools(text) { + const covered = new Set(); + for (const sentence of text.split(/(?<=[.!?])\s+/)) { + if (CONDITION.test(sentence)) { + for (const name of toolNames(sentence)) covered.add(name); + } + } + return covered; +} + +/** Tools a reference file is about: `memory.md` covers `memory` and `memory_*`. */ +function ownTools(filePath) { + const match = /(?:^|[\\/])reference[\\/]([a-z0-9-]+)\.md$/.exec(filePath); + if (!match) return new Set(); + const stem = match[1].replaceAll("-", "_"); + return new Set( + [...OPTIONAL_TOOLS].filter((t) => t === stem || t.startsWith(stem + "_")), + ); +} + +/** + * Split Markdown into checkable units: paragraphs, list items and table rows, + * each with its first line number and the "if available" heading scope it + * sits in. Fenced code blocks are skipped. + */ +function units(lines, firstLine) { + const out = []; + const headings = []; // stack of { level, conditional } + let current = null; + let inFence = false; + let beforeFirstH2 = true; + + const flush = () => { + if (current) out.push(current); + current = null; + }; + const conditionalScope = () => headings.some((h) => h.conditional); + + lines.forEach((line, i) => { + const lineNo = firstLine + i; + if (/^\s*(```|~~~)/.test(line)) { + flush(); + inFence = !inFence; + return; + } + if (inFence) return; + + const heading = /^(#{1,6})\s+(.*)$/.exec(line); + if (heading) { + flush(); + const level = heading[1].length; + while (headings.length && headings.at(-1).level >= level) headings.pop(); + headings.push({ level, conditional: CONDITION_HEADING.test(heading[2]) }); + if (level === 2) beforeFirstH2 = false; + return; + } + if (line.trim() === "") { + flush(); + return; + } + + const isTableRow = /^\s*\|/.test(line); + const isListItem = /^\s*([-*+]|\d+[.)])\s+/.test(line); + if (isTableRow || isListItem || !current || current.table) flush(); + if (!current) { + current = { + line: lineNo, + text: "", + table: isTableRow, + conditional: conditionalScope(), + opening: beforeFirstH2, + }; + } + current.text += (current.text ? " " : "") + line.trim(); + }); + flush(); + return out; +} + +/** Split off YAML frontmatter. Returns the description and the body lines. */ +function splitFrontmatter(text) { + const lines = text.split(/\r?\n/); + if (lines[0] !== "---") return { description: null, body: lines, bodyStart: 1 }; + const end = lines.indexOf("---", 1); + if (end === -1) return { description: null, body: lines, bodyStart: 1 }; + let description = null; + try { + const data = YAML.parse(lines.slice(1, end).join("\n")); + if (data && typeof data.description === "string") description = data.description; + } catch { + // Malformed frontmatter is pluginpack's problem, not this check's. + } + return { description, body: lines.slice(end + 1), bodyStart: end + 2 }; +} + +/** Problems in one Markdown file, as { line, message }. */ +export function checkText(filePath, text) { + const problems = []; + text.split(/\r?\n/).forEach((line, i) => { + if (HOST_PREFIX.test(line)) { + problems.push({ + line: i + 1, + message: + "host-specific tool prefix (`mcp__glean...`). Name the tool by its bare name.", + }); + } + }); + + const own = ownTools(filePath); + const { description, body, bodyStart } = splitFrontmatter(text); + const all = units(body, bodyStart); + if (description !== null) { + all.unshift({ line: 1, text: description, conditional: false, opening: false }); + } + + // A conditional mention in the opening text covers the whole file. + const fileWide = new Set(own); + for (const unit of all) { + if (unit.opening) { + for (const name of conditionalTools(unit.text)) fileWide.add(name); + } + } + + for (const unit of all) { + if (unit.conditional) continue; + const covered = conditionalTools(unit.text); + for (const name of toolNames(unit.text)) { + if (fileWide.has(name) || covered.has(name)) continue; + problems.push({ + line: unit.line, + message: + `\`${name}\` is named without saying it may be missing. ` + + `Add a condition ("if \`${name}\` is available, ...; otherwise ...") ` + + `or move it under an "If available" heading.`, + }); + } + } + return problems.sort((a, b) => a.line - b.line); +} + +function skillFiles(dir, out, inSkills = false) { + let entries; + try { + entries = fs.readdirSync(dir, { withFileTypes: true }); + } catch { + return out; + } + for (const entry of entries) { + const abs = path.join(dir, entry.name); + if (entry.isDirectory()) { + if (!SKIP_DIRS.has(entry.name)) { + skillFiles(abs, out, inSkills || entry.name === "skills"); + } + } else if (inSkills && entry.isFile() && entry.name.endsWith(".md")) { + out.push(abs); + } + } + return out; +} + +function main() { + const repoRoot = path.resolve(fileURLToPath(import.meta.url), "..", ".."); + const files = SCAN_ROOTS.flatMap((root) => + skillFiles(path.join(repoRoot, root), []), + ).sort(); + + let count = 0; + for (const file of files) { + const rel = path.relative(repoRoot, file); + for (const p of checkText(rel, fs.readFileSync(file, "utf8"))) { + console.error(`${rel}:${p.line}: ${p.message}`); + count++; + } + } + if (count > 0) { + console.error( + `\n${count} problem(s). Glean's tools/list is the only full list of tools; ` + + `see the rules at the top of scripts/check-skill-tool-names.mjs.`, + ); + process.exit(1); + } + console.log(`Skill tool names OK (${files.length} files).`); +} + +if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) { + main(); +} diff --git a/scripts/check-skill-tool-names.test.mjs b/scripts/check-skill-tool-names.test.mjs new file mode 100644 index 0000000..df96ac2 --- /dev/null +++ b/scripts/check-skill-tool-names.test.mjs @@ -0,0 +1,127 @@ +import { test } from "node:test"; +import assert from "node:assert/strict"; +import { checkText } from "./check-skill-tool-names.mjs"; + +const SKILL = "shared/glean/skills/example/SKILL.md"; +const lines = (problems) => problems.map((p) => p.line); + +test("core tools may be named anywhere", () => { + const text = "Use `search`, then `read_document`. Ask `chat`. Find people with `employee_search`.\n"; + assert.deepEqual(checkText(SKILL, text), []); +}); + +test("an optional tool without a condition is flagged", () => { + const text = "# Skill\n\nStart with `code_search` on the best keyword.\n"; + const problems = checkText(SKILL, text); + assert.deepEqual(lines(problems), [3]); + assert.match(problems[0].message, /`code_search`/); +}); + +test("a condition in the same paragraph allows the tool", () => { + const text = [ + "# Skill", + "", + "## Steps", + "", + "If `code_search` is available, start with it.", + "", + "Use `meeting_lookup` for decisions when it is in your tool list;", + "otherwise use `search`.", + ].join("\n"); + assert.deepEqual(checkText(SKILL, text), []); +}); + +test("a condition in another paragraph does not count", () => { + const text = "## Steps\n\nIf `code_search` is available, use it.\n\nThen narrow `code_search` with filters.\n"; + assert.deepEqual(lines(checkText(SKILL, text)), [5]); +}); + +test("a condition about something else does not count", () => { + const text = [ + "## Tools", + "", + "Delegate to a subagent when subagents are available. For pitfalls of", + "`meeting_lookup`, see the reference.", + ].join("\n"); + assert.deepEqual(lines(checkText(SKILL, text)), [3]); +}); + +test("a conditional sentence covers later sentences in its paragraph", () => { + const text = "## Steps\n\nIf `code_search` is available, start there. Narrow `code_search` with filters.\n"; + assert.deepEqual(checkText(SKILL, text), []); +}); + +test("each list item and table row is checked on its own", () => { + const text = [ + "## Steps", + "", + "- Use `gmail_search` if it is available.", + "- Use `outlook_search` for mail.", + "", + "| Need | Tool |", + "|---|---|", + "| Mail | `gmail_search`, if available |", + "| Meetings | `meeting_lookup` |", + ].join("\n"); + assert.deepEqual(lines(checkText(SKILL, text)), [4, 9]); +}); + +test("an 'if available' heading covers its section only", () => { + const text = [ + "## Other tools, if available", + "", + "| Meetings | `meeting_lookup` |", + "", + "### Notes", + "", + "`user_activity` returns views and edits.", + "", + "## Rules", + "", + "Use `memory` for preferences.", + ].join("\n"); + assert.deepEqual(lines(checkText(SKILL, text)), [11]); +}); + +test("a condition in the opening text covers the whole file", () => { + const text = [ + "# Code skill", + "", + "Use this skill only when `code_search` is in your tool list.", + "", + "## Steps", + "", + "Start with `code_search`.", + "Narrow `memory` results.", + ].join("\n"); + assert.deepEqual(lines(checkText(SKILL, text)), [7]); +}); + +test("a reference file may name its own tools", () => { + const text = "# Memory\n\nCall `memory_schema`, then `memory`. Compare with `user_activity`.\n"; + const problems = checkText("shared/glean/skills/using-glean/reference/memory.md", text); + assert.equal(problems.length, 1); + assert.match(problems[0].message, /`user_activity`/); +}); + +test("fenced code blocks are ignored", () => { + const text = "## Example\n\n```\n`code_search`(\"x\")\n```\n"; + assert.deepEqual(checkText(SKILL, text), []); +}); + +test("the frontmatter description is checked", () => { + const text = "---\nname: x\ndescription: Uses `meeting_lookup` to prep.\n---\n\n# X\n"; + assert.deepEqual(lines(checkText(SKILL, text)), [1]); +}); + +test("host-specific prefixes are flagged", () => { + const text = "Call `mcp__glean_default__search`.\n"; + const problems = checkText(SKILL, text); + assert.equal(problems.length, 1); + assert.match(problems[0].message, /host-specific/); +}); + +test("names outside backticks are not tool names", () => { + const text = "## Rules\n\nPersonalize via memory and meeting lookups.\n"; + assert.deepEqual(checkText(SKILL, text), []); +});