# Glean Tools Guide > Use when Glean MCP tools are available and you need guidance on which tool to use, how to format queries, or best practices for enterprise search. This skill provides tool selection logic and query optimization for Glean integrations. Auto-triggers when mcp__glean tools are being considered. - Skill: `tomevault-io/glean-tools-guide` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/glean-tools-guide` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/glean-tools-guide/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/glean-tools-guide --- # Glean Tools Selection Guide This skill provides guidance on selecting and using Glean MCP tools effectively. ## Skills vs Agents vs Commands This plugin uses three component types: - **Skills** (like this one): Auto-triggered guidance that helps Claude select the right tools - **Agents** (e.g., `enterprise-searcher`): Autonomous workers spawned for complex multi-step tasks - **Commands** (e.g., `/glean-search:search`): User-triggered structured workflows Skills provide knowledge; agents do work; commands orchestrate workflows. ## Tool Naming Convention Glean MCP tools follow the pattern: ``` mcp__glean_[server-name]__[tool] ``` Where `[server-name]` is dynamic and configured per user (e.g., `default`, `production`, `acme`). The tool suffix is always consistent. When invoking tools, use whatever Glean server is available in your tool list. ## Available Tools Overview | Tool Suffix | Purpose | Use When | |-------------|---------|----------| | `search` | Document discovery | Finding docs, wikis, policies, specs | | `employee_search` | People lookup | Finding people, org chart, teams | | `meeting_lookup` | Meeting search | Finding meetings, transcripts, decisions | | `gmail_search` | Email search | Finding emails, attachments | | `code_search` | Code discovery | Finding internal code, commits | | `user_activity` | Activity feed | Finding your recent actions and interactions | | `read_document` | Full content | Reading complete document by URL | | `chat` | AI synthesis | Complex analysis across sources | ## Tool Selection Decision Tree ``` User question about... ├── People, "who", org chart → employee_search ├── Meetings, decisions, action items → meeting_lookup ├── Emails, attachments → gmail_search ├── Internal code, commits → code_search ├── "My activity", "what have I done", recent actions → user_activity ├── Documents, policies, specs → search ├── Need full document content → read_document (with URL) └── Complex multi-source analysis → chat ``` ## Critical Rules ### 1. Never Use Regular Search for People ``` # WRONG search "John Smith" # CORRECT employee_search "John Smith" ``` ### 2. Search → Read Workflow When users need document details: 1. First: `search` to find documents 2. Then: `read_document` with URL from results ### 3. Use Chat for Synthesis When the question requires reasoning across multiple sources: ``` chat "What are our authentication best practices based on recent RFCs and security policies?" ``` ## Query Filter Reference ### Document Search (search) - Structured Parameters The `search` tool uses **separate parameters** (not inline query filters): | Parameter | Type | Description | |-----------|------|-------------| | `query` | string | Keywords to find documents (required) | | `owner` | string | Filter by document creator (`"person name"`, `"me"`, `"myteam"`) | | `from` | string | Filter by who updated/commented/created (`"person name"`, `"me"`, `"myteam"`) | | `updated` | string | Filter by update date (`today`, `yesterday`, `past_week`, `past_2_weeks`, `past_month`, or month name) | | `after` | string | Documents created after date (`YYYY-MM-DD` format, no future dates) | | `before` | string | Documents created before date (`YYYY-MM-DD` format) | | `app` | enum | Filter by datasource (e.g., `confluence`, `github`, `gdrive`, `slack`, `jira`, `notion`) | | `type` | enum | Filter by type: `pull`, `spreadsheet`, `slides`, `email`, `direct message`, `folder` | | `channel` | string | Filter by Slack channel name | | `exhaustive` | boolean | Return all matching results (use for "all", "each", "every" requests) | | `sort_by_recency` | boolean | Sort by newest first (only when user wants "latest" or "most recent") | ### Code Search Filters (code_search) - Inline Query Syntax Code search uses **inline filters in the query string**: **Person Filters:** - `owner:"person name"` or `owner:me` - Filter by commit creator - `from:"person name"` or `from:me` - Filter by code file/commit updater **Date Filters:** - `updated:today|yesterday|past_week|past_month` - Filter by update date - `after:YYYY-MM-DD` - Commits/files changed after date - `before:YYYY-MM-DD` - Commits/files changed before date ### Employee Search Filters (employee_search) - Inline Query Syntax - `reportsto:"manager name"` - Find direct reports (NOT for finding who someone reports to) - `startafter:YYYY-MM-DD` - People who started after date - `startbefore:YYYY-MM-DD` - People who started before date - `roletype:"individual contributor"|"manager"` - Filter by role type - `sortby:hire_date_ascending|hire_date_descending|most_reports` - Sort results ### Meeting Lookup Filters (meeting_lookup) - Inline Query Syntax **Important**: meeting_lookup works best with natural language queries. Date filter syntax does NOT work reliably. **Natural language dates (recommended):** - "standup last week" - Meetings from last week - "design review past 2 weeks" - Recent meetings - "1:1 with John tomorrow" - Future meetings - "team sync yesterday" - Yesterday's meetings **Other filters that work:** - `participants:"name"` - Filter by attendees - `topic:"subject"` - Filter by meeting subject/title - `extract_transcript:"true"` - Include meeting content/transcript **Note:** Inline date filters (`after:`, `before:`) do not work reliably with meeting_lookup. Use natural language dates instead. ### Gmail Search Filters (gmail_search) - Inline Query Syntax - `from:"person"|"email@domain.com"|"me"` - Filter by sender - `to:"person"|"email@domain.com"|"me"` - Filter by recipient - `subject:"text"` - Filter by subject line - `has:attachment|document|spreadsheet|presentation` - Filter by attachment type - `is:important|starred|read|unread|snoozed` - Filter by email status - `label:INBOX|SENT|TRASH|DRAFT|SPAM` - Filter by folder/label - `after:YYYY-MM-DD` / `before:YYYY-MM-DD` - Date range ### User Activity Parameters (user_activity) The `user_activity` tool uses date range parameters (not query filters): - `start_date` - Start date in YYYY-MM-DD format (inclusive, required) - `end_date` - End date in YYYY-MM-DD format (exclusive, required) Use for: standup notes, weekly summaries, 1:1 prep, finding documents you touched but forgot. ## Example Tool Calls These examples show the correct syntax for each tool type. ### Search (Structured Parameters) Pass filters as separate parameters, not in the query string: ``` search(query="authentication RFC", app="confluence", updated="past_month") search(query="API design", owner="me", sort_by_recency=true) search(query="onboarding guide", from="John Smith", after="2024-01-01") ``` ### Code Search (Inline Filters) Include filters directly in the query string: ``` code_search("authentication handler owner:me updated:past_week") code_search("payment processor after:2024-06-01 before:2024-12-01") code_search("API endpoint from:\"Jane Doe\"") ``` ### Employee Search (Inline Filters) Include filters directly in the query string: ``` employee_search("engineering manager reportsto:\"VP Engineering\"") employee_search("backend engineer startafter:2024-01-01") employee_search("data scientist roletype:\"individual contributor\"") ``` ### Meeting Lookup (Natural Language + Inline Filters) Use natural language for dates; inline filters for other criteria: ``` meeting_lookup("my meetings today extract_transcript:\"true\"") meeting_lookup("standup last week participants:\"John Smith\"") meeting_lookup("design review past 2 weeks topic:\"architecture\"") ``` Note: Date filters (`after:`, `before:`) are documented but don't work reliably in practice. Use natural language dates instead ("today", "yesterday", "last week", "past 2 weeks"). ### User Activity (Structured Parameters) Pass date range as separate parameters: ``` user_activity(start_date="2024-01-08", end_date="2024-01-15") ``` ## Filter Best Practices **Structured vs Inline Filters:** - `search` uses **structured parameters** - pass filters as separate tool arguments - `code_search`, `employee_search`, `gmail_search`, `meeting_lookup` use **inline filters** in the query string **When to Use Date Filters:** - Use `updated:` for relative timeframes ("last week", "past month") - Use `after:`/`before:` for date ranges ("between Jan and March", "since 2024") - Avoid date filters for "latest" or "recent" without specific timeframe - For `meeting_lookup`, prefer natural language dates over inline filters **Person Filter Guidelines:** - Use quotes for multi-word names: `from:"John Smith"` - Use `owner:` for document creators, `from:` for broader involvement - Use `me` when user refers to themselves **Search Strategy:** - Start broad, then narrow with filters if too many results - For `search`: add filter parameters to narrow results - For other tools: add inline filters to the query string - Use the `exhaustive` parameter on `search` for exhaustive results ("all", "each", "every") **Common Pitfalls:** - Don't use `after:` with future dates - For `search`, pass `channel` and `app` as separate parameters - Quote multi-word filter values in inline syntax: `from:"John Smith"` ## Best Practices 1. **Cite sources**: Always include URLs so users can verify 2. **Start broad, then narrow**: Use filters to refine if too many results 3. **Combine signals**: For expertise, check code + docs + meetings 4. **Respect permissions**: Results are filtered by user access 5. **Note when empty**: No results is useful information ## Related Commands Point users to structured workflows when appropriate: - `/glean-search:search` - Quick search - `/glean-people:find-expert` - Expertise discovery - `/glean-meetings:catch-up` - Return from time off - `/glean-meetings:meeting-prep` - Meeting preparation - `/glean-people:stakeholders` - Stakeholder mapping - `/glean-docs:onboarding` - Team onboarding - `/glean-docs:verify-rfc` - Spec verification --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/gleanwork) — claim your Tome and manage your conversions.