@commandable/integration-data 0.0.5 → 0.0.6

package/integrations/github/schemas/get_pull_request_diff.json

@@ -0,0 +1,10 @@
+{
+  "type": "object",
+  "properties": {
+    "owner": { "type": "string", "description": "Repository owner" },
+    "repo": { "type": "string", "description": "Repository name" },
+    "pull_number": { "type": "integer", "description": "Pull request number" }
+  },
+  "required": ["owner", "repo", "pull_number"],
+  "additionalProperties": false
+}

package/integrations/github/schemas/get_repo_tree.json

@@ -0,0 +1,12 @@
+{
+  "type": "object",
+  "properties": {
+    "owner": { "type": "string", "description": "Repository owner (user or org)" },
+    "repo": { "type": "string", "description": "Repository name" },
+    "ref": { "type": "string", "description": "Branch name, tag, or commit SHA (defaults to HEAD)" },
+    "recursive": { "type": "boolean", "description": "Return the full recursive tree (all nested files). Default true.", "default": true },
+    "path_filter": { "type": "string", "description": "Optional path prefix to filter results (e.g. 'src/')" }
+  },
+  "required": ["owner", "repo"],
+  "additionalProperties": false
+}

package/integrations/github/schemas/get_workflow_run.json

@@ -0,0 +1,10 @@
+{
+  "type": "object",
+  "properties": {
+    "owner": { "type": "string", "description": "Repository owner" },
+    "repo": { "type": "string", "description": "Repository name" },
+    "run_id": { "type": "integer", "description": "Workflow run ID (obtain from list_workflow_runs)" }
+  },
+  "required": ["owner", "repo", "run_id"],
+  "additionalProperties": false
+}

package/integrations/github/schemas/list_branches.json

@@ -0,0 +1,12 @@
+{
+  "type": "object",
+  "properties": {
+    "owner": { "type": "string", "description": "Repository owner" },
+    "repo": { "type": "string", "description": "Repository name" },
+    "protected": { "type": "boolean", "description": "Filter to only protected branches" },
+    "page": { "type": "integer", "default": 1 },
+    "per_page": { "type": "integer", "default": 30, "maximum": 100 }
+  },
+  "required": ["owner", "repo"],
+  "additionalProperties": false
+}

package/integrations/github/schemas/list_commits.json

@@ -3,9 +3,11 @@
   "properties": {
     "owner": { "type": "string" },
     "repo": { "type": "string" },
-    "sha": { "type": "string" },
-    "path": { "type": "string" },
-    "author": { "type": "string" }
+    "sha": { "type": "string", "description": "Branch name, tag, or commit SHA to start listing from (defaults to default branch)" },
+    "path": { "type": "string", "description": "Filter commits that touch this file path" },
+    "author": { "type": "string", "description": "Filter by GitHub username or email address" },
+    "page": { "type": "integer", "default": 1 },
+    "per_page": { "type": "integer", "default": 30, "maximum": 100 }
   },
   "required": ["owner", "repo"],
   "additionalProperties": false

package/integrations/github/schemas/list_issue_comments.json

@@ -0,0 +1,12 @@
+{
+  "type": "object",
+  "properties": {
+    "owner": { "type": "string", "description": "Repository owner" },
+    "repo": { "type": "string", "description": "Repository name" },
+    "issue_number": { "type": "integer", "description": "Issue number" },
+    "page": { "type": "integer", "default": 1 },
+    "per_page": { "type": "integer", "default": 30, "maximum": 100 }
+  },
+  "required": ["owner", "repo", "issue_number"],
+  "additionalProperties": false
+}

package/integrations/github/schemas/list_issues.json

@@ -4,8 +4,10 @@
     "owner": { "type": "string" },
     "repo": { "type": "string" },
     "state": { "type": "string", "enum": ["open", "closed", "all"], "default": "open" },
