git:20260626.d9fb956 to git:20260705.5a5efb9

- user-invocable: true

- # Google Workspace Extension - Behavioral Guide

- This guide provides behavioral instructions for effectively using the Google Workspace Extension tools. For detailed parameter documentation, refer to the tool descriptions in the extension itself.

- ## 🧭 Tool Selection (read this first)

- Reach for the lightest tool that does the job. For every service, walk the

- priority order below top to bottom: try the `gws` CLI first, fall through to MCP

- only on tool absence OR auth failure, and use BYOB browser automation only as a

- last resort when nothing above can do the task at all. A present-but-

- human OAuth step) must hand off to the next tier — do not stall on it.

- | Docs | `gws docs` | (no MCP) | BYOB |

- | Sheets | `gws sheets` | (no MCP) | BYOB |

- | Slides | `gws slides` | (no MCP) | BYOB |

- | People | `gws people` | (no MCP) | BYOB |

- | Chat | `gws chat` | (no MCP) | BYOB |

- | Forms | `gws forms` | (no MCP) | BYOB |

- | Keep | `gws keep` | (no MCP) | BYOB |

-

- For reading/sending mail specifically, prefer the `/email` skill's ladder, which

- starts at `gws gmail` → Gmail MCP → BYOB. If the repo context file declares a

- faster project-local mail CLI, the `/email` skill puts it ahead of `gws` as Tier 1;

- otherwise the generic `gws gmail` tier is the top of the mail ladder.

-

- ## 🎯 Core Principles

-

- ### 1. User Context First

- **Always establish user context at the beginning of interactions:**

- - Use `gws people people get --params '{"resourceName": "people/me"}'` to understand who the user is

- - Establish the user's local timezone (e.g. `gws calendar settings get --params '{"setting": "timezone"}'`)

- - Apply this context throughout all interactions

- - All time-based operations should respect the user's timezone

-

- ### 2. Safety and Transparency

- **Never execute write operations without explicit confirmation:**

- - Preview all changes before executing

- - Show complete details in a readable format

- - Wait for clear user approval

- - Give users the opportunity to review and cancel

-

- ### 3. Smart Tool Usage

- **Choose the right approach for each task:**

- - Tools automatically handle URL-to-ID conversion - don't extract IDs manually

- - Batch related operations when possible

- - Use pagination for large result sets

- - Apply appropriate formats based on the use case

-

- ## 📋 Output Formatting Standards

-

- ### Lists and Search Results

- Always format multiple items as **numbered lists** for better readability:

-

- ✅ **Correct:**

- ```

- Found 3 documents:

- 1. Budget Report 2024

- 2. Q3 Sales Presentation

- 3. Team Meeting Notes

- ```

-

- ❌ **Incorrect:**

- ```

- Found 3 documents:

- - Budget Report 2024

- - Q3 Sales Presentation

- - Team Meeting Notes

- ```

-

- ### Write Operation Previews

- Before any write operation, show a clear preview:

-

- ```

- I'll create this calendar event:

-

- Title: Team Standup

- Date: January 15, 2025

- Time: 10:00 AM - 10:30 AM (EST)

- Attendees: team@example.com

-

- Should I create this event?

- ```

-

- ## 🔄 Multi-Tool Workflows

-

- ### Creating and Organizing Documents

- When creating documents in specific folders:

- 1. Create the document first

- 2. Then move it to the folder (if specified)

- 3. Confirm successful completion

-

- ### Calendar Scheduling Workflow

- 1. Establish the user's timezone (see User Context First)

- 2. Check availability with `gws calendar events list` (or `mcp__claude_ai_Google_Calendar__list_events`)

- 3. Create event with proper timezone handling

- 4. Always show times in user's local timezone

-

- ### Email Search and Response

- 1. Search with `gws gmail users messages list` using Gmail query syntax (or `mcp__claude_ai_Gmail__search_threads`)

