Boomerang

Create one or more self-declared relationship paths. A super connector manually asserts they know a target account or contact, which is stored as a SELF_DECLARED_ACCOUNT or SELF_DECLARED_CONTACT path and used to surface warm intro opportunities. Use when: Use when a team member (super connector) wants to declare that they personally know a contact or have a relationship with an account, and this relationship was not automatically detected via calendar or LinkedIn signals. workspace_id / user_id are injected from request headers. Returns items[] with fields: relationship_path validation_errors success Also returns pagination info (type, message, status). IMPORTANT: If the response contains more than one record, always present the options to the user and ask them to choose before taking any follow-up action. Do not act on all results automatically.

create_self_declared_relationship

Create a workspace tag for an entity type. Names are unique per entity type, case-insensitively. Use when: Use when the user asks for a label that does not exist yet and you are not attaching it to anything. To create and attach in one step, prefer AssignTagsByName. workspace_id / user_id are injected from request headers. Also returns pagination info (id, name, entity_type).

create_tag

Create a workflow trigger for a recipient. Two kinds: (1) SCHEDULED — Temporal cron or one_time_fire_at in absolute UTC (default); (2) WEBHOOK — Composio inbound CRM event, no cron. Always set name, ≤100-char description (never copy the prompt), prompt, channels, scope (USER|WORKSPACE), and draft metadata.preview per channel. For WORKSPACE also set activation_mode: WORKSPACE_MANDATORY (runs for everyone in the audience; no per-user opt-in) or WORKSPACE_OPT_IN (shared template teammates enable individually). For WEBHOOK also set trigger_kind=WEBHOOK and metadata.supported_events (or pass template_id from an admin WEBHOOK trigger_template so the backend inherits kind + supported_events). For SCHEDULED provide exactly one of cron or one_time_fire_at. When creating from an admin template seed, copy template_id, trigger_kind, and metadata.supported_events verbatim from the seed JSON — never invent event slugs. Use when: Use for a new reminder/schedule OR a new event-driven HubSpot/Salesforce notification, OR to opt-in/activate an existing WORKSPACE_OPT_IN catalog template for the requesting user (pass catalog_id from create/list — that creates a USER activation; do not use updateWorkflowTrigger for first-time opt-in). Ask scope=USER vs WORKSPACE before free-form creates. If WORKSPACE, ask whether it must run for everyone with no opt-in (activation_mode=WORKSPACE_MANDATORY, workspace admin) or be a template teammates enable (WORKSPACE_OPT_IN). If the conversation seed includes a workflow_trigger_template_context JSON block, this is a template create: pass template_id + trigger_kind + metadata from that block, put template instructions into prompt (customize with the user), omit cron for WEBHOOK, and do not invent supported_events. If there is no seed but the user wants an admin template, call listTriggerTemplates first and copy id → template_id. Call list_workflow_triggers first to avoid duplicates. Always draft metadata.preview for the channel(s) in use. workspace_id / user_id are injected from request headers.

createWorkflowTrigger

Add or update a non–Super Connector workspace member. Email is required — this tool upserts by email. Do NOT use for new Super Connectors — use add_super_connector instead (it creates the user, assigns the Super Connector role, and places them in a category in one step). For new members (Requester, Admin, etc.): present an interactive add-member form UI with required fields Email, First Name, Last Name, plus optional Phone and LinkedIn URL. Never block submit on the optional fields. The form has NO role field — roles are assigned separately via add_role after this call succeeds. On form Submit: call THIS tool with all submitted identity fields. NEVER call add_role on form submit. Do not ask for identity fields in plain chat when a form is shown. For updates: if email was not provided, ask the user to supply it. If they do not know the email, collect other identifiers, call search_workspace_members to find matches, present the best match with name and email, and ask 'Is this the person you want to update?' — only call this tool after the target member is confirmed and email is known. Creates the platform User if needed, then creates or updates the workspace membership. Returns keycloak_user_id (internal — never say this to the user). Does NOT assign workspace roles. USER-FACING COPY after success: e.g. 'I've added Manthan to the workspace.' If a role was discussed earlier: 'Would you like me to assign the Requester role?' — never say 'create_workspace_member', 'membership created', 'no role assigned', or explain which tool ran. Use when: Use to add or update workspace members who are NOT Super Connectors. If the user wants to add a Super Connector, use add_super_connector instead — do NOT call create_workspace_member or add_role for that flow. ADD flow (non-SC): (1) render add-member form → (2) user submits → (3) call create_workspace_member with all identity fields — NOT add_role. (4) If a role was discussed (e.g. Requester, Admin), call add_role after success using keycloak_user_id from the response. UPDATE flow without email: search via search_workspace_members, confirm identity, then call with resolved email. Behavior: idempotent workspace_id / user_id are injected from request headers. Prerequisites (check before calling this tool): [REQUIRED] Email must be known and the target member confirmed before calling. Verify: If email was not provided, ask the user for it. If unavailable, collect name, LinkedIn URL, and/or phone, call search_workspace_members, show the top match(es) with name and email, and get explicit user confirmation ('Is this the person you want to update?') before proceeding. For new members, render the add-member form UI and wait for submit — do not call with guessed values. Next steps (after this tool succeeds): [optional] [SUGGESTION] → call add_role: Tell the user they were added successfully (use their name). If a non–Super Connector role was discussed earlier, assign it via add_role (plain language confirmation only). Never mention tool names, API calls, membership records, or internal IDs. Also returns pagination info (created_at, updated_at, created_by, updated_by, deleted_at, deleted_by).