-    "labels": { "type": "string" },
-    "assignee": { "type": "string" }
+    "labels": { "type": "string", "description": "Comma-separated list of label names to filter by" },
+    "assignee": { "type": "string", "description": "Filter by assignee username, or 'none' for unassigned, '*' for any" },
+    "page": { "type": "integer", "default": 1 },
+    "per_page": { "type": "integer", "default": 30, "maximum": 100 }
   },
   "required": ["owner", "repo"],
   "additionalProperties": false

package/integrations/github/schemas/list_labels.json

@@ -0,0 +1,11 @@
+{
+  "type": "object",
+  "properties": {
+    "owner": { "type": "string", "description": "Repository owner" },
+    "repo": { "type": "string", "description": "Repository name" },
+    "page": { "type": "integer", "default": 1 },
+    "per_page": { "type": "integer", "default": 100, "maximum": 100 }
+  },
+  "required": ["owner", "repo"],
+  "additionalProperties": false
+}

package/integrations/github/schemas/list_pull_request_comments.json

@@ -0,0 +1,12 @@
+{
+  "type": "object",
+  "properties": {
+    "owner": { "type": "string", "description": "Repository owner" },
+    "repo": { "type": "string", "description": "Repository name" },
+    "pull_number": { "type": "integer", "description": "Pull request number" },
+    "page": { "type": "integer", "default": 1 },
+    "per_page": { "type": "integer", "default": 30, "maximum": 100 }
+  },
+  "required": ["owner", "repo", "pull_number"],
+  "additionalProperties": false
+}

package/integrations/github/schemas/list_pull_request_files.json

@@ -0,0 +1,12 @@
+{
+  "type": "object",
+  "properties": {
+    "owner": { "type": "string", "description": "Repository owner" },
+    "repo": { "type": "string", "description": "Repository name" },
+    "pull_number": { "type": "integer", "description": "Pull request number" },
+    "page": { "type": "integer", "default": 1 },
+    "per_page": { "type": "integer", "default": 30, "maximum": 100 }
+  },
+  "required": ["owner", "repo", "pull_number"],
+  "additionalProperties": false
+}

package/integrations/github/schemas/list_pull_requests.json

@@ -3,7 +3,13 @@
   "properties": {
     "owner": { "type": "string" },
     "repo": { "type": "string" },
-    "state": { "type": "string", "enum": ["open", "closed", "all"], "default": "open" }
+    "state": { "type": "string", "enum": ["open", "closed", "all"], "default": "open" },
+    "head": { "type": "string", "description": "Filter by head user/org and branch (e.g. 'user:my-branch')" },
+    "base": { "type": "string", "description": "Filter by base branch name (e.g. 'main')" },
+    "sort": { "type": "string", "enum": ["created", "updated", "popularity", "long-running"], "default": "created" },
+    "direction": { "type": "string", "enum": ["asc", "desc"], "default": "desc" },
+    "page": { "type": "integer", "default": 1 },
+    "per_page": { "type": "integer", "default": 30, "maximum": 100 }
   },
   "required": ["owner", "repo"],
   "additionalProperties": false

package/integrations/github/schemas/list_releases.json

@@ -0,0 +1,11 @@
+{
+  "type": "object",
+  "properties": {
+    "owner": { "type": "string", "description": "Repository owner" },
+    "repo": { "type": "string", "description": "Repository name" },
+    "page": { "type": "integer", "default": 1 },
+    "per_page": { "type": "integer", "default": 30, "maximum": 100 }
+  },
+  "required": ["owner", "repo"],
+  "additionalProperties": false
+}

package/integrations/github/schemas/list_tags.json

@@ -0,0 +1,11 @@
+{
+  "type": "object",
+  "properties": {
+    "owner": { "type": "string", "description": "Repository owner" },
+    "repo": { "type": "string", "description": "Repository name" },
+    "page": { "type": "integer", "default": 1 },
+    "per_page": { "type": "integer", "default": 30, "maximum": 100 }
+  },
+  "required": ["owner", "repo"],
+  "additionalProperties": false
+}

