Contacts & Directory

Look up people in the user's personal contacts, "other contacts" (people they've corresponded with), and the Workspace directory via the Google People API. Uses bridge google. The bridge automatically resolves credentials from the claw owner's Google connection.

Scope error handling

Call the bridge command for the user's actual request directly — do not pre-flight a verifier call first. JIT will surface the right signal if a permission is missing; adding a verifier just triggers an unrelated extra consent prompt the user shouldn't have to grant.

MUST: when any bridge google command returns a JSON object with a "reason" field (no_connection, scope_required, team_claw_unsupported, expired) instead of API data, paste the entire JSON line verbatim in your reply on its own line. Paraphrasing, summarising, or omitting any field means the inline Connect button does not render and the user is stuck with no way to grant the permission. After the JSON line add one short sentence telling the user what's missing. Never offer browser walkthroughs, settings-page navigation, "open it in your browser" links, or other manual workarounds — the inline button is the only supported path.

Common Actions

Search personal contacts

bridge google --skill contacts-directory people people searchContacts --params '{"query":"alex","readMask":"names,emailAddresses,phoneNumbers,organizations"}'

Search "other contacts" (people you've emailed but not saved)

bridge google --skill contacts-directory people otherContacts search --params '{"query":"alex","readMask":"names,emailAddresses"}'

Search the Workspace directory (org-wide)

bridge google --skill contacts-directory people people searchDirectoryPeople --params '{"query":"alex","readMask":"names,emailAddresses,organizations,phoneNumbers","sources":["DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE"]}'

List all personal contacts (paginated)

bridge google --skill contacts-directory people people connections list --params '{"resourceName":"people/me","pageSize":100,"personFields":"names,emailAddresses,organizations"}'

Get a specific contact

bridge google --skill contacts-directory people people get --params '{"resourceName":"people/CONTACT_ID","personFields":"names,emailAddresses,phoneNumbers,addresses,organizations,biographies"}'

Typical Use Cases

• Resolve a name to an email before drafting a message in the Gmail skill
• Find the right org-internal recipient before scheduling via Calendar
• Pull title/department from the directory to personalize sales outreach
• Disambiguate when the user says "send this to Alex" and there are multiple Alexes

Safety

• Treat directory data as confidential — don't broadcast colleague info without reason
• Prefer searchContacts / searchDirectoryPeople over listing everyone — narrower and faster
• When you find multiple matches, show the user a short list and ask which one they meant
• Never store or echo phone numbers / addresses unless directly asked