create_workspace_member

Delete the single MEMORY document for a USER or WORKSPACE scope. Soft-deletes the row (audit history preserved). Idempotent — a missing row returns deleted=false. Use when: Use when the user explicitly asks to clear their scoped memory. Prefer UpsertScopedMemory to update, not delete-then-recreate. Behavior: destructive workspace_id / user_id are injected from request headers.

delete_scoped_memory

Return live enum values for every FilterableField, GroupByField, and MetricField per entity — generated from real workspace data, not hand-maintained lists. Use to discover which strength values, path_types, or categories exist before filtering on them. Use when: Call when unsure which enum values are valid for a field in the current workspace (e.g. which relationship categories exist, which path_types are populated). Response is workspace-specific. Behavior: read_only workspace_id / user_id are injected from request headers. Returns entities[] with fields: entity filterable_fields: All FilterableField values valid for this entity, with enum values and supported ops. supported_group_by: All GroupByField values valid for this entity. supported_metrics: All MetricField values valid for this entity. supported_columns: All ResponseColumn values valid for this entity. IMPORTANT: If the response contains more than one record, always present the options to the user and ask them to choose before taking any follow-up action. Do not act on all results automatically.

describe_schema

For a list of target accounts, find the current buying committee at each account that a super connector can warmly reach (they overlapped in tenure at that account), then create the contacts and WORK_OVERLAP relationship paths. Returns each contact with the connecting super connector, title, tenure overlap, and — when relevance ran — an assistant relevance verdict. This WRITES data: it creates contacts and relationship paths. Only accounts that carry a super-connector relationship and whose workspace has a buying_committee_regex produce results. Use when: Use when a rep or admin wants to surface (and materialize) the warm buying committee for specific target accounts on demand, rather than waiting for the background automation. Pass the target account ids. Leave run_relevance false unless the caller explicitly wants the slower LLM relevance filter for very large companies. Behavior: destructive workspace_id / user_id are injected from request headers. Returns contacts[] with fields: account_id account_linkedin_id account_name super_connector_keycloak_user_id super_connector_linkedin_id contact_id contact_linkedin_id contact_first_name contact_last_name contact_title connecting_company_size overlap_months relevance_evaluated relevance_decision_yes relevance_score path_created IMPORTANT: If the response contains more than one record, always present the options to the user and ask them to choose before taking any follow-up action. Do not act on all results automatically.

evaluate_work_overlap_contacts

Upload and manage files. Drop files here to send them to the server.

file_manager

Find candidate companies by name, region(s), industry list, and/or employee-count band. Returns ranked CompanyCandidate entries (social_id, name, industry, company_size, employees_num, country_code, match_score) plus total_matched and truncated. Use the returned social_id as company_social_ids input to search_people_by_location_and_seniority. Use when: Use BEFORE any company-anchored people search, including when the user named a company by name rather than by LinkedIn id — resolving a name here (rather than passing company_name straight to the people-search tool) avoids an ambiguous-match rejection. Also use directly for 'find companies like X' or 'companies in Ohio, industrials, 200-1000 employees' style requests that are themselves the goal (e.g. before an ICP sweep). Behavior: read_only, idempotent Returns candidates[] with fields: social_id name industry company_size employees_num country_code match_score icp_industry icp_industry_categories IMPORTANT: If the response contains more than one record, always present the options to the user and ask them to choose before taking any follow-up action. Do not act on all results automatically.

find_companies

List the account categories: the fixed vocabulary (Customer, Prospect, …) with display labels. Use when: Use to populate a category picker before calling BulkSetAccountCategory, BulkAddAccountCategories or BulkRemoveAccountCategories. Behavior: read_only workspace_id / user_id are injected from request headers. Returns categories[] with fields: category label IMPORTANT: If the response contains more than one record, always present the options to the user and ask them to choose before taking any follow-up action. Do not act on all results automatically.

get_account_categories