package/integrations/github/schemas/list_workflow_runs.json

@@ -0,0 +1,18 @@
+{
+  "type": "object",
+  "properties": {
+    "owner": { "type": "string", "description": "Repository owner" },
+    "repo": { "type": "string", "description": "Repository name" },
+    "branch": { "type": "string", "description": "Filter runs by branch name" },
+    "status": {
+      "type": "string",
+      "enum": ["queued", "in_progress", "completed", "action_required", "cancelled", "failure", "neutral", "skipped", "stale", "success", "timed_out", "waiting"],
+      "description": "Filter by run status or conclusion"
+    },
+    "event": { "type": "string", "description": "Filter by triggering event (e.g. 'push', 'pull_request', 'schedule', 'workflow_dispatch')" },
+    "page": { "type": "integer", "default": 1 },
+    "per_page": { "type": "integer", "default": 30, "maximum": 100 }
+  },
+  "required": ["owner", "repo"],
+  "additionalProperties": false
+}

package/integrations/github/schemas/request_pull_request_reviewers.json

@@ -0,0 +1,20 @@
+{
+  "type": "object",
+  "properties": {
+    "owner": { "type": "string", "description": "Repository owner" },
+    "repo": { "type": "string", "description": "Repository name" },
+    "pull_number": { "type": "integer", "description": "Pull request number" },
+    "reviewers": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "GitHub usernames to request reviews from"
+    },
+    "team_reviewers": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Team slugs to request reviews from (org repos only)"
+    }
+  },
+  "required": ["owner", "repo", "pull_number"],
+  "additionalProperties": false
+}

package/integrations/github/schemas/search_code.json

@@ -0,0 +1,10 @@
+{
+  "type": "object",
+  "properties": {
+    "query": { "type": "string", "description": "GitHub code search query. Examples: 'useState repo:facebook/react language:typescript', 'console.log path:src/ language:javascript org:my-org'. Supports language, path, repo, org, and extension filters." },
+    "page": { "type": "integer", "default": 1 },
+    "per_page": { "type": "integer", "default": 30, "maximum": 100 }
+  },
+  "required": ["query"],
+  "additionalProperties": false
+}

package/integrations/github/schemas/search_issues.json

@@ -0,0 +1,10 @@
+{
+  "type": "object",
+  "properties": {
+    "query": { "type": "string", "description": "GitHub issue search query (e.g. 'is:open is:issue label:bug repo:owner/repo', 'is:open assignee:@me', 'is:issue no:assignee'). Supports all GitHub search qualifiers." },
+    "page": { "type": "integer", "default": 1 },
+    "per_page": { "type": "integer", "default": 30, "maximum": 100 }
+  },
+  "required": ["query"],
+  "additionalProperties": false
+}

package/integrations/github/schemas/search_pull_requests.json

@@ -0,0 +1,10 @@
+{
+  "type": "object",
+  "properties": {
+    "query": { "type": "string", "description": "GitHub search query for PRs. Use 'is:pr' to scope to PRs (e.g. 'is:pr is:open author:octocat label:bug repo:owner/repo'). Supports all GitHub issue search qualifiers." },
+    "page": { "type": "integer", "default": 1 },
+    "per_page": { "type": "integer", "default": 30, "maximum": 100 }
+  },
+  "required": ["query"],
+  "additionalProperties": false
+}

package/integrations/github/schemas/search_repos.json

@@ -0,0 +1,12 @@
+{
+  "type": "object",
+  "properties": {
+    "query": { "type": "string", "description": "GitHub repository search query. Examples: 'machine learning language:python stars:>1000', 'topic:react', 'user:facebook is:public'. Supports stars, forks, language, topic, and many other qualifiers." },
+    "sort": { "type": "string", "enum": ["stars", "forks", "help-wanted-issues", "updated"], "description": "Sort repos by this field" },
+    "order": { "type": "string", "enum": ["asc", "desc"], "default": "desc" },
+    "page": { "type": "integer", "default": 1 },
+    "per_page": { "type": "integer", "default": 30, "maximum": 100 }
+  },
+  "required": ["query"],
+  "additionalProperties": false
+}

