tinyhat-google-workspace

Files (1)

• SKILL.md

SKILL.md (first lines)

# Tinyhat Google Workspace

Use `tinyhat_google_workspace` for account and permission lifecycle. Use
`tinyhat_google_workspace_app` for Google API operations.

## Choose the account

Call `{"action": "status"}` when the intended account is not already known.
Status returns safe account metadata, including an opaque `account_id` for each
connected Google account. Match the user's wording to the returned email; never
guess between multiple accounts. If the user did not identify one, show the
safe account list and ask which account to use.

Pass the selected `account_id` to permission changes, disconnect, and every gws
operation when multiple accounts are connected. Do not expose or ask for raw
tokens.

## Connect and change permissions

If the current `tinyhat_google_workspace` schema is not already visible, call
`tool_describe` before the first invocation. Never discover the schema by
probing with `{"action": "connect"}`: that creates a real identity-only OAuth
attempt. For a message that names a Gmail action, make one correctly parameterized
call with the matching preset or exact Custom scopes.

`{"action": "connect"}` adds another account with identity only: `openid`,
`email`, and `profile`. Phrases such as "add my personal account" or "connect my
work Google account" mean add, not replace. Do not add Workspace data access
unless the user's request needs it.

When the user asks vaguely to connect Gmail or grant "reasonable", "normal",
or unspecified Google access, call `{"action": "choose_permissions"}`. The
tool sends a concise Telegram Mini App chooser. Do not guess a broad preset,
and do not ask the user to know OAuth scope names. If the user clearly states
the intended work, skip the chooser and request the narrowest matching preset:

- "send email", "email people", or "send messages" → `mail_sender`
- "draft", "prepare", "write", or "edit email drafts" → `mail_writer`
- "read", "search", "summarize", or "review email" → `mail_reader`
- "organize", "label", "archive", "mark read", or "manage my inbox" →
  `inbox_manager`

Normal wording is enough. Do not require phrases such as "send-only scope" or
an exact permission URL. A request to draft email must use `mail_writer`
because Google does not offer a draft-only scope: `gmail.compose` also permits
sending. A request only to send must use the narrower `mail_sender` preset and
must not use `mail_writer` or `inbox_manager`.

Use a preset only when its capabilities exactly cover what the user asked for.
Never translate an exact or Custom request to the "closest" preset, and never
silently broaden access because a broader preset is already implemented. If no
preset is an exact match, use an exact manifest-listed `scopes` subset or union
with a precise `reason`. If the requested access is ambiguous or cannot be
represented exactly by implemented scopes, ask the user to clarify or return
the tool's `review_required` result; do not retry with broader access.

Use the `presets` array for common access. Presets compose, so request the
smallest combination that supports the user's task:

| Preset | Id | Access |
| --- | --- | --- |
| Mail Reader | `mail_reader` | Read Gmail messages, threads, and settings without changing them. |
| Mail Sender | `mail_sender` | Send confirmed email without reading the inbox or managing drafts. |
| Workspace Reader | `workspace_reader` | Read Gmail messages, threads, and settings, Calendar events, and Drive files. |
| Mail Writer | `mail_writer` | Create and manage Gmail drafts and send email through `gmail.compose`. |
| Inbox Manager | `inbox_manager` | Read, compose, send, draft, label, archive, and change read state through `gmail.modify`; it cannot bypass Trash for immediate permanent deletion. |
| Calendar Coordinator | `calendar_coordinator` | Read, create, update, and delete Calendar events through `calendar.events`. |
| File Collaborator | `file_collaborator` | Work with Drive files Tinyhat creates or files you explicitly share with the app through `drive.file`; it does not grant access to other Drive files. |

Examples:

```json
{"action": "connect", "presets": ["mail_sender"]}
```

```json
{"action": "connect", "presets": ["workspace_reader"]}
```

```json
{"action": "set_permissions", "account_id": "...", "presets": ["mail_writer", "calendar_coordinator"]}
```

For Custom access, supply an exact subset or union of manifest-listed canonical
`scopes` and a short `reason`. Custom scopes may extend a `presets` selection.
An explicit Custom request stays Custom even when its scope set happens to
equal a preset. Do not replace it with a nearby preset or infer extra
capabilities from the user's reason.
Tinyhat always includes the identity baseline and normalizes redundant scopes
before it prepares consent:

- `gmail.modify` supersedes Gmail read, compose, send, and label-only scopes.
- `gmail.compose` supersedes `gmail.send`.
- `calendar.events` supersedes `calendar.events.readonly`.

The public manifest is the source of truth for which scopes are implemented and
which OAuth clients may request them. Its request state is separate from its
Google verification state. An implemented scope may start authorization while
verification is `preparing_submission`; Google may show an unverified-app
warning and the user decides whether to continue. Unknown, unimplemented, or
legacy-only scopes return a structured `review_required` result before creating
OAuth state, starting a worker, or sending a Google button. Explain that result
and do not retry with a broader permission.

The historical `profile` field and its values remain compatibility inputs for
older callers and saved grants. Do not choose a legacy profile for a new
request when `presets` or `scopes` can express the intent. `profile` is
mutually exclusive with `presets` and `scopes`.

`connect` with an explicit `account_id` is additive: it combines the selected
account's current scopes with the requested presets and Custom scopes.
`set_permissions` is exact replacement: it installs only the selected presets
and Custom scopes, plus identity. Use exact replacement when narrowing access.

Google consent is the permission decision. The native Google button opens the
exact request. The user may grant it or return and ask for narrower access. Do
not add a separate Tinyhat permission-upgrade confirmation or pass `confirmed`
or `confirmation_id` to the connection tool. OAuth consent does not authorize
an email send, draft or label mutation, Calendar change, file write, or other

From tinyhat-ai/tinyhat, MIT.

More from tinyhat-ai/tinyhat