Retrieve the stored company profile (research document) for the workspace. Returns a structured object with sections: one_line_summary, value_proposition, pain_points, proof_points, competitors, customer_industry_category, customer_industry, departments, seniority, title_keywords, title_regex, buying_committee, buying_committee_regex, extended_buying_committee, extended_buying_committee_regex, company_size, named_customers, named_investors. IMPORTANT — rendering instructions: do NOT dump raw JSON, bullet lists of keys, or plain text paragraphs in chat. After fetching, render the full document as a self-contained editable UI (React or HTML artifact) — the user must review and edit each section inline. Use when: Use when the user wants to view or edit the company profile / company research for the workspace. After the tool returns, IMMEDIATELY render the editable artifact UI in the same turn — do not summarize the JSON in prose. If the response contains no document or all sections are empty/null, tell the user 'No company profile has been generated yet' and prompt them to generate one from the app — do NOT render an empty artifact. GenerateCompanyResearch is not an exposed MCP tool so it cannot be called directly; direct the user to trigger generation from the Boomerang app, then call get_company_profile again once they confirm it is ready. Behavior: read_only workspace_id / user_id are injected from request headers. Next steps (after this tool succeeds): [REQUIRED] [ACTION] → call update_company_profile: MANDATORY same turn: render the returned data as an editable company profile artifact UI with labeled sections and a Save button wired to update_company_profile. Do NOT echo JSON or field values as chat text. Also returns pagination info (researched_on, company_name, company_url, one_line_summary, value_proposition, pain_points, proof_points, competitors, customer_industry_category, departments, seniority, title_keywords, company_size, named_customers, named_investors, title_regex, buying_committee, buying_committee_regex, customer_industry, extended_buying_committee, extended_buying_committee_regex).

get_company_profile