package/integrations/github/schemas/update_pull_request.json

@@ -0,0 +1,15 @@
+{
+  "type": "object",
+  "properties": {
+    "owner": { "type": "string", "description": "Repository owner" },
+    "repo": { "type": "string", "description": "Repository name" },
+    "pull_number": { "type": "integer", "description": "Pull request number to update" },
+    "title": { "type": "string", "description": "New title for the PR" },
+    "body": { "type": "string", "description": "New description for the PR (markdown)" },
+    "state": { "type": "string", "enum": ["open", "closed"], "description": "Set to 'closed' to close the PR without merging" },
+    "base": { "type": "string", "description": "New base branch to merge into" },
+    "draft": { "type": "boolean", "description": "Set to true to convert to draft, false to mark ready for review" }
+  },
+  "required": ["owner", "repo", "pull_number"],
+  "additionalProperties": false
+}

package/integrations/google-calendar/__tests__/write_and_admin_handlers.test.ts

@@ -102,19 +102,6 @@ suite('google-calendar write & admin handlers (live)', () => {
     const patched = await patch_event({ calendarId: ctx.calendarId, eventId: createdId, body: { summary: `CmdTest Updated ${Date.now()}` } })
     expect(patched?.id).toBe(createdId)
 
-    // Also exercise full update (PUT)
-    const update_event = buildWrite('update_event')
-    const updated = await update_event({
-      calendarId: ctx.calendarId,
-      eventId: createdId,
-      body: {
-        summary: `CmdTest Updated (PUT) ${Date.now()}`,
-        start: { dateTime: patched?.start?.dateTime || new Date().toISOString() },
-        end: { dateTime: patched?.end?.dateTime || new Date(Date.now() + 3600000).toISOString() },
-      },
-    })
-    expect(updated?.id).toBe(createdId)
-
     const delete_event = buildWrite('delete_event')
     const del = await delete_event({ calendarId: ctx.calendarId, eventId: createdId })
     expect(del?.success === true || del === '').toBe(true)

package/integrations/google-calendar/handlers/get_event.js

@@ -1,5 +1,9 @@
 async (input) => {
-  const path = `/calendars/${encodeURIComponent(input.calendarId)}/events/${encodeURIComponent(input.eventId)}`
+  const params = new URLSearchParams()
+  if (input.fields)
+    params.set('fields', input.fields)
+  const qs = params.toString()
+  const path = `/calendars/${encodeURIComponent(input.calendarId)}/events/${encodeURIComponent(input.eventId)}${qs ? `?${qs}` : ''}`
   const res = await integration.fetch(path)
   return await res.json()
 }

package/integrations/google-calendar/handlers/list_events.js

@@ -14,6 +14,8 @@ async (input) => {
     params.set('singleEvents', String(input.singleEvents))
   if (input.orderBy)
     params.set('orderBy', input.orderBy)
+  if (input.fields)
+    params.set('fields', input.fields)
   const qs = params.toString()
   const path = `/calendars/${encodeURIComponent(input.calendarId)}/events${qs ? `?${qs}` : ''}`
   const res = await integration.fetch(path)

package/integrations/google-calendar/manifest.json

@@ -2,25 +2,24 @@
   "name": "google-calendar",
   "version": "0.1.0",
   "tools": [
-    { "name": "list_calendars", "description": "List calendars for the authenticated user.", "inputSchema": "schemas/empty.json", "handler": "handlers/list_calendars.js", "scope": "read" },
-    { "name": "get_calendar", "description": "Get a calendar by ID.", "inputSchema": "schemas/id_calendar.json", "handler": "handlers/get_calendar.js", "scope": "read" },
-    { "name": "list_events", "description": "List events in a calendar with optional time range and query.", "inputSchema": "schemas/list_events.json", "handler": "handlers/list_events.js", "scope": "read" },
-    { "name": "get_event", "description": "Get a specific event by ID from a calendar.", "inputSchema": "schemas/id_calendar_event.json", "handler": "handlers/get_event.js", "scope": "read" },
-    { "name": "list_colors", "description": "Get the color definitions for calendars and events.", "inputSchema": "schemas/empty.json", "handler": "handlers/list_colors.js", "scope": "read" },
-    { "name": "freebusy_query", "description": "Query free/busy information for calendars.", "inputSchema": "schemas/freebusy_query.json", "handler": "handlers/freebusy_query.js", "scope": "read" },
-    { "name": "list_settings", "description": "List user settings.", "inputSchema": "schemas/empty.json", "handler": "handlers/list_settings.js", "scope": "read" },
+    { "name": "list_calendars", "description": "List all calendars in the authenticated user's calendar list, including the primary calendar and any subscribed or shared calendars. Returns calendar IDs needed for list_events, create_event, and other calendar-specific tools. The primary calendar has calendarId='primary'.", "inputSchema": "schemas/empty.json", "handler": "handlers/list_calendars.js", "scope": "read" },
+    { "name": "get_calendar", "description": "Get details for a specific calendar by ID, including its summary, description, timezone, and access role. Use list_calendars to find calendar IDs.", "inputSchema": "schemas/id_calendar.json", "handler": "handlers/get_calendar.js", "scope": "read" },
+    { "name": "list_events", "description": "List events in a calendar with optional time range, text search, and pagination. Use calendarId='primary' for the user's main calendar. Set singleEvents=true and orderBy='startTime' to get recurring events expanded into individual instances in chronological order. Times must be RFC3339 format (e.g. '2024-01-15T09:00:00Z' or '2024-01-15T09:00:00-05:00'). Defaults to 25 results. Use pageToken from the response for the next page.", "inputSchema": "schemas/list_events.json", "handler": "handlers/list_events.js", "scope": "read" },
+    { "name": "get_event", "description": "Get a specific event by its ID from a calendar. Returns full event details including summary, start, end, attendees, location, description, recurrence, and status. Use list_events to find event IDs.", "inputSchema": "schemas/id_calendar_event.json", "handler": "handlers/get_event.js", "scope": "read" },
+    { "name": "list_colors", "description": "Get the set of color definitions available for calendars and events. Returns colorId values and their hex codes. Use colorId values in create_event or patch_event to color-code events.", "inputSchema": "schemas/empty.json", "handler": "handlers/list_colors.js", "scope": "read" },
+    { "name": "freebusy_query", "description": "Query free/busy availability for one or more calendars within a time range. Useful for finding open slots or checking if attendees are available. Provide timeMin, timeMax (RFC3339), and an items array of calendar IDs. Returns busy time blocks for each calendar.", "inputSchema": "schemas/freebusy_query.json", "handler": "handlers/freebusy_query.js", "scope": "read" },
+    { "name": "list_settings", "description": "List the authenticated user's Google Calendar settings, such as timezone, date format, and notification preferences.", "inputSchema": "schemas/empty.json", "handler": "handlers/list_settings.js", "scope": "read" },
 
-    { "name": "create_event", "description": "Create an event in a calendar.", "inputSchema": "schemas/create_event.json", "handler": "handlers/create_event.js", "scope": "write" },
-    { "name": "update_event", "description": "Update an event in a calendar (full update).", "inputSchema": "schemas/update_event.json", "handler": "handlers/update_event.js", "scope": "write" },
-    { "name": "patch_event", "description": "Patch fields on an event in a calendar.", "inputSchema": "schemas/patch_event.json", "handler": "handlers/patch_event.js", "scope": "write" },
-    { "name": "delete_event", "description": "Delete an event from a calendar.", "inputSchema": "schemas/id_calendar_event.json", "handler": "handlers/delete_event.js", "scope": "write" },
-    { "name": "move_event", "description": "Move an event to another calendar.", "inputSchema": "schemas/move_event.json", "handler": "handlers/move_event.js", "scope": "write" },
-    { "name": "quick_add", "description": "Create an event using natural language text.", "inputSchema": "schemas/quick_add.json", "handler": "handlers/quick_add.js", "scope": "write" },
+    { "name": "create_event", "description": "Create a new event in a calendar. Required fields: calendarId, summary, start, end. Use {dateTime, timeZone} for timed events (e.g. {\"dateTime\": \"2024-01-15T10:00:00\", \"timeZone\": \"America/New_York\"}) or {date} for all-day events (e.g. {\"date\": \"2024-01-15\"}). Optional fields: description, location, attendees (array of {email}), recurrence (RRULE strings), reminders, colorId, visibility. The calendarId field is extracted automatically; all other fields are sent as the event body.", "inputSchema": "schemas/create_event.json", "handler": "handlers/create_event.js", "scope": "write" },
+    { "name": "patch_event", "description": "Partially update an event by providing only the fields to change. All other fields are preserved. Use this as the standard event update method. Provide changes in a 'body' object along with calendarId and eventId.", "inputSchema": "schemas/patch_event.json", "handler": "handlers/patch_event.js", "scope": "write" },
+    { "name": "delete_event", "description": "Delete an event from a calendar. This permanently removes the event. For recurring events, this deletes only the specified instance. Use list_events to find event IDs.", "inputSchema": "schemas/id_calendar_event.json", "handler": "handlers/delete_event.js", "scope": "write" },
+    { "name": "move_event", "description": "Move an event from one calendar to another. Provide the source calendarId, eventId, and the destination calendarId. Returns the updated event in the destination calendar.", "inputSchema": "schemas/move_event.json", "handler": "handlers/move_event.js", "scope": "write" },
+    { "name": "quick_add", "description": "Create an event using a natural language text string. Parses the text to extract event details automatically. Examples: 'Meeting with Bob tomorrow at 3pm for 1 hour', 'Dentist appointment on Friday at 2pm', 'Weekly standup every Monday at 9am'. Requires calendarId (use 'primary') and text.", "inputSchema": "schemas/quick_add.json", "handler": "handlers/quick_add.js", "scope": "write" },
 
-    { "name": "list_acl", "description": "List ACL rules for a calendar.", "inputSchema": "schemas/id_calendar.json", "handler": "handlers/list_acl.js", "scope": "admin" },
-    { "name": "get_acl", "description": "Get a specific ACL rule by ID for a calendar.", "inputSchema": "schemas/get_acl.json", "handler": "handlers/get_acl.js", "scope": "admin" },
-    { "name": "insert_acl", "description": "Insert a new ACL rule for a calendar.", "inputSchema": "schemas/insert_acl.json", "handler": "handlers/insert_acl.js", "scope": "admin" },
-    { "name": "update_acl", "description": "Update an ACL rule for a calendar.", "inputSchema": "schemas/update_acl.json", "handler": "handlers/update_acl.js", "scope": "admin" },
-    { "name": "delete_acl", "description": "Delete an ACL rule from a calendar.", "inputSchema": "schemas/delete_acl.json", "handler": "handlers/delete_acl.js", "scope": "admin" }
+    { "name": "list_acl", "description": "List the Access Control List (ACL) rules for a calendar. Returns rules defining who has access and at what permission level (reader, writer, owner). Use get_calendar to find the calendarId.", "inputSchema": "schemas/id_calendar.json", "handler": "handlers/list_acl.js", "scope": "admin" },
+    { "name": "get_acl", "description": "Get a specific ACL rule by its rule ID for a calendar. Use list_acl to find rule IDs.", "inputSchema": "schemas/get_acl.json", "handler": "handlers/get_acl.js", "scope": "admin" },
+    { "name": "insert_acl", "description": "Add a new ACL rule to grant a user or group access to a calendar. Roles: 'reader' (view), 'writer' (view + edit events), 'owner' (full control). Scope must include type ('user', 'group', 'domain', or 'default') and optionally value (email or domain).", "inputSchema": "schemas/insert_acl.json", "handler": "handlers/insert_acl.js", "scope": "admin" },
+    { "name": "update_acl", "description": "Update an existing ACL rule to change a user's or group's permission level on a calendar. Use list_acl to find the rule ID.", "inputSchema": "schemas/update_acl.json", "handler": "handlers/update_acl.js", "scope": "admin" },
+    { "name": "delete_acl", "description": "Remove an ACL rule from a calendar, revoking the associated user's or group's access. Use list_acl to find the rule ID.", "inputSchema": "schemas/delete_acl.json", "handler": "handlers/delete_acl.js", "scope": "admin" }
   ]
 }

package/integrations/google-calendar/prompt.md

@@ -0,0 +1,68 @@
+## Calendar IDs
+
+- Use `calendarId='primary'` for the authenticated user's main calendar
+- Use `list_calendars` to discover other calendar IDs (work, shared, subscribed calendars)
+- Calendar IDs typically look like email addresses (e.g. `user@example.com`) or opaque strings for subscribed calendars
+
+## Date and time format
+
+All times must be in RFC3339 format:
+- Timed events: `'2024-01-15T10:00:00-05:00'` (with timezone offset) or `'2024-01-15T15:00:00Z'` (UTC)
+- All-day events use date-only format: `'2024-01-15'`
+
+## Creating events
+
+For `create_event`, required fields are `calendarId`, `summary`, `start`, and `end`:
+
+**Timed event:**
+```json
+{
+  "calendarId": "primary",
+  "summary": "Team Meeting",
+  "start": { "dateTime": "2024-01-15T10:00:00", "timeZone": "America/New_York" },
+  "end":   { "dateTime": "2024-01-15T11:00:00", "timeZone": "America/New_York" }
+}
+```
+
+**All-day event:**
+```json
+{
+  "calendarId": "primary",
+  "summary": "Company Holiday",
+  "start": { "date": "2024-01-15" },
+  "end":   { "date": "2024-01-16" }
+}
+```
+
+Note: For all-day events, `end.date` should be the day *after* the last day (exclusive end).
+
+## Listing events in chronological order
+
+To list upcoming events in start-time order (e.g. "what's on my calendar this week"):
+- Set `singleEvents=true` to expand recurring events into individual instances
+- Set `orderBy='startTime'` (requires `singleEvents=true`)
+- Set `timeMin` to now (current ISO timestamp) and `timeMax` to the end of the desired range
+
+## Quick add
+
+`quick_add` parses natural language:
+- `"Meeting with Bob tomorrow at 3pm for 1 hour"`
+- `"Dentist appointment on Friday at 2pm"`
+- `"Weekly standup every Monday at 9am"`
+
+## Free/busy queries
+
+Use `freebusy_query` to check availability before scheduling:
+```json
+{
+  "timeMin": "2024-01-15T00:00:00Z",
+  "timeMax": "2024-01-15T23:59:59Z",
+  "items": [{ "id": "primary" }, { "id": "colleague@example.com" }]
+}
+```
+
+## Updating events
+
+- Use `update_event` for a full replacement (all fields must be provided)
+- Use `patch_event` for partial updates (only provide the fields you want to change in `body`)
+- `patch_event` is preferred when modifying one or two fields to avoid accidentally clearing others

package/integrations/google-calendar/schemas/id_calendar_event.json

@@ -1,8 +1,10 @@
 {
+  "$schema": "http://json-schema.org/draft-07/schema#",
   "type": "object",
   "properties": {
-    "calendarId": { "type": "string", "description": "Calendar ID (use 'primary' for primary)." },
-    "eventId": { "type": "string", "description": "Event ID." }
+    "calendarId": { "type": "string", "description": "Calendar ID. Use 'primary' for the user's main calendar." },
+    "eventId": { "type": "string", "description": "Event ID. Obtained from list_events results." },
+    "fields": { "type": "string", "description": "Partial response fields selector to reduce response size. Example: 'id,summary,start,end,attendees'." }
   },
   "required": ["calendarId", "eventId"],
   "additionalProperties": false

package/integrations/google-calendar/schemas/list_events.json

@@ -1,14 +1,16 @@
 {
+  "$schema": "http://json-schema.org/draft-07/schema#",
   "type": "object",
   "properties": {
-    "calendarId": { "type": "string", "description": "Calendar ID (use 'primary' for primary)." },
-    "timeMin": { "type": "string", "description": "RFC3339 start time" },
-    "timeMax": { "type": "string", "description": "RFC3339 end time" },
-    "q": { "type": "string", "description": "Free-text search query" },
-    "maxResults": { "type": "integer", "minimum": 1, "maximum": 2500 },
-    "pageToken": { "type": "string" },
-    "singleEvents": { "type": "boolean", "description": "Expand recurring events" },
-    "orderBy": { "type": "string", "enum": ["startTime", "updated"] }
+    "calendarId": { "type": "string", "description": "Calendar ID. Use 'primary' for the user's main calendar. Find other calendar IDs via list_calendars." },
+    "timeMin": { "type": "string", "description": "Start of the time range (RFC3339 format, e.g. '2024-01-15T00:00:00Z' or '2024-01-15T09:00:00-05:00'). Only events ending after this time are returned." },
+    "timeMax": { "type": "string", "description": "End of the time range (RFC3339 format). Only events starting before this time are returned." },
+    "q": { "type": "string", "description": "Free-text search query matching event summary, description, location, and attendee details." },
+    "maxResults": { "type": "integer", "minimum": 1, "maximum": 2500, "default": 25, "description": "Maximum number of events to return. Defaults to 25. Use pageToken from the response for the next page." },
+    "pageToken": { "type": "string", "description": "Page token from a previous list_events response to retrieve the next page of results." },
+    "singleEvents": { "type": "boolean", "description": "Expand recurring events into individual instances. Set to true with orderBy='startTime' to get events in chronological order." },
+    "orderBy": { "type": "string", "enum": ["startTime", "updated"], "description": "Sort order. 'startTime' requires singleEvents=true. 'updated' sorts by last modification time." },
+    "fields": { "type": "string", "description": "Partial response fields selector to reduce response size. Example: 'items(id,summary,start,end,attendees)'. See Calendar API fields reference." }
   },
   "required": ["calendarId"],
   "additionalProperties": false

package/integrations/google-docs/__tests__/get_handlers.test.ts

@@ -70,28 +70,13 @@ suiteOrSkip('google-docs read handlers (live)', () => {
         await safeCleanup(async () => drive.write('delete_file')({ fileId: folderId }))
       }, 60000)
 
-      it('get_document returns metadata/content', async () => {
+      it('read_document returns markdown content', async () => {
         if (!documentId)
           return expect(true).toBe(true)
-        const handler = docs.read('get_document')
+        const handler = docs.read('read_document')
         const result = await handler({ documentId })
-        expect(result?.documentId || result?.body?.content || result?.title).toBeTruthy()
-      }, 30000)
-
-      it('get_document_text returns plain text', async () => {
-        if (!documentId)
-          return expect(true).toBe(true)
-        const handler = docs.read('get_document_text')
-        const result = await handler({ documentId })
-        expect(typeof result?.text === 'string').toBe(true)
-      }, 30000)
-
-      it('get_document_structured returns body JSON', async () => {
-        if (!documentId)
-          return expect(true).toBe(true)
-        const handler = docs.read('get_document_structured')
-        const result = await handler({ documentId })
-        expect(result?.body || result?.documentId).toBeTruthy()
+        expect(result?.documentId || result?.title).toBeTruthy()
+        expect(typeof result?.markdown).toBe('string')
       }, 30000)
     })
   }