- 2. Get full content with `gws gmail users messages get` if needed (or `mcp__claude_ai_Gmail__get_thread`)

- 3. Preview any reply before sending

- 4. Use threading context when responding

-

- ### Adding/Removing Labels from Emails

- 1. For system labels, including "INBOX", "SPAM", "TRASH", "UNREAD", "STARRED", "IMPORTANT", the ID is the name itself.

- 2. For user created custom labels, retrieve label ID with `gws gmail users labels list` (or `mcp__claude_ai_Gmail__list_labels`).

- 3. Use `gws gmail users messages modify` to add or remove labels from emails with a single call using label IDs (or `mcp__claude_ai_Gmail__label_message` / `mcp__claude_ai_Gmail__unlabel_message`).

-

- ### Event Deletion

- When deleting a calendar event (`gws calendar events delete`, or `mcp__claude_ai_Google_Calendar__delete_event`):

- - This is a destructive action that permanently removes the event.

- - For organizers, this cancels the event for all attendees.

- - For attendees, this only removes it from their own calendar.

- - Always confirm with the user before executing a deletion.

-

- ## 📅 Calendar Best Practices

-

- ### Understanding "Next Meeting"

- When asked about "next meeting" or "today's schedule":

- 1. **Fetch the full day's context** - Use start of day (00:00:00) to end of day (23:59:59)

- 2. **Filter by response status** - Only show meetings where the user has:

- - Accepted the invitation

- - Not yet responded (needs to decide)

- - DO NOT show declined meetings unless explicitly requested

- 3. **Compare with current time** - Identify meetings relative to now

- 4. **Handle edge cases**:

- - If a meeting is in progress, mention it first

- - "Next" means the first meeting after current time

- - Keep full day context for follow-up questions

-

- ### Meeting Response Filtering

- - **Default behavior**: Show only accepted and pending meetings

- - **Declined meetings**: Exclude unless user asks "show me all meetings" or "including declined"

- - **Use `attendeeResponseStatus`** parameter to filter appropriately

- - This respects the user's time by not cluttering their schedule with irrelevant meetings

-

- ### Timezone Management

- - Always display times in the user's timezone

- - Convert all times appropriately before display

- - Include timezone abbreviation (EST, PST, etc.) for clarity

-

- ## 📧 Gmail & Chat Guidelines

-

- ### Search Strategies

- - Use Gmail search syntax: `from:email@example.com is:unread`

- - Combine multiple criteria for precise results

- - Include SPAM/TRASH only when explicitly needed

-

- ### Threading and Context

- - Maintain conversation context in replies

- - Reference previous messages when relevant

- - Use appropriate reply vs. new message based on context

-

- ### Downloading Attachments

- 1. **Find Attachment ID**: Use `gws gmail users messages get` with `format=full` to retrieve message details, including `attachments` metadata (IDs and filenames).

- 2. **Download**: Use `gws gmail users messages attachments get` with the specific `messageId` and `attachmentId`.

- 3. **Absolute Paths**: Always provide an **absolute path** for the output argument (e.g., `/Users/username/Downloads/file.pdf`). Relative paths will be rejected for security.

-

- ### Composing on Behalf of the User

-

- When drafting or replying to email on the user's behalf, apply these three constraints without exception:

-

- - **Async CTAs only** — Never offer calls, meetings, voice/video contact, or any form of synchronous communication. The agent cannot participate in real-time conversations. Use async alternatives instead: "happy to share more over email", "feel free to reply with questions", or leave the closing open with no CTA. Phrases like "let's jump on a call", "schedule a meeting", or "give us a ring" are prohibited.

- - **Draft-first rule** — All outbound composition must produce a draft (`gws gmail users drafts create`, or `mcp__claude_ai_Gmail__create_draft`). Never call a send tool without an explicit user instruction to send. This is stricter than the general write-operation safety rule: even if the user says "write a reply", the result is a draft that the user reviews and sends manually.

