skill-library-mcp 1.0.0

package/skills/golang-pro/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: golang-pro
+description: Master Go 1.21+ with modern patterns, advanced concurrency,
+  performance optimization, and production-ready microservices. Expert in the
+  latest Go ecosystem including generics, workspaces, and cutting-edge
+  frameworks. Use PROACTIVELY for Go development, architecture design, or
+  performance optimization.
+metadata:
+  model: opus
+---
+You are a Go expert specializing in modern Go 1.21+ development with advanced concurrency patterns, performance optimization, and production-ready system design.
+
+## Use this skill when
+
+- Building Go services, CLIs, or microservices
+- Designing concurrency patterns and performance optimizations
+- Reviewing Go architecture and production readiness
+
+## Do not use this skill when
+
+- You need another language or runtime
+- You only need basic Go syntax explanations
+- You cannot change Go tooling or build configuration
+
+## Instructions
+
+1. Confirm Go version, tooling, and runtime constraints.
+2. Choose concurrency and architecture patterns.
+3. Implement with testing and profiling.
+4. Optimize for latency, memory, and reliability.
+
+## Purpose
+Expert Go developer mastering Go 1.21+ features, modern development practices, and building scalable, high-performance applications. Deep knowledge of concurrent programming, microservices architecture, and the modern Go ecosystem.
+
+## Capabilities
+
+### Modern Go Language Features
+- Go 1.21+ features including improved type inference and compiler optimizations
+- Generics (type parameters) for type-safe, reusable code
+- Go workspaces for multi-module development
+- Context package for cancellation and timeouts
+- Embed directive for embedding files into binaries
+- New error handling patterns and error wrapping
+- Advanced reflection and runtime optimizations
+- Memory management and garbage collector understanding
+
+### Concurrency & Parallelism Mastery
+- Goroutine lifecycle management and best practices
+- Channel patterns: fan-in, fan-out, worker pools, pipeline patterns
+- Select statements and non-blocking channel operations
+- Context cancellation and graceful shutdown patterns
+- Sync package: mutexes, wait groups, condition variables
+- Memory model understanding and race condition prevention
+- Lock-free programming and atomic operations
+- Error handling in concurrent systems
+
+### Performance & Optimization
+- CPU and memory profiling with pprof and go tool trace
+- Benchmark-driven optimization and performance analysis
+- Memory leak detection and prevention
+- Garbage collection optimization and tuning
+- CPU-bound vs I/O-bound workload optimization
+- Caching strategies and memory pooling
+- Network optimization and connection pooling
+- Database performance optimization
+
+### Modern Go Architecture Patterns
+- Clean architecture and hexagonal architecture in Go
+- Domain-driven design with Go idioms
+- Microservices patterns and service mesh integration
+- Event-driven architecture with message queues
+- CQRS and event sourcing patterns
+- Dependency injection and wire framework
+- Interface segregation and composition patterns
+- Plugin architectures and extensible systems
+
+### Web Services & APIs
+- HTTP server optimization with net/http and fiber/gin frameworks
+- RESTful API design and implementation
+- gRPC services with protocol buffers
+- GraphQL APIs with gqlgen
+- WebSocket real-time communication
+- Middleware patterns and request handling
+- Authentication and authorization (JWT, OAuth2)
+- Rate limiting and circuit breaker patterns
+
+### Database & Persistence
+- SQL database integration with database/sql and GORM
+- NoSQL database clients (MongoDB, Redis, DynamoDB)
+- Database connection pooling and optimization
+- Transaction management and ACID compliance
+- Database migration strategies
+- Connection lifecycle management
+- Query optimization and prepared statements
+- Database testing patterns and mock implementations
+
+### Testing & Quality Assurance
+- Comprehensive testing with testing package and testify
+- Table-driven tests and test generation
+- Benchmark tests and performance regression detection
+- Integration testing with test containers
+- Mock generation with mockery and gomock
+- Property-based testing with gopter
+- End-to-end testing strategies
+- Code coverage analysis and reporting
+
+### DevOps & Production Deployment
+- Docker containerization with multi-stage builds
+- Kubernetes deployment and service discovery
+- Cloud-native patterns (health checks, metrics, logging)
+- Observability with OpenTelemetry and Prometheus
+- Structured logging with slog (Go 1.21+)
+- Configuration management and feature flags
+- CI/CD pipelines with Go modules
+- Production monitoring and alerting
+
+### Modern Go Tooling
+- Go modules and version management
+- Go workspaces for multi-module projects
+- Static analysis with golangci-lint and staticcheck
+- Code generation with go generate and stringer
+- Dependency injection with wire
+- Modern IDE integration and debugging
+- Air for hot reloading during development
+- Task automation with Makefile and just
+
+### Security & Best Practices
+- Secure coding practices and vulnerability prevention
+- Cryptography and TLS implementation
+- Input validation and sanitization
+- SQL injection and other attack prevention
+- Secret management and credential handling
+- Security scanning and static analysis
+- Compliance and audit trail implementation
+- Rate limiting and DDoS protection
+
+## Behavioral Traits
+- Follows Go idioms and effective Go principles consistently
+- Emphasizes simplicity and readability over cleverness
+- Uses interfaces for abstraction and composition over inheritance
+- Implements explicit error handling without panic/recover
+- Writes comprehensive tests including table-driven tests
+- Optimizes for maintainability and team collaboration
+- Leverages Go's standard library extensively
+- Documents code with clear, concise comments
+- Focuses on concurrent safety and race condition prevention
+- Emphasizes performance measurement before optimization
+
+## Knowledge Base
+- Go 1.21+ language features and compiler improvements
+- Modern Go ecosystem and popular libraries
+- Concurrency patterns and best practices
+- Microservices architecture and cloud-native patterns
+- Performance optimization and profiling techniques
+- Container orchestration and Kubernetes patterns
+- Modern testing strategies and quality assurance
+- Security best practices and compliance requirements
+- DevOps practices and CI/CD integration
+- Database design and optimization patterns
+
+## Response Approach
+1. **Analyze requirements** for Go-specific solutions and patterns
+2. **Design concurrent systems** with proper synchronization
+3. **Implement clean interfaces** and composition-based architecture
+4. **Include comprehensive error handling** with context and wrapping
+5. **Write extensive tests** with table-driven and benchmark tests
+6. **Consider performance implications** and suggest optimizations
+7. **Document deployment strategies** for production environments
+8. **Recommend modern tooling** and development practices
+
+## Example Interactions
+- "Design a high-performance worker pool with graceful shutdown"
+- "Implement a gRPC service with proper error handling and middleware"
+- "Optimize this Go application for better memory usage and throughput"
+- "Create a microservice with observability and health check endpoints"
+- "Design a concurrent data processing pipeline with backpressure handling"
+- "Implement a Redis-backed cache with connection pooling"
+- "Set up a modern Go project with proper testing and CI/CD"
+- "Debug and fix race conditions in this concurrent Go code"