Fetch a previously-registered CRM specification by its own id. Use when: Use when you already have a CrmSpecification id (from create_crm_specification's response) and need to confirm its connection_source or check is_deleted. Behavior: read_only workspace_id / user_id are injected from request headers.

get_crm_specification

Get the logged-in user (requestor) for this MCP session. Call this when you need to know who is authenticated — for example when the user asks "who am I?", when a workflow needs the current user's ID, or before calling tools that act on behalf of the requestor (intro requests, relationship actions, workspace membership checks, etc.). The returned ``user_id`` is the Keycloak subject (``sub`` claim). This is the same identifier injected as ``user_id`` on workspace-scoped tool calls via request context. Returns: The requestor's user_id plus basic profile fields from the access token when available (email, name).

get_current_user

Get information about the workspace you are currently working in. Call this when the user asks which workspace they are in, or wants details about their active workspace (name, type, description, contact stats, etc.). Returns: Workspace details for the active session workspace, or an error if none is selected.

get_current_workspace

Fetch the latest AI-generated draft of a specific type for an intro request. After request_intro, this is an automatic mandatory follow-up — call without asking the user. Call once per draft type: GHOSTWRITTEN_EMAIL (email the requester sends directly), FORWARDABLE_EMAIL (email the referrer / SUPER_CONNECTOR workspace member forwards), and TEXT (plain-text message). Returns the draft content so the user can review and edit it before the intro request is submitted. IMPORTANT — rendering instructions: do NOT dump raw JSON or plain text. After fetching drafts, render each one in an editable UI matched to its type — the user must be able to change fields inline and save. For GHOSTWRITTEN_EMAIL and FORWARDABLE_EMAIL: render a self-contained editable email composer (React or HTML artifact) styled like an email client — editable inputs for From, To, CC, and Subject; an editable textarea or rich-text area for Body. Label each card with its draft type (e.g. 'Ghostwritten Email', 'Forwardable Email'). Include a Save button per draft that calls update_draft with is_manually_edited=true and the edited email_content. For TEXT: render an editable textarea pre-filled with the message and a Save button that calls update_draft with the edited text_content. Use tabs or cards when showing multiple drafts. Render as an artifact so the user can review, edit, and save outreach copy before submitting the intro request. Use when: Call automatically in the same turn immediately after request_intro succeeds — do NOT ask 'Want me to pull those up?' Call three times — GHOSTWRITTEN_EMAIL, FORWARDABLE_EMAIL, TEXT — using intro_request_id from the request_intro response, then render all results in editable email/text UI with Save wired to update_draft. Only proceed to intro_request_send_state_change_event (INTRO_REQUESTED_EVENT) after the user has reviewed (and optionally saved edits to) the drafts. Behavior: read_only workspace_id / user_id are injected from request headers. Next steps (after this tool succeeds): [optional] [ACTION] → call update_draft: When the user edits a draft in the UI and clicks Save, call update_draft with is_manually_edited=true and the full edited email_content or text_content. [optional] [SUGGESTION] → call intro_request_send_state_change_event: After the user has reviewed and saved any draft edits, submit the intro request for admin review. Also returns pagination info (request_context).

get_draft_by_type

Poll an email extraction job. Returns status and progress counters. When status is COMPLETED, PARTIALLY_COMPLETED, or FAILED, also returns results[] with each contact's email (if found), email_status, resolved_vendor, and row status. Poll until terminal; do not invent emails. Use when: Use after submitEmailExtractionJob (or any flow that returned a job_id) to check whether extraction finished. Read results from this response when the job is terminal — no separate results call is needed. Behavior: read_only Returns results[] with fields: row_id first_name last_name company_name company_domain email email_status confidence resolved_vendor status boomerang_identity_id Also returns pagination info (seconds, nanos). IMPORTANT: If the response contains more than one record, always present the options to the user and ask them to choose before taking any follow-up action. Do not act on all results automatically.

getEmailExtractionJobStatus

Fetch the tags attached to specific entities, keyed by entity id. Entities are addressed by internal UUID. Use when: Use when you already have entity ids and need their tags — e.g. showing why an account was grouped a certain way. Behavior: read_only workspace_id / user_id are injected from request headers. Returns entities[] with fields: entity_id tags IMPORTANT: If the response contains more than one record, always present the options to the user and ask them to choose before taking any follow-up action. Do not act on all results automatically.

get_entity_tags

Exact lookup of a single person by LinkedIn handle/vanity name (or full LinkedIn URL), returning their profile and full work-experience history. Use this instead of search_people when the user gives you a specific LinkedIn profile URL or handle. Use when: User supplies a LinkedIn URL or bare handle and wants that specific person's profile and/or career history — not a filtered search. Behavior: read_only, idempotent Returns experiences[] with fields: title company_name company_social_id start_date end_date is_current Also returns pagination info (full_name, current_title, current_company, location, country_code, linkedin_url, social_followers, person_social_id). IMPORTANT: If the response contains more than one record, always present the options to the user and ask them to choose before taking any follow-up action. Do not act on all results automatically.

get_person_by_linkedin_handle

Find Power Users in this workspace who appear to have left the employer originally declared for them on import, detected in the last 30 days. Not scoped to any notion of account ownership — returns every matching Power User workspace-wide (optionally filtered to one account). Returns, per person, a LinkedIn profile URL, which account they're associated with (the account itself IS their new/current employer), their past/declared company and (best-effort) title, their current title/tenure as last resolved from profile data, and an approximate job-change-detected timestamp. Use when: Use when you need to check whether any Power User in this workspace has moved to a new employer in roughly the last month. Only job changes detected within the trailing 30 days (as of the call) are returned — there's no way to widen or shift this window via the request. Omit account_id to search the whole workspace; pass account_id to scope to one specific account (a plain filter, not an ownership check). Workspace is taken from session context. Behavior: read_only workspace_id / user_id are injected from request headers. Prerequisites (check before calling this tool): [optional] Do not treat left_provided_company as a confirmed job change — it is a signal derived from resolved company records, which can be stale or wrong. Verify: N/A — this is a standing caveat on every result this tool returns, not a precondition to check beforehand. Next steps (after this tool succeeds): [REQUIRED] [ACTION]: Before acting on any result (e.g. drafting outreach, notifying a rep), independently verify the job change is genuine — e.g. a web search or LinkedIn lookup for the person's current role. [optional] [SUGGESTION]: If page_info.total_pages is greater than page_info.current_page_number + 1, call this tool again with page_number incremented by 1 to retrieve the remaining results. Internal fields — available for follow-up tool calls but do NOT display to the user: `relationship_path_id`, `power_user_id` Returns results[] with fields: relationship_path_id account_id: CRM account UUID this Power User is associated with. account_name: Name of the CRM account this Power User is associated with. account_owner_email: [redacted] power_user_id user_linkedin_id power_user_linkedin_url: Full LinkedIn profile URL for this Power User — use this to look up their current role and verify the job change before acting on it. first_name last_name connector_email: [redacted] provided_company_name provided_company_domain provided_company_linkedin_id resolved_provided_company_linkedin_id past_title current_company_name current_company_linkedin_id current_title current_company_start_date current_company_end_date is_current left_provided_company job_change_detected_at import_extras Also returns pagination info (total_pages, current_page_number, page_size, total_count). IMPORTANT: If the response contains more than one record, always present the options to the user and ask them to choose before taking any follow-up action. Do not act on all results automatically.

get_power_user_job_changes

Fetch a single referrer request by its UUID for a specific referrer (workspace member with SUPER_CONNECTOR role). Returns full details including current state, decline reason, reason text, and timestamps. Use when: Use when you have referrer_request_id and referrer_id (the workspace member with SUPER_CONNECTOR role) and need full details of that connector leg — status, decline reason, or timestamps before SendStateChangeEvent. Behavior: read_only workspace_id / user_id are injected from request headers. Internal fields — available for follow-up tool calls but do NOT display to the user: `actor_id` Also returns pagination info (reason, declined_reason, acted_on_behalf_of_referrer, new_holder_id).

get_referrer_request_for_referrer_by_id

Load the single MEMORY document for a USER or WORKSPACE scope (full markdown_body). Use when: Use before maintaining memory: retrieve the existing scoped memory document to merge an observation into it. Behavior: read_only workspace_id / user_id are injected from request headers. Also returns pagination info (id, slug, family, scope, workspace_id, user_id, display_name, description, injection_strategy, priority, enabled, publish_status, tags, tool_binding_key, activation_conditions_json, visibility_conditions_json, metadata_json, published_version, created_at, updated_at, created_by, updated_by, latest_version, session_id, entity_type, entity_id).

get_scoped_memory

Fetch how and why a super connector was provisioned (roles, qualifying company, investor / public-research / calendar evidence, and a human-readable notes summary) so closeness to the workspace can be judged. Use when: When assessing how strong or close a specific super connector's relationship to the workspace is, given who provisioned them and why. Behavior: read_only, idempotent DEPRECATED. workspace_id / user_id are injected from request headers. Also returns pagination info (roles, reason, qualifying_company_name, qualifying_company_linkedin_id, producer, investor_evidence, public_research_evidence, calendar_evidence, notes, summary, relevance_score, relevance_band, relevance_scored_at).

get_super_connector_metadata

Fetch how and why one or more super connectors were provisioned (roles, qualifying company, investor / public-research / calendar evidence) together with their relevance verdict — summary, relevance_score (1-100 against the workspace's own company), and relevance_band (HIGH/MEDIUM/LOW) — so closeness to the workspace can be judged. Accepts 1..N super connector ids in a single call — always prefer this over calling repeatedly per id. Use when: When assessing how strong or close one or many super connectors' relationships to the workspace are, given who provisioned them and why. Prefer relevance_band / relevance_score and summary when present; fall back to notes for connectors that have not been scored yet. Use this for both single-id and multi-id lookups. Behavior: read_only, idempotent workspace_id / user_id are injected from request headers. Returns entries[] with fields: super_connector_id provisioning_evidence IMPORTANT: If the response contains more than one record, always present the options to the user and ask them to choose before taking any follow-up action. Do not act on all results automatically.

get_super_connector_metadata_bulk

Fetch available filter option values (seniority, location, category, strength, relationship path type, department, account owner, industry, country, employee size, ICP) for warm intro paths scoped to a reference entity (account, contact, or super connector). Returns value/label pairs with counts so the LLM can present valid filter choices to the user. Use when: Use before or alongside SearchWarmIntroRelationships when you need to show the user which filter values exist for a given account, contact, or super connector scope. Pass any already-active filters to narrow the returned option lists dynamically. Do not use this to retrieve relationship paths — use SearchWarmIntroRelationships for that. Behavior: read_only workspace_id / user_id are injected from request headers. Returns seniority[] with fields: value label count Returns location[] with fields: value label count Returns category[] with fields: value label count Returns strength[] with fields: value label count Returns relationship_path_type[] with fields: value label count Returns department[] with fields: value label count Returns account_owner[] with fields: value label count Returns account_industry[] with fields: value label count Returns account_country[] with fields: value label count Returns account_employee_size[] with fields: value label count Returns account_icp[] with fields: value label count Returns account_office_country[] with fields: value label count Returns account_office_state[] with fields: value label count Returns account_office_city[] with fields: value label count IMPORTANT: If the response contains more than one record, always present the options to the user and ask them to choose before taking any follow-up action. Do not act on all results automatically.

get_unique_filter_options

Look up a platform user by email address. Returns the user's Keycloak ID and profile fields (name, LinkedIn ID). Use get_user_by_email to check if someone already exists or to resolve identity before updating a workspace member. Use when: Use when you know the email and need to look up a user before adding or updating workspace membership. If email is unknown during an update, prefer search_workspace_members to find existing members, confirm identity with the user, then call create_workspace_member with the resolved email. Behavior: read_only Also returns pagination info (created_at, updated_at, created_by, updated_by, deleted_at, deleted_by).

get_user_by_email

Retrieve the stored person profile (research document) for a user in the workspace. Returns a structured object with researched_on, person_name, person_url and a role classification (value/source/confidence). IMPORTANT — rendering instructions: do NOT dump raw JSON, bullet lists of keys, or plain text paragraphs in chat. After fetching, render the document as a self-contained editable UI (React or HTML artifact) — the user must review and edit the role inline. Use when: Use when the user wants to view or edit the researched role for a person in the workspace. After the tool returns, IMMEDIATELY render the editable artifact UI in the same turn — do not summarize the JSON in prose. If no document exists yet, trigger GenerateUserResearch first, then call get_user_profile again when ready. Behavior: read_only workspace_id / user_id are injected from request headers. Next steps (after this tool succeeds): [REQUIRED] [ACTION] → call update_user_profile: MANDATORY same turn: render the returned data as an editable person profile artifact UI with the role field and a Save button wired to update_user_profile. Do NOT echo JSON or field values as chat text. Also returns pagination info (researched_on, person_name, person_url, role, next_15_days_focus, next_90_days_focus).

get_user_profile

List all categories configured in the current workspace. Each category has id, label, name, description, and relationship_type. For the add-member Super Connector Category dropdown, filter to entries where relationship_type is SUPER_CONNECTORS and is_deleted is false — use id as the option value and label (or name) as the display text. Use when: Call before rendering the add–Super Connector form (add_super_connector flow) — populates the required Category dropdown. Do NOT use with create_workspace_member for Super Connectors. Also use when the user asks what Super Connector categories exist in the workspace. REQUIRED before applying FILTER_FIELD_CATEGORY in search_warm_intro_relationships: filter response to relationship_type SUPER_CONNECTORS and is_deleted false, match the user's intent to a category label (e.g. 'Investor Employees', 'Advisor'), then pass that category's id UUID as the filter value. Behavior: read_only workspace_id / user_id are injected from request headers. Returns categories[] with fields: id: Category UUID — pass as category_ids when calling add_super_connector. name: Internal category name/slug. value label: Human-readable label for dropdown display. description: Short description of what this category represents. definition is_tracked parent_id type logo relationship_type: Category scope. Use entries with SUPER_CONNECTORS for the Super Connector add-member dropdown. order is_deleted: When true, exclude from dropdown options. meta created_at category_features IMPORTANT: If the response contains more than one record, always present the options to the user and ask them to choose before taking any follow-up action. Do not act on all results automatically.

get_workspace_categories

Get current_state for an intro request. TWO lookup modes — use exactly one, never mix fields across modes: (1) PREFERRED when intro_request_id is known: pass intro_request_id ONLY — omit target_id and requester_id. (2) Fallback when intro_request_id is unknown: pass target_id AND requester_id together — omit intro_request_id. INVALID (returns requester_id is required): intro_request_id + target_id without requester_id, or target_id alone. When intro_request_id is available, prefer search_intro_request with INTRO_REQUEST_SEARCH_FILTER_INTRO_REQUEST_ID instead. Use when: Use only when you need current_state only (not full details) and intro_request_id is unavailable (use target_id + requester_id), OR when intro_request_id is known pass intro_request_id alone. Do NOT call with intro_request_id and target_id together. If intro_request_id is known and you need full details or state, prefer search_intro_request over this tool. Behavior: read_only workspace_id / user_id are injected from request headers. Prerequisites (check before calling this tool): [REQUIRED] Lookup parameters must match one valid mode — mixed partial keys cause INVALID_ARGUMENT. Verify: Mode A: intro_request_id only. Mode B: target_id + requester_id (both required). Invalid: intro_request_id + target_id without requester_id. Invalid: target_id without requester_id. When intro_request_id is known, use search_intro_request instead.

intro_request_get_current_state

Return the complete intro request state machine transition graph. Each row is a directed edge: source_state → target_state, plus the event that triggers the move, which actor may fire it (ADMIN, REQUESTER, SYSTEM, REFERRER), action metadata, and event_label (human-readable). No input — returns the full graph in one call. To find valid next moves for a specific request: call intro_request_get_current_state first, then filter transitions where source_state equals that current_state and allowed_actor matches the caller's role. Use when: Use to understand the intro request lifecycle — which states exist and which events move from one state to another (e.g. DRAFT → INTRO_REQUESTED via INTRO_REQUESTED_EVENT, DRAFT → DISCARD_DRAFT via DISCARD_DRAFT_EVENT). Call before intro_request_send_state_change_event whenever you are unsure what transitions are legal from the request's current state. Pair with intro_request_get_current_state: current_state tells you where the request is; this tool tells you where it can go next. Behavior: read_only workspace_id / user_id are injected from request headers. Next steps (after this tool succeeds): [optional] [SUGGESTION] → call intro_request_send_state_change_event: After filtering edges from the request's current_state, fire the chosen event via intro_request_send_state_change_event. Returns transitions[] with fields: source_state: From-state — the intro request must be in this state for the transition to be valid. Match against current_state from intro_request_get_current_state. target_state: To-state — where the intro request lands after the event succeeds. event: Event enum to pass to intro_request_send_state_change_event to trigger this edge. action: Internal action identifier for this transition (informational). allowed_actor: Role allowed to fire this event. Only suggest transitions the current user's role can trigger. event_label: Human-readable label for this transition — use when presenting next-step options to the user. IMPORTANT: If the response contains more than one record, always present the options to the user and ask them to choose before taking any follow-up action. Do not act on all results automatically.

intro_request_get_state_machine_transitions

Fire a state machine event to move an intro request from its current state to a new state. Returns previous_state, current_state, and whether a transition occurred. Lookup: pass intro_request_id ONLY (preferred), OR target_id + requester_id together — never intro_request_id + target_id without requester_id. Only events valid for the request's current state will succeed — use intro_request_get_state_machine_transitions to see the full from→to graph. Use when: Use when the user wants to advance, submit, cancel, withdraw, or discard an intro request. Workflow when the valid next step is unclear: (1) intro_request_get_current_state → (2) intro_request_get_state_machine_transitions → filter edges where source_state equals current_state and allowed_actor matches the caller → (3) pick the matching event → (4) call this tool. Do not guess events — invalid events are rejected. Behavior: destructive workspace_id / user_id are injected from request headers. Prerequisites (check before calling this tool): [REQUIRED] Know the intro request's current state before firing an event. Verify: When intro_request_id is known, use search_intro_request with INTRO_REQUEST_SEARCH_FILTER_INTRO_REQUEST_ID + EQUALS. If using intro_request_get_current_state: pass intro_request_id ALONE — do not also pass target_id. Alternative lookup: target_id + requester_id together with no intro_request_id. Never pass intro_request_id + target_id without requester_id — the API returns INVALID_ARGUMENT. [REQUIRED] Confirm the event is a valid edge from the current state. Verify: Call intro_request_get_state_machine_transitions and find a transition where source_state == current_state, allowed_actor matches the user's role, and target_state matches the intended outcome. Use event_label to explain options to the user.

intro_request_send_state_change_event

List all uploaded files with metadata.

list_files

List stored LinkedIn engagement for a tracked person in a date range. Requires exactly one of keycloak_user_id OR linkedin_handle, plus start_date and end_date (yyyy-MM-dd). Returns a slim summary per activity: comment text (if any), post author's LinkedIn handle, when it happened, and interaction type. Read-only — does not scrape LinkedIn. Use when: Use when a trigger or user asks what LinkedIn posts someone commented on or reacted to in a date range. Prefer linkedin_handle when known. Reads stored history only. Behavior: read_only, idempotent Internal fields — available for follow-up tool calls but do NOT display to the user: `total_count`, `page`, `page_size`, `keycloak_user_id` Returns activities[] with fields: comment_text: Comment text when the activity is a comment; empty for reactions/likes. post_author_linkedin_handle: LinkedIn vanity handle of the person whose post was engaged with. activity_at: When the comment or reaction occurred. interaction_type: Type of engagement, e.g. comment or reaction. IMPORTANT: If the response contains more than one record, always present the options to the user and ask them to choose before taking any follow-up action. Do not act on all results automatically.

list_linkedin_engagement_activities

List the customer-defined tags available in this workspace for a given entity type, optionally narrowed to a name substring. Use when: Use before attaching or filtering by tags, to discover which tags exist and their ids. Behavior: read_only workspace_id / user_id are injected from request headers. Returns tags[] with fields: id name entity_type IMPORTANT: If the response contains more than one record, always present the options to the user and ask them to choose before taking any follow-up action. Do not act on all results automatically.

list_tags

List admin-managed trigger templates for the workspace (master + tenant). Returns id, name, description, instructions, enabled, trigger_kind (SCHEDULED|WEBHOOK), and metadata (including supported_events for WEBHOOK). Use a template's id as createWorkflowTrigger.template_id — never invent ids or event slugs. WEBHOOK templates are included only when the caller is OWNER, ADMIN, or SUPER_CONNECTOR_ADMIN in the workspace; other callers receive SCHEDULED templates only. Use when: Use when the user wants to browse or pick an admin template to create from, or when there is no workflow_trigger_template_context seed in the conversation. Call before createWorkflowTrigger so you can copy template_id, trigger_kind, and metadata.supported_events / metadata.preview verbatim. Prefer this over inventing WEBHOOK event slugs. If WEBHOOK templates are missing from the response, the caller lacks OWNER/ADMIN/SUPER_CONNECTOR_ADMIN — do not invent them. Not a substitute for listWorkflowTriggers (that lists live activations / catalog rows). Behavior: read_only workspace_id / user_id are injected from request headers. Returns templates[] with fields: id workspace_id name description instructions enabled created_at updated_at created_by_user_id trigger_kind: SCHEDULED or WEBHOOK. Passed through to createWorkflowTrigger when this template is used. metadata: Same shape as catalog metadata. Example: {"preview":{"slack":{"text":"..."},"email":{"subject":"...","html_body":"..."}},"supported_events":[{"integration_name":"hubspot","subscribed_events":["HUBSPOT_CONTACT_CREATED_TRIGGER"]}]}. WEBHOOK templates require supported_events. IMPORTANT: If the response contains more than one record, always present the options to the user and ask them to choose before taking any follow-up action. Do not act on all results automatically.

listTriggerTemplates

List a recipient's workflow triggers (catalog-based and agent-created), optionally filtered by lifecycle status. Returns id, catalog_id, name, description, prompt, schedule, and status. Use when: Use before creating a new trigger to avoid duplicates, or when the user refers to 'that reminder'/'my reminders' — match on name/description here, then update_workflow_trigger with trigger_id set to the row's id (config UUID). Empty id means an unactivated catalog template — activate via create_workflow_trigger with that catalog_id, not update. Behavior: read_only workspace_id / user_id are injected from request headers. Returns triggers[] with fields: name description enabled last_run_at last_run_status status prompt source id allowed_channels selected_channels cron recurring adhoc config_status plan channel_metadata agent_thread_id editable metadata test_mode test_cron test_lead_minutes test_recipients scope created_by created_by_user_name owner_user_id owner_user_name activation_mode principal_type catalog_id audience_type is_template audience_filter trigger_kind IMPORTANT: If the response contains more than one record, always present the options to the user and ask them to choose before taking any follow-up action. Do not act on all results automatically.

listWorkflowTriggers

Merge two workspace members who are the same person (e.g. a Super Connector added twice): everything the retired member has — relationships, connections, categories, tags, roles — moves onto the keeper, and the retired member is removed. Irreversible from chat. ALWAYS call first with dry_run=true: show the user the side-by-side comparison (both people's name, email, LinkedIn, roles and data counts) and every warning in plain language, and ask them to confirm which person to keep. Only after the user explicitly agrees, call again with the same keeper_user_id and retired_user_id, dry_run=false and confirm=true. Never merge on your own initiative, never skip the dry run, and never set confirm=true without the user's explicit agreement. If the outcome is MERGE_OUTCOME_REFUSED, explain refusal_reason plainly and do not retry. USER-FACING COPY: talk about people by name, never mention user ids, tool names or enum strings. Use when: Use only when an admin asks to merge, combine or de-duplicate two members of this workspace. Get both user ids from search_workspace_members first (by name, email or LinkedIn). The keeper is the member to keep (usually the one with more data or a login); the retired member must not have a login. Behavior: destructive workspace_id / user_id are injected from request headers. Prerequisites (check before calling this tool): [REQUIRED] Both keeper_user_id and retired_user_id are known and belong to members of this workspace. Verify: Call search_workspace_members and take user_id from the two matching rows. Never guess ids. [REQUIRED] A dry run was shown to the user and they explicitly agreed to the merge. Verify: Only call with dry_run=false after a dry_run=true call in this conversation and an explicit 'yes' from the user. Also returns pagination info (user_id, member_id, name, email, linkedin_id, role, data_counts, has_login).

merge_workspace_members

Preview how many companies and people match a SearchPeopleRequest at each funnel stage (companies -> current employees -> +seniority -> +title keywords -> +person location), without running the final search. Same anchor/filter fields as search_people_by_location_and_seniority. Use this to show the user what each filter is doing before committing to the final query, especially after adding or loosening a filter. Use when: Use whenever the user is refining a search interactively — after every new filter (region, seniority, title keywords, company set) — to show the funnel counts and let them see which parameter is truncating the result set. Do not use as a substitute for the final search_people_by_location_and_seniority call. Behavior: read_only, idempotent Returns stages[] with fields: label company_count people_count by_seniority top_locations top_titles basis sampled_rows IMPORTANT: If the response contains more than one record, always present the options to the user and ask them to choose before taking any follow-up action. Do not act on all results automatically.

preview_people_query

Query agent content by slug, natural language query, family (SKILL, MEMORY), tags, or scope. Use for on-demand skill retrieval or finding memories. Use when: Use when the agent needs to load a specific skill by slug or search for content not already injected in the runtime bundle. Behavior: read_only workspace_id / user_id are injected from request headers. Returns results[] with fields: content score match_reason IMPORTANT: If the response contains more than one record, always present the options to the user and ask them to choose before taking any follow-up action. Do not act on all results automatically.

query_content

Read an uploaded file's contents by name.

read_file

Get the current state of a referrer request by target_id with optional requester_id or referrer_id (workspace member with SUPER_CONNECTOR role) filters. Returns ReferrerRequestState and whether a matching request was found. Use when: Use before SendStateChangeEvent when you need to check current state and do not have referrer_request_id. Prefer GetReferrerRequestForReferrerById when you have the referrer_request_id. Behavior: read_only workspace_id / user_id are injected from request headers.

referrer_request_get_current_state