- - **Honest representation** — When composing outreach about the user's product or service, represent it accurately. If the product or operation is automated or AI-assisted, say so rather than implying a human-run team. Do not overclaim capabilities, team size, or operational structure. Inaccurate representation damages trust and creates expectations that cannot be met.

-

- ## 📄 Docs, Sheets, and Slides

-

- ### Format Selection (Sheets)

- Choose output format based on use case:

- - **text**: Human-readable, good for quick review

- - **csv**: Data export, analysis in other tools

- - **json**: Programmatic processing, structured data

-

- ### Content Handling

- - Docs/Sheets/Slides tools accept URLs directly - no ID extraction needed

- - Use markdown for initial document creation when appropriate

- - Preserve formatting when reading/modifying content

-

- ## 🚫 Common Pitfalls to Avoid

-

- ### Don't Do This:

- - ❌ Manually extract IDs from URLs when tools accept URLs directly

- - ❌ Assume timezone without checking

- - ❌ Execute writes without preview and confirmation

- - ❌ Create files unless explicitly requested

- - ❌ Duplicate parameter documentation from tool descriptions

- - ❌ Use relative paths for file downloads (e.g., `downloads/file.txt`)

-

- ### Do This Instead:

- - ✅ Pass URLs directly to tools that accept them

- - ✅ Get user timezone at session start

- - ✅ Preview all changes and wait for approval

- - ✅ Only create what's requested

- - ✅ Focus on behavioral guidance and best practices

- - ✅ Always use **absolute paths** for file downloads (e.g., `/Users/me/Downloads/file.txt`)

-

- ## 🔍 Error Handling Patterns

-

- ### Authentication Errors

- - If any tool returns `{"error":"invalid_request"}` or a `gws` call fails with an auth error, it likely indicates an expired or invalid session.

- - **Action:** For `gws`, re-run the one-time human OAuth step (`gws auth setup` / `gws auth login`); for MCP, reset credentials and force a re-login. If the tool stays unauthenticated, **fall through to the next tier** in the Tool Selection ladder rather than stalling.

- - Inform the user that you are resetting authentication due to an error.

-

- ### Graceful Degradation

- - If a folder doesn't exist, offer to create it

- - If search returns no results, suggest alternatives

- - If permissions are insufficient, explain clearly

- ### Validation Before Action

- - Verify file/folder existence before moving

- - Check calendar availability before scheduling

- - Validate email addresses before sending

- ## ⚡ Performance Optimization

- ### Batch Operations

- - Group related API calls when possible

- - Use field masks to request only needed data

- - Implement pagination for large datasets

- ### Caching Strategy

- - Reuse user context throughout session

- - Cache frequently accessed metadata

- - Minimize redundant API calls

- ## 📝 Session Management

- ### Beginning of Session

- 1. Get user profile (see User Context First — `gws people people get` with `resourceName=people/me`)

- 2. Establish the user's timezone

- 3. Establish any relevant context

- ### During Interaction

- - Maintain context awareness

- - Apply user preferences consistently

- - Handle follow-up questions efficiently

- ### End of Session

- - Confirm all requested tasks completed

- - Provide summary if multiple operations performed

- - Ensure no pending confirmations

- ## 🎨 Service-Specific Nuances

- ### Google Docs

- - Support for markdown content creation

- - Automatic HTML conversion from markdown

- - Position-based text insertion (index 1 for beginning)

- ### Google Sheets

- - Multiple output formats available

- - Range-based operations with A1 notation

- - Metadata includes sheet structure information

- ### Google Calendar

- - Event creation requires both start and end times

- - Support for attendee management

- - Response status filtering available

- ### Gmail

- - Full threading support

- - Label-based organization

- - Draft creation and management

- ### Google Chat

- - Space vs. DM distinction

- - Thread-aware messaging

- - Unread message filtering

- Remember: This guide focuses on **how to think** about using these tools effectively. For specific parameter details, refer to the tool descriptions themselves.