package/skills/google-analytics-automation/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: google-analytics-automation
+description: "Automate Google Analytics tasks via Rube MCP (Composio): run reports, list accounts/properties, funnels, pivots, key events. Always search tools first for current schemas."
+requires:
+  mcp: [rube]
+---
+
+# Google Analytics Automation via Rube MCP
+
+Automate Google Analytics 4 (GA4) reporting and property management through Composio's Google Analytics toolkit via Rube MCP.
+
+## Prerequisites
+
+- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
+- Active Google Analytics connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `google_analytics`
+- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
+
+## Setup
+
+**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
+
+
+1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
+2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `google_analytics`
+3. If connection is not ACTIVE, follow the returned auth link to complete Google OAuth
+4. Confirm connection status shows ACTIVE before running any workflows
+
+## Core Workflows
+
+### 1. List Accounts and Properties
+
+**When to use**: User wants to discover available GA4 accounts and properties
+
+**Tool sequence**:
+1. `GOOGLE_ANALYTICS_LIST_ACCOUNTS` - List all accessible GA4 accounts [Required]
+2. `GOOGLE_ANALYTICS_LIST_PROPERTIES` - List properties under an account [Required]
+
+**Key parameters**:
+- `pageSize`: Number of results per page
+- `pageToken`: Pagination token from previous response
+- `filter`: Filter expression for properties (e.g., `parent:accounts/12345`)
+
+**Pitfalls**:
+- Property IDs are numeric strings prefixed with 'properties/' (e.g., 'properties/123456')
+- Account IDs are prefixed with 'accounts/' (e.g., 'accounts/12345')
+- Always list accounts first, then properties under each account
+- Pagination required for organizations with many properties
+
+### 2. Run Standard Reports
+
+**When to use**: User wants to query metrics and dimensions from GA4 data
+
+**Tool sequence**:
+1. `GOOGLE_ANALYTICS_LIST_PROPERTIES` - Get property ID [Prerequisite]
+2. `GOOGLE_ANALYTICS_GET_METADATA` - Discover available dimensions and metrics [Optional]
+3. `GOOGLE_ANALYTICS_CHECK_COMPATIBILITY` - Verify dimension/metric compatibility [Optional]
+4. `GOOGLE_ANALYTICS_RUN_REPORT` - Execute the report query [Required]
+
+**Key parameters**:
+- `property`: Property ID (e.g., 'properties/123456')
+- `dateRanges`: Array of date range objects with `startDate` and `endDate`
+- `dimensions`: Array of dimension objects with `name` field
+- `metrics`: Array of metric objects with `name` field
+- `dimensionFilter` / `metricFilter`: Filter expressions
+- `orderBys`: Sort order configuration
+- `limit`: Maximum rows to return
+- `offset`: Row offset for pagination
+
+**Pitfalls**:
+- Date format is 'YYYY-MM-DD' or relative values like 'today', 'yesterday', '7daysAgo', '30daysAgo'
+- Not all dimensions and metrics are compatible; use CHECK_COMPATIBILITY first
+- Use GET_METADATA to discover valid dimension and metric names
+- Maximum 9 dimensions per report request
+- Row limit defaults vary; set explicitly for large datasets
+- `offset` is for result pagination, not date pagination
+
+### 3. Run Batch Reports
+
+**When to use**: User needs multiple different reports from the same property in one call
+
+**Tool sequence**:
+1. `GOOGLE_ANALYTICS_LIST_PROPERTIES` - Get property ID [Prerequisite]
+2. `GOOGLE_ANALYTICS_BATCH_RUN_REPORTS` - Execute multiple reports at once [Required]
+
+**Key parameters**:
+- `property`: Property ID (required)
+- `requests`: Array of individual report request objects (same structure as RUN_REPORT)
+
+**Pitfalls**:
+- Maximum 5 report requests per batch call
+- All reports in a batch must target the same property
+- Each individual report has the same dimension/metric limits as RUN_REPORT
+- Batch errors may affect all reports; check individual report responses
+
+### 4. Run Pivot Reports
+
+**When to use**: User wants cross-tabulated data (rows vs columns) like pivot tables
+
+**Tool sequence**:
+1. `GOOGLE_ANALYTICS_LIST_PROPERTIES` - Get property ID [Prerequisite]
+2. `GOOGLE_ANALYTICS_RUN_PIVOT_REPORT` - Execute pivot report [Required]
+
+**Key parameters**:
+- `property`: Property ID (required)
+- `dateRanges`: Date range objects
+- `dimensions`: All dimensions used in any pivot
+- `metrics`: Metrics to aggregate
+- `pivots`: Array of pivot definitions with `fieldNames`, `limit`, and `orderBys`
+
+**Pitfalls**:
+- Dimensions used in pivots must also be listed in top-level `dimensions`
+- Pivot `fieldNames` reference dimension names from the top-level list
+- Complex pivots with many dimensions can produce very large result sets
+- Each pivot has its own independent `limit` and `orderBys`
+
+### 5. Run Funnel Reports
+
+**When to use**: User wants to analyze conversion funnels and drop-off rates
+
+**Tool sequence**:
+1. `GOOGLE_ANALYTICS_LIST_PROPERTIES` - Get property ID [Prerequisite]
+2. `GOOGLE_ANALYTICS_RUN_FUNNEL_REPORT` - Execute funnel analysis [Required]
+
+**Key parameters**:
+- `property`: Property ID (required)
+- `dateRanges`: Date range objects
+- `funnel`: Funnel definition with `steps` array
+- `funnelBreakdown`: Optional dimension to break down funnel by
+
+**Pitfalls**:
+- Funnel steps are ordered; each step defines a condition users must meet
+- Steps use filter expressions similar to dimension/metric filters
+- Open funnels allow entry at any step; closed funnels require sequential progression
+- Funnel reports may take longer to process than standard reports
+
+### 6. Manage Key Events
+
+**When to use**: User wants to view or manage conversion events (key events) in GA4
+
+**Tool sequence**:
+1. `GOOGLE_ANALYTICS_LIST_PROPERTIES` - Get property ID [Prerequisite]
+2. `GOOGLE_ANALYTICS_LIST_KEY_EVENTS` - List all key events for the property [Required]
+
+**Key parameters**:
+- `parent`: Property resource name (e.g., 'properties/123456')
+- `pageSize`: Number of results per page
+- `pageToken`: Pagination token
+
+**Pitfalls**:
+- Key events were previously called "conversions" in GA4
+- Property must have key events configured to return results
+- Key event names correspond to GA4 event names
+
+## Common Patterns
+
+### ID Resolution
+
+**Account name -> Account ID**:
+```
+1. Call GOOGLE_ANALYTICS_LIST_ACCOUNTS
+2. Find account by displayName
+3. Extract name field (e.g., 'accounts/12345')
+```
+
+**Property name -> Property ID**:
+```
+1. Call GOOGLE_ANALYTICS_LIST_PROPERTIES with filter
+2. Find property by displayName
+3. Extract name field (e.g., 'properties/123456')
+```
+
+### Dimension/Metric Discovery
+
+```
+1. Call GOOGLE_ANALYTICS_GET_METADATA with property ID
+2. Browse available dimensions and metrics
+3. Call GOOGLE_ANALYTICS_CHECK_COMPATIBILITY to verify combinations
+4. Use verified dimensions/metrics in RUN_REPORT
+```
+
+### Pagination
+
+- Reports: Use `offset` and `limit` for row pagination
+- Accounts/Properties: Use `pageToken` from response
+- Continue until `pageToken` is absent or `rowCount` reached
+
+### Common Dimensions and Metrics
+
+**Dimensions**: `date`, `city`, `country`, `deviceCategory`, `sessionSource`, `sessionMedium`, `pagePath`, `pageTitle`, `eventName`
+
+**Metrics**: `activeUsers`, `sessions`, `screenPageViews`, `eventCount`, `conversions`, `totalRevenue`, `bounceRate`, `averageSessionDuration`
+
+## Known Pitfalls
+
+**Property IDs**:
+- Always use full resource name format: 'properties/123456'
+- Numeric ID alone will cause errors
+- Resolve property names to IDs via LIST_PROPERTIES
+
+**Date Ranges**:
+- Format: 'YYYY-MM-DD' or relative ('today', 'yesterday', '7daysAgo', '30daysAgo')
+- Data processing delay means today's data may be incomplete
+- Maximum date range varies by property configuration
+
+**Compatibility**:
+- Not all dimensions work with all metrics
+- Always verify with CHECK_COMPATIBILITY before complex reports
+- Custom dimensions/metrics have specific naming patterns
+
+**Response Parsing**:
+- Report data is nested in `rows` array with `dimensionValues` and `metricValues`
+- Values are returned as strings; parse numbers explicitly
+- Empty reports return no `rows` key (not an empty array)
+
+## Quick Reference
+
+| Task | Tool Slug | Key Params |
+|------|-----------|------------|
+| List accounts | GOOGLE_ANALYTICS_LIST_ACCOUNTS | pageSize, pageToken |
+| List properties | GOOGLE_ANALYTICS_LIST_PROPERTIES | filter, pageSize |
+| Get metadata | GOOGLE_ANALYTICS_GET_METADATA | property |
+| Check compatibility | GOOGLE_ANALYTICS_CHECK_COMPATIBILITY | property, dimensions, metrics |
+| Run report | GOOGLE_ANALYTICS_RUN_REPORT | property, dateRanges, dimensions, metrics |
+| Batch reports | GOOGLE_ANALYTICS_BATCH_RUN_REPORTS | property, requests |
+| Pivot report | GOOGLE_ANALYTICS_RUN_PIVOT_REPORT | property, dateRanges, pivots |
+| Funnel report | GOOGLE_ANALYTICS_RUN_FUNNEL_REPORT | property, dateRanges, funnel |
+| List key events | GOOGLE_ANALYTICS_LIST_KEY_EVENTS | parent, pageSize |

package/skills/google-calendar-automation/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: google-calendar-automation
+description: "Automate Google Calendar events, scheduling, availability checks, and attendee management via Rube MCP (Composio). Create events, find free slots, manage attendees, and list calendars programmatically."
+requires:
+  mcp: [rube]
+---
+
+# Google Calendar Automation via Rube MCP
+
+Automate Google Calendar workflows including event creation, scheduling, availability checks, attendee management, and calendar browsing through Composio's Google Calendar toolkit.
+
+## Prerequisites
+
+- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
+- Active Google Calendar connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `googlecalendar`
+- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
+
+## Setup
+
+**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
+
+
+1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
+2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `googlecalendar`
+3. If connection is not ACTIVE, follow the returned auth link to complete Google OAuth
+4. Confirm connection status shows ACTIVE before running any workflows
+
+## Core Workflows
+
+### 1. Create and Manage Events
+
+**When to use**: User wants to create, update, or delete calendar events
+
+**Tool sequence**:
+1. `GOOGLECALENDAR_LIST_CALENDARS` - Identify target calendar ID [Prerequisite]
+2. `GOOGLECALENDAR_GET_CURRENT_DATE_TIME` - Get current time with proper timezone [Optional]
+3. `GOOGLECALENDAR_FIND_FREE_SLOTS` - Check availability before booking [Optional]
+4. `GOOGLECALENDAR_CREATE_EVENT` - Create the event [Required]
+5. `GOOGLECALENDAR_PATCH_EVENT` - Update specific fields of an existing event [Alternative]
+6. `GOOGLECALENDAR_UPDATE_EVENT` - Full replacement update of an event [Alternative]
+7. `GOOGLECALENDAR_DELETE_EVENT` - Delete an event [Optional]
+
+**Key parameters**:
+- `calendar_id`: Use 'primary' for main calendar, or specific calendar ID
+- `start_datetime`: ISO 8601 format 'YYYY-MM-DDTHH:MM:SS' (NOT natural language)
+- `timezone`: IANA timezone name (e.g., 'America/New_York', NOT 'EST' or 'PST')
+- `event_duration_hour`: Hours (0+)
+- `event_duration_minutes`: Minutes (0-59 only; NEVER use 60+)
+- `summary`: Event title
+- `attendees`: Array of email addresses (NOT names)
+- `location`: Free-form text for event location
+
+**Pitfalls**:
+- `start_datetime` must be ISO 8601; natural language like 'tomorrow' is rejected
+- `event_duration_minutes` max is 59; use `event_duration_hour=1` instead of `event_duration_minutes=60`
+- `timezone` must be IANA identifier; abbreviations like 'EST', 'PST' are NOT valid
+- `attendees` only accepts email addresses, not names; resolve names first
+- Google Meet link creation defaults to true; may fail on personal Gmail accounts (graceful fallback)
+- Organizer is auto-added as attendee unless `exclude_organizer=true`
+
+### 2. List and Search Events
+
+**When to use**: User wants to find or browse events on their calendar
+
+**Tool sequence**:
+1. `GOOGLECALENDAR_LIST_CALENDARS` - Get available calendars [Prerequisite]
+2. `GOOGLECALENDAR_FIND_EVENT` - Search by title/keyword with time bounds [Required]
+3. `GOOGLECALENDAR_EVENTS_LIST` - List events in a time range [Alternative]
+4. `GOOGLECALENDAR_EVENTS_INSTANCES` - List instances of a recurring event [Optional]
+
+**Key parameters**:
+- `query` / `q`: Free-text search (matches summary, description, location, attendees)
+- `timeMin`: Lower bound (RFC3339 with timezone offset, e.g., '2024-01-01T00:00:00-08:00')
+- `timeMax`: Upper bound (RFC3339 with timezone offset)
+- `singleEvents`: true to expand recurring events into instances
+- `orderBy`: 'startTime' (requires singleEvents=true) or 'updated'
+- `maxResults`: Results per page (max 2500)
+
+**Pitfalls**:
+- **Timezone warning**: UTC timestamps (ending in 'Z') don't align with local dates; use local timezone offsets instead
+- Example: '2026-01-19T00:00:00Z' covers 2026-01-18 4pm to 2026-01-19 4pm in PST
+- Omitting `timeMin`/`timeMax` scans the full calendar and can be slow
+- `pageToken` in response means more results; paginate until absent
+- `orderBy='startTime'` requires `singleEvents=true`
+
+### 3. Manage Attendees and Invitations
+
+**When to use**: User wants to add, remove, or update event attendees
+
+**Tool sequence**:
+1. `GOOGLECALENDAR_FIND_EVENT` or `GOOGLECALENDAR_EVENTS_LIST` - Find the event [Prerequisite]
+2. `GOOGLECALENDAR_PATCH_EVENT` - Add attendees (replaces entire attendees list) [Required]
+3. `GOOGLECALENDAR_REMOVE_ATTENDEE` - Remove a specific attendee by email [Required]
+
+**Key parameters**:
+- `event_id`: Unique event identifier (opaque string, NOT the event title)
+- `attendees`: Full list of attendee emails (PATCH replaces entire list)
+- `attendee_email`: Email to remove
+- `send_updates`: 'all', 'externalOnly', or 'none'
+
+**Pitfalls**:
+- `event_id` is a technical identifier, NOT the event title; always search first to get the ID
+- `PATCH_EVENT` attendees field replaces the entire list; include existing attendees to avoid removing them
+- Attendee names cannot be resolved; always use email addresses
+- Use `GMAIL_SEARCH_PEOPLE` to resolve names to emails before managing attendees
+
+### 4. Check Availability and Free/Busy Status
+
+**When to use**: User wants to find available time slots or check busy periods
+
+**Tool sequence**:
+1. `GOOGLECALENDAR_LIST_CALENDARS` - Identify calendars to check [Prerequisite]
+2. `GOOGLECALENDAR_GET_CURRENT_DATE_TIME` - Get current time with timezone [Optional]
+3. `GOOGLECALENDAR_FIND_FREE_SLOTS` - Find free intervals across calendars [Required]
+4. `GOOGLECALENDAR_FREE_BUSY_QUERY` - Get raw busy periods for computing gaps [Fallback]
+5. `GOOGLECALENDAR_CREATE_EVENT` - Book a confirmed slot [Required]
+
+**Key parameters**:
+- `items`: List of calendar IDs to check (e.g., ['primary'])
+- `time_min`/`time_max`: Query interval (defaults to current day if omitted)
+- `timezone`: IANA timezone for interpreting naive timestamps
+- `calendarExpansionMax`: Max calendars (1-50)
+- `groupExpansionMax`: Max members per group (1-100)
+
+**Pitfalls**:
+- Maximum span ~90 days per Google Calendar freeBusy API limit
+- Very long ranges or inaccessible calendars yield empty/invalid results
+- Only calendars with at least freeBusyReader access are visible
+- Free slots responses may normalize to UTC ('Z'); check offsets
+- `GOOGLECALENDAR_FREE_BUSY_QUERY` requires RFC3339 timestamps with timezone
+
+## Common Patterns
+
+### ID Resolution
+- **Calendar name -> calendar_id**: `GOOGLECALENDAR_LIST_CALENDARS` to enumerate all calendars
+- **Event title -> event_id**: `GOOGLECALENDAR_FIND_EVENT` or `GOOGLECALENDAR_EVENTS_LIST`
+- **Attendee name -> email**: `GMAIL_SEARCH_PEOPLE`
+
+### Timezone Handling
+- Always use IANA timezone identifiers (e.g., 'America/Los_Angeles')
+- Use `GOOGLECALENDAR_GET_CURRENT_DATE_TIME` to get current time in user's timezone
+- When querying events for a local date, use timestamps with local offset, NOT UTC
+- Example: '2026-01-19T00:00:00-08:00' for PST, NOT '2026-01-19T00:00:00Z'
+
+### Pagination
+- `GOOGLECALENDAR_EVENTS_LIST` returns `nextPageToken`; iterate until absent
+- `GOOGLECALENDAR_LIST_CALENDARS` also paginates; use `page_token`
+
+## Known Pitfalls
+
+- **Natural language dates**: NOT supported; all dates must be ISO 8601 or RFC3339
+- **Timezone mismatch**: UTC timestamps don't align with local dates for filtering
+- **Duration limits**: `event_duration_minutes` max 59; use hours for longer durations
+- **IANA timezones only**: 'EST', 'PST', etc. are NOT valid; use 'America/New_York'
+- **Event IDs are opaque**: Always search to get event_id; never guess or construct
+- **Attendees as emails**: Names cannot be used; resolve with GMAIL_SEARCH_PEOPLE
+- **PATCH replaces attendees**: Include all desired attendees in the array, not just new ones
+- **Conference limitations**: Google Meet may fail on personal accounts (graceful fallback)
+- **Rate limits**: High-volume searches can trigger 403/429; throttle between calls
+
+## Quick Reference
+
+| Task | Tool Slug | Key Params |
+|------|-----------|------------|
+| List calendars | `GOOGLECALENDAR_LIST_CALENDARS` | `max_results` |
+| Create event | `GOOGLECALENDAR_CREATE_EVENT` | `start_datetime`, `timezone`, `summary` |
+| Update event | `GOOGLECALENDAR_PATCH_EVENT` | `calendar_id`, `event_id`, fields to update |
+| Delete event | `GOOGLECALENDAR_DELETE_EVENT` | `calendar_id`, `event_id` |
+| Search events | `GOOGLECALENDAR_FIND_EVENT` | `query`, `timeMin`, `timeMax` |
+| List events | `GOOGLECALENDAR_EVENTS_LIST` | `calendarId`, `timeMin`, `timeMax` |
+| Recurring instances | `GOOGLECALENDAR_EVENTS_INSTANCES` | `calendarId`, `eventId` |
+| Find free slots | `GOOGLECALENDAR_FIND_FREE_SLOTS` | `items`, `time_min`, `time_max`, `timezone` |
+| Free/busy query | `GOOGLECALENDAR_FREE_BUSY_QUERY` | `timeMin`, `timeMax`, `items` |
+| Remove attendee | `GOOGLECALENDAR_REMOVE_ATTENDEE` | `event_id`, `attendee_email` |
+| Get current time | `GOOGLECALENDAR_GET_CURRENT_DATE_TIME` | `timezone` |
+| Get calendar | `GOOGLECALENDAR_GET_CALENDAR` | `calendar_id` |