MCP App Store
by KeenEthics
UserGems icon

UserGems MCP Server for ChatGPT

By UserGems

Overview

Build outbound and ABM campaigns with UserGems and AI agents inside ChatGPT. Build audiences, find buying signals, and orchestrate sales outreach and advertising audiences. Reps can surface their hottest prospects, research target accounts, and draft personalized outreach.

How to connect

  1. ChatGPT: Open the UserGems listing in the ChatGPT app directory and choose Connect. ChatGPT listing UserGems exposes 141 tools here.

Tools

campaign_get_crm_default_settings

ChatGPT
Returns the workspace defaults a "Create or Update Record in CRM" campaign action inherits when it does not override them: at_create_type (+ label), default_owner (id and resolved name), account_owner, assign_owner_if_lead_or_contact_already_exists, webhook_url, and crm_field_defaults (the current CRM field mapping per object). Useful before adding a create_or_update_prospect_in_salesforce or account-only create_or_update_account_in_crm action, to show the user the defaults before asking about custom settings. crm_field_defaults is also the starting point for a partial crm_field_configs override. Read-only.

campaign_list_bing_audiences

ChatGPT
Lists available Bing Ads audiences for use in a "Sync to Bing Ads Audience" action. Useful when the user wants to sync prospects to an existing Bing audience. Returns audience IDs and names, plus the connection_id of the ad account each belongs to; the sync action takes that connection_id when the workspace has more than one Bing account; the account used is worth naming to the user. If none are found, the user can create a new audience instead.

campaign_list_crm_object_fields

ChatGPT
Lists CRM fields for a given object type: name, label, type. Salesforce: "Account", "Opportunity", "Contact", "Lead", "Task". HubSpot: "contact", "company".

campaign_list_crm_user_lookup_fields

ChatGPT
Lists CRM fields that reference User/Owner objects. Salesforce: Account, Contact, Lead. HubSpot: Company, Contact. Use for "Assign owner" action (field_to_update) and for "Add CRM Task" when assign_owner_type is "user_field".

campaign_list_crm_users

ChatGPT
Lists CRM users (Salesforce/HubSpot) for the company. Use this to resolve user emails to CRM IDs for assign owner, Add CRM Task, or Slack notification actions.

campaign_list_google_audiences

ChatGPT
Lists available Google Ads audiences for use in a "Sync to Google Ads Audience" action, across every connected Google Ads account. Each audience carries the connection_id and account_name of its account, and the response also lists the accounts. Audience IDs are unique only within an account, so the sync action needs that connection_id when the workspace has more than one; omitting it binds the sync to whichever account resolves first. The account used is worth naming to the user. If none are found, the user can create a new audience instead.

campaign_list_linkedin_audiences

ChatGPT
Lists available LinkedIn audiences for use in a "Sync to LinkedIn Audience" action, across every connected LinkedIn ad account. Each audience carries the connection_id and account_name of its account, and the response also lists the accounts. Audience IDs are unique only within an account, so the sync action needs that connection_id when the workspace has more than one; omitting it binds the sync to whichever account resolves first. The account used is worth naming to the user. If none are found, the user can create a new audience instead.

campaign_list_meta_audiences

ChatGPT
Lists available Meta audiences for use in a "Sync to Meta Audience" action, across every connected Meta ad account. Each audience carries the connection_id and account_name of its account, and the response also lists the accounts. Audience IDs are unique only within an account, so the sync action needs that connection_id when the workspace has more than one; omitting it binds the sync to whichever account resolves first. The account used is worth naming to the user. If none are found, the user can create a new audience instead.

campaign_list_sep_sequences

ChatGPT
Lists the SEP sequences (Outreach or HubSpot), cadences (Salesloft) or flows (Gong) in the workspace, and with format "full", what one contains. Useful before adding an "Add to Sequence" action, to find sequence IDs and names, and with format "full" when the user describes a sequence shape ("a 6-step sequence with a LinkedIn connect and a call brief") rather than naming one. In "full" each step's type matches the message type Gem-E generates (email, linkedin_message, linkedin_connection_request, call_briefing, manual_task; null when the provider reports a type that cannot be classified, read provider_step_type then), messageType is new_thread or reply, and delayAfterDays is the wait after that step. templated_steps is every step needing Gem-E content; comparing it with how many messages the campaign's Writing Agent step generates shows whether the sequence would run with blank or unused steps, in which case the user is best pointed to the Add to Sequence action in the campaign builder. templated_email_steps is a breakdown for context, since Gem-E also writes LinkedIn messages, connection requests and call briefings. The compact list returns up to 25 matches by default; data reports returned, total_matching and truncated (there is no total). When truncated, narrowing with search costs fewer tokens than raising limit. Read-only: only the user can create or edit a sequence, in Outreach, Salesloft, Gong or HubSpot. HubSpot enrolls existing CRM contacts with the selected sender. Existing enrollments support skip or stop (default stop). Owner reassignment explicitly changes the HubSpot CRM contact owner and defaults to false. Removal and pause require manual repair in HubSpot before retrying. Full sequence step details are available through campaign_list_sep_sequences with format "full". Writing Gem-E values to HubSpot contacts is unavailable. For HubSpot, templated_steps counts each step with a template once, and required_properties lists the subject/body contact properties from the company's Engagement mapping that active templates reference; an action with its own mapping can read other properties. Other contact tokens are ignored by Gem-E validation. Inspection uses the designated Sequences user and does not establish sender access.

campaign_list_slack_channels

ChatGPT
Lists Slack channels for the company. Use this when send_to is slack_channel to get channel IDs for Slack notification actions.

campaign_list_slack_users

ChatGPT
Lists Slack users for the company. Use this to get Slack user IDs for @mentions in Slack notification messages.

campaign_select_crm_user_field

ChatGPT
Presents a selection widget for the user to choose a CRM field that references User/Owner objects. Useful when owner_type is "user_field" in an Add to Sequence action. Takes object_type (Salesforce: Account, Contact, Lead; HubSpot: Company, Contact); waits for the user to pick before continuing.

campaign_select_sep_sequence

ChatGPT
Presents a selection widget for the user to choose an SEP sequence (Outreach, Salesloft, Gong, HubSpot). Use this instead of campaign_list_sep_sequences when the user needs to choose a sequence while building a campaign: the user picks it interactively. The picker carries at most limit options (50 by default) plus total_matching and truncated, not the whole catalog. What the search box can reach depends on the client: the MCP app re-queries this tool as the user types, while the in-app widget only filters the options already sent and cannot reach anything past the limit; a narrower search reaches a sequence not shown. campaign_list_sep_sequences returns sequence ids as data instead, for a lookup, a shape check, or a client that cannot render a picker, and with format "full" is the only way to read what a sequence contains. HubSpot enrolls existing CRM contacts with the selected sender. Existing enrollments support skip or stop (default stop). Owner reassignment explicitly changes the HubSpot CRM contact owner and defaults to false. Removal and pause require manual repair in HubSpot before retrying. Full sequence step details are available through campaign_list_sep_sequences with format "full". Writing Gem-E values to HubSpot contacts is unavailable.

campaign_select_sequence_owner

ChatGPT
Presents a selection widget for the user to choose a SEP user (Outreach, Salesloft, Gong, HubSpot). Useful when owner_type is "specific_user" in an Add to Sequence action. Waits for the user to pick before continuing. HubSpot enrolls existing CRM contacts with the selected sender. Existing enrollments support skip or stop (default stop). Owner reassignment explicitly changes the HubSpot CRM contact owner and defaults to false. Removal and pause require manual repair in HubSpot before retrying. Full sequence step details are available through campaign_list_sep_sequences with format "full". Writing Gem-E values to HubSpot contacts is unavailable.

campaign_update_action_create_gem_e_messages

ChatGPT
Vocabulary: "Writing Agent" is the UserGems name for Gem-E message generation. Inside a campaign it is the create_gem_e_messages action - the campaign builder labels that step "Writing Agent"; outside a campaign it is the company-level Writing Agent page holding the shared messaging instructions. "Writing Agent", "the writer", "writing agent step" and "writing agent instructions" all refer to this. Which campaign is meant (or whether it is company-wide) is a separate scope question. Saves new campaign messaging instructions for the "Generate AI messages" action. Useful when the user wants to update instructions for a specific campaign. get_latest_campaign_messages_generator_instructions returns the latest draft when one exists, plus its chat_message_id and is_draft; the prompt in workflow_actions context only reflects the published version and is not the baseline when a draft exists. When is_draft is true, this tool expects the change amended from that draft, with its chat_message_id passed as based_on_chat_message_id - the call is rejected otherwise. When a campaign has multiple Create Gem E Messages actions, pass workflow_action_id to pick one. Generation applies the campaign and company-wide instructions together, so before saving, compare the new prompt against company_wide_published_prompt (also returned by get_latest_campaign_messages_generator_instructions). Where a campaign rule contradicts a company-wide rule on tone, structure, language, length, formatting or content, end that rule with the tag "[Override Company Instruction]". Rules that only add detail on top of the company-wide instructions need no tag. Outside the in-app chat (e.g. MCP), address the action with workflow_action_id or campaign_id and omit workflow_action_uuid/action_index. The change is saved as an unpublished draft at the tip of the instruction chain and does not affect generation until it is published: usergems_mcp_publish_instructions publishes it, and usergems_mcp_discard_instruction_draft drops it. This tool replaces the entire prompt: unchanged parts of the existing prompt need to be reproduced character for character, keeping en/em dashes, quotes, HTML markup, punctuation and whitespace exactly as they are. In the in-app chat, the workflow_actions in context belong to the campaign open on the page (context.currentPage "campaign"); another campaign is reached through navigate_to_page first. An instruction request made in the company-level Writing Agent chat is company-wide unless that request itself names a specific campaign (one named in earlier turns does not count); update_company_messages_generator_instructions covers that case. Saving only creates a draft, so it needs no request_confirmation step; the returned widget lets the user preview, view or publish the change. After saving, reply short: show only the bullets you added, never the full prompt, and remind the user to review the full prompt before going live. Outside the in-app chat (e.g. MCP), call usergems_mcp_instructions_playbook first and follow it, and only call this tool after the user has seen the exact change and said yes to saving it.

content_create

ChatGPT
Creates a new Gem-E/Writer Agent content item and saves exactly the values passed. The item is saved immediately and created deactivated: it isn't used in messages until it's activated, in the UI or with content_toggle_active. No need to navigate to the content or campaign page first when already there. In a campaign context the item can be scoped to the current campaign (its workflow_id in workflow_ids) or left global (no workflow_ids); that choice is the user's. Outside the in-app chat (e.g. MCP), call the playbook for the item's type first and follow it: usergems_mcp_case_study_playbook, usergems_mcp_new_feature_playbook, usergems_mcp_link_playbook, usergems_mcp_value_proposition_playbook, usergems_mcp_email_template_playbook, or usergems_mcp_conditional_instructions_playbook; for a writing rule, usergems_mcp_instructions_playbook. Only call this after the user has seen a preview of the exact values to be saved (type, name, text, messaging instructions, filters, dates, campaigns) and said yes to saving them. A request to add something is not that yes. Leave messaging_instructions empty unless the user gave guidance on how to use the item, and keep their wording when they did. Never save an end_date without a start_date (today unless the user gives one), and never use a release or publish date from the source as the start_date. When saving an in-app content generator's output, name is only the value after "Name:" and description is only what comes after "Description:", with line breaks kept. The labels "Name:" and "Description:" are delimiters and never part of the saved value. For a Conditional Instruction, everything under "Description:", including an "Inline-Conditional Behaviors:" part, goes into description.

content_edit

ChatGPT
Edits an existing GemE content item. Useful when the user wants to modify existing content. The edit is applied and saved immediately; the returned card offers Preview messaging, View in library and Publish (which activates the content). Also used to personalize a signal playbook: pass the final instruction text (rewritten by the sub-agent or the caller) in instructions, and the tool saves it as-is to the playbook's messaging_instructions with no AI generation of its own. The user's message is rewritten into a clean instruction first, keeping only quoted copy the prospect will read (a fixed P.S., a tagline, a URL) exactly as written, rather than pasted word for word. To add, replace or clear filter conditions on the content (including on signal playbooks), build the conditions from the fields in usergems_mcp_audience_filter_instructions (real values from list_filter_field_values) and pass them as filter_conditions together with filter_conditions_mode. When only filters change, pass an empty string for instructions so existing personalization text is preserved. To turn a content item on or off (activate, deactivate, pause, enable, disable), pass is_active - a pure toggle skips the AI rewrite and returns instantly. When only specific fields should change, pass fields_to_edit (allow-list of name, description, link, messaging_instructions); any field not listed is left untouched by the save rather than regenerated, which avoids stale or hallucinated copy on omitted fields. When a field should be removed or wiped (e.g. "remove the link", "clear the messaging instructions"), pass fields_to_clear with the field name; the save blanks that column and the AI rewrite is skipped for it. Field mapping per content type (the UI label the user speaks in, translated to the PATCH field name): - case_study: description = "Case study" body, messaging_instructions = "Messaging instructions", link = "Link" URL. - sample_email: description = "Email template", messaging_instructions = "Messaging instructions" (no link field). - new_feature: description = "Description", messaging_instructions = "Messaging instructions", link = "Link". - link: description = "Description", messaging_instructions = "Messaging instructions", link = the actual URL. - conditional_instructions: description = "Content" (no messaging_instructions, no link). - value_proposition: description = "Value proposition" text, messaging_instructions = "Persona pain points" text, link = "Link". Examples: "Update the case study body" -> fields_to_edit: ["description"]. "Change the link to X" -> fields_to_edit: ["link"]. "Generate pain points" on a value_proposition -> fields_to_edit: ["messaging_instructions"]. Scoping the AI rewrite to the exact fields named keeps it from rewriting a field the user did not ask about. If the item's name mentions something the edit changes - an email position ("First Email", "Email 1", "Breakup Email"), a target group ("VPs", "Enterprise"), a competitor or tool ("HubSpot"), or a behaviour ("Executive Summary") - pass the new name in the same call. Example: "Executive Summary - First Email" moved to email 4 becomes "Executive Summary - Email 4". A generic name the edit does not touch stays; an explicit rename request always wins. Before editing a signal playbook, call usergems_mcp_signal_playbook_guidance_playbook; before editing a conditional instruction or value proposition, call its playbook (usergems_mcp_conditional_instructions_playbook, usergems_mcp_value_proposition_playbook). For a writing rule, call usergems_mcp_instructions_playbook first. When a user asks for this in chat, never save without showing them a preview and getting a yes.

content_get_matching_for_prospect

ChatGPT
Fetches and returns relevant context and information about your company to use for email generation (value proposition, case studies, features, links, etc.) that match a specific prospect's profile.

content_list

ChatGPT
Lists GemE content items or retrieves a specific item by id or name. Use with id or name to fetch full details of a single content item. Use without id/name to list all contents (metadata only). Supports filtering by content type and active status.

content_toggle_active

ChatGPT
Activate or deactivate a GemE content item by toggling its is_active flag. Content is created deactivated; activating it, in the UI or here at the user's request, is what lets messaging use it. Use this when the user wants to enable (re-activate) a deactivated content item, or disable an active one. Does NOT delete the content. Pass is_active=true to activate, false to deactivate. Signal Playbook entries are excluded and cannot be toggled through this tool. Only call this after the user clearly asks to publish or turn an item on or off.

crm_query_salesforce

ChatGPT
Runs a read-only SOQL query against the company's Salesforce. Allowed objects: Account, Contact, Lead, Opportunity, OpportunityContactRole, CampaignMember, Task, User, EntityDefinition, and the UserGems custom object (UserGem__UserGems__c or UserGems__UserGems__c); other objects are rejected. campaign_list_crm_object_fields returns the field names to use. Salesforce only. Maximum 100 records per query.

fetch_prospect_matching_content

ChatGPT
Fetches rendered content of a specific type (case study, new feature, link, sample email, value proposition, or conditional instructions) that matches a prospect's profile. The content is fully parsed and rendered as it would appear during message generation.

fetch_prospect_messaging_data

ChatGPT
Fetches the rendered prospect messaging data including all prospect fields, signals, and company instructions formatted as they would appear during message generation. Use this to understand a prospect's profile before generating messages.

generate_filter_conditions

ChatGPT
Generates filter conditions from a natural language description. Use this to create conditions before applying them with campaign_set_audience, campaign_set_action_payload_conditions, or content tools (content_create, content_edit, content_generate). Each returned condition carries the catalog field and, for fields whose values are ids (persona, company list, relationship type, owner), the ids rather than the names, so it can be passed on as is.

get_latest_campaign_messages_generator_instructions

ChatGPT
Vocabulary: "Writing Agent" is the UserGems name for Gem-E message generation. Inside a campaign it is the create_gem_e_messages action - the campaign builder labels that step "Writing Agent"; outside a campaign it is the company-level Writing Agent page holding the shared messaging instructions. "Writing Agent", "the writer", "writing agent step" and "writing agent instructions" all refer to this. Which campaign is meant (or whether it is company-wide) is a separate scope question. The response also carries company_wide_published_prompt (the published company-wide instructions), so cross-level comparison needs no extra call. Returns the current campaign-level messaging instructions: the prompt of the campaign's "Generate AI Messages" action (latest draft if one exists, otherwise the latest published version), with its chat_message_id and is_draft flag. Useful before proposing or saving changes: when is_draft is true, campaign_update_action_create_gem_e_messages expects the change amended from the returned prompt (not the payload prompt in the workflow_actions context), with the chat_message_id echoed as based_on_chat_message_id. When chatting inside a campaign, omit campaign_id to use that campaign; otherwise pass campaign_id (see usergems_mcp_campaign_list_workflows) or omit it to ask the user to pick a campaign.

get_latest_company_messages_generator_instructions

ChatGPT
Vocabulary: "Writing Agent" is the UserGems name for Gem-E message generation. Inside a campaign it is the create_gem_e_messages action - the campaign builder labels that step "Writing Agent"; outside a campaign it is the company-level Writing Agent page holding the shared messaging instructions. "Writing Agent", "the writer", "writing agent step" and "writing agent instructions" all refer to this. Which campaign is meant (or whether it is company-wide) is a separate scope question. Returns the current company-wide messaging instructions: the latest draft when one exists (with its chat_message_id and is_draft=true), otherwise the latest published version. Useful before proposing or saving changes: when is_draft is true, update_company_messages_generator_instructions expects the change amended from the returned prompt, with the chat_message_id echoed as based_on_chat_message_id.

get_matching_prompt_blocks_for_prospect

ChatGPT
Returns the Ai Workflow prompt blocks whose filter conditions match the given prospect. Use this to assemble the conditional per-prospect prompt from the blocks authored in the Ai Workflow Gem-E feature settings. Returns a flat list of blocks in authoring order; each entry includes id, name, and prompt.

list_filter_field_values

ChatGPT
Returns the real, valid values of one filterable field, useful before writing a literal value into a filter condition. Values are workspace-specific stored labels, not the codes you might guess: seniority, department, industry, sub-industry and CRM picklists are typical cases, where a literal like VP or Enterprise will not match the stored label. Country is the classic example (stored as United States, not US), but country fields are already preloaded with their values, so this tool covers the other fields listed above instead. Region labels (EMEA, APAC, Europe, North America) are also valid values on country fields. Fields flagged vals: true in usergems_mcp_audience_filter_instructions are the ones this tool answers for; fields that already carry preloadData (including country) need no call. A truncated response returns only part of the list, so a not_in_list condition built from it would be incomplete.

update_company_messages_generator_instructions

ChatGPT
Vocabulary: "Writing Agent" is the UserGems name for Gem-E message generation. Inside a campaign it is the create_gem_e_messages action - the campaign builder labels that step "Writing Agent"; outside a campaign it is the company-level Writing Agent page holding the shared messaging instructions. "Writing Agent", "the writer", "writing agent step" and "writing agent instructions" all refer to this. Which campaign is meant (or whether it is company-wide) is a separate scope question. Saves new company-wide messaging instructions for the email/message generator. get_latest_company_messages_generator_instructions returns the latest draft when one exists (the baseline for the change) plus its chat_message_id and is_draft. When is_draft is true, this tool expects that prompt amended, with its chat_message_id passed as based_on_chat_message_id - the call is rejected otherwise. This tool replaces the entire prompt: unchanged parts of the existing prompt need to be reproduced character for character, keeping en/em dashes, quotes, HTML markup, punctuation and whitespace exactly as they are, with no typography normalization or reformatting. The change is saved as an unpublished draft and never published directly. In the app, the widget shown after saving lets the user preview, view or publish it. Outside the app (e.g. MCP), usergems_mcp_draft_prospect_email with preview_instructions_chat_message_id set to this draft and no campaign_id previews it on prospects from usergems_mcp_fetch_prospects_and_accounts; usergems_mcp_publish_instructions publishes it, and usergems_mcp_discard_instruction_draft drops it so no later edit builds on a rejected draft. A company-level preview is indicative, not exhaustive: its prospects come from the workspace at large rather than any one campaign audience, and the change lands on every campaign. After saving, reply short: show only the bullets you added, never the full prompt, and remind the user to review the full prompt before going live. Before saving, call usergems_mcp_company_instructions_playbook and follow it. Never save without showing the user the change and getting a yes.

usergems_mcp_account_ui_card_playbook

ChatGPT
Returns the rendering rules and inline company-card layout for presenting account information: summary, signals, past conversations, recommended prospects, or deal history. Useful before an answer built from tools such as usergems_mcp_get_company_account_details, usergems_mcp_get_account_signal_history, usergems_mcp_past_interactions_rag, usergems_mcp_fetch_prospects_and_accounts, or usergems_mcp_company_ai_research.

usergems_mcp_add_accounts

ChatGPT
Adds one or more companies to a UserGems list - by list id, by list name, or under a company signal - with no spreadsheet, no Salesforce report and no Google Sheet. Useful when the user names companies directly in chat ("add Acme to my Targets list", "put these 5 companies in a list called X"). Naming a list that does not exist yet creates it on first use. Takes up to 500 records per call and queues them through the same import pipeline a file import uses; the import runs in the background and the result shows in Settings under Track companies. usergems_mcp_import_accounts_report is for when the user has a file instead.

usergems_mcp_add_contacts

ChatGPT
Adds one or more people to a UserGems contact list, with no spreadsheet, no Salesforce report and no Google Sheet. Useful when the user names contacts directly in chat ("add jane@acme.com as a champion", "track these 3 people"). Naming a relationship type that does not exist yet creates it on first use. Takes up to 500 records per call, each with at least an email, and queues them through the same import pipeline a file import uses; the import runs in the background and the result shows in Settings under Track contacts. usergems_mcp_import_contacts_report is for when the user has a file instead.

usergems_mcp_amplification_playbook

ChatGPT
Useful when the user wants to layer Slack alerts, ad-audience sync (LinkedIn / Google / Meta / Bing / AdRoll), or gifting on top of a campaign, existing or new. Branches on layer and returns the per-layer probing questions plus the action snippet to inject into the campaign's actions[]. The gifting branch is stubbed until the Sendoso integration ships.

usergems_mcp_audience_filter_instructions

ChatGPT
Returns the audience-filter schema an AI model needs to generate JSON filter conditions for prospects and accounts. Four levels, fetch only what is needed: (1) include_sections: ["instructions"] for the output contract and value-shape rules, stable per workspace, fetch once per journey then drop it. (2) include_sections: ["catalog"] for every filterable field in the workspace, grouped, name/label/type only; field_filter or groups narrow it. (3) describe: ["field.name", ...] for the full spec of the 3-8 fields picked: description, operations, options, preload data, value shape. (4) value_search: ["Closed Lost"] when the user named a value rather than a field: it returns the field that holds it. list_filter_field_values gives the real values of an open-ended field. The catalog is complete: if a filter exists in the UI, it is in here. To keep the conditions as a standalone saved audience with no campaign (for example "build me a marketing audience and save it"), usergems_mcp_save_audience takes conditions and a name and no audience_id, and returns audience.id and audience_url.

usergems_mcp_audit_company_icp_fit

ChatGPT
Answers "why isn't this company in my audience?". Takes one company already tracked in the workspace and reports, for each ICP, whether it fits and which criterion excludes it - criteria lists every criterion with the ICP's value next to the company's, and failing names the ones it misses. The verdict comes from the same matching query the account imports and the enrichment run use, so it agrees with what an ICP audience will really contain. Also returned: stored, the ICP ids the last enrichment pass wrote on the account - that is what audiences filtering on isICPAccount / icpIds actually read - and stale: true when those disagree with the live check, which means the account simply has not been enriched since the ICP changed. When explanation_complete is false, the breakdown could not confirm the verdict, so only the raw values are available, not a reason. usergems_mcp_edit_icp widens the excluding criterion. The company must already be in UserGems: auditing an arbitrary outside domain is out of scope, since there is no company data to match against. Pure read.

usergems_mcp_audit_persona_match

ChatGPT
Answers "why isn't this person in my persona / audience?" - takes a job title or someone already in the workspace and reports, per persona, whether they match and what keeps them out: which keyword group hit, which excluded keyword removed it, which words the strict setting rejected, and whether the country and industry rules pass, including their missing-value choices. The verdict comes from the same code the background matching runs, so it agrees with what a persona audience will really contain. best_persona is the one the person is assigned to when several match. stored is what the audiences read today; when it disagrees with the live verdict, stale is true and the prospect simply has not been re-matched since the persona changed - that pass runs about 15 minutes after a save. hint names the one change that would fix it and the tool that makes it, which is usergems_mcp_edit_persona. Useful before proposing a persona edit for a "missing people" complaint. Pure read. The person has to be in UserGems already; to check an arbitrary job title, pass title on its own.

usergems_mcp_await_import_upload

ChatGPT
Waits for the spreadsheet the user is uploading through the usergems_mcp_import_upload dropzone. Pass the upload_token that tool returned. Blocks up to ~45 seconds; returns {status: 'uploaded', upload_id, headers, sample_row} once the file lands, or {status: 'waiting'} while the user has not finished, checked again by calling with the same token. Returns {status: expired} once the upload window closes without a file; a fresh call to usergems_mcp_import_upload opens a new dropzone.

usergems_mcp_campaign_compare

ChatGPT
Compares two campaigns (workflows) by id and returns a structured diff across four dimensions: (1) audience - same filter and semantically-equivalent conditions; (2) action sequence - same ordered action types and timing; (3) per-action payloads - which steps differ (email body, slack target, CRM fields); (4) status & schedule - active, owner-assignment, the assign-owner roster (assign_owner_membership: assign_type and assign_user_ids per rule, so two campaigns that both assign an owner but rotate through different people are reported as differing), schedule and limits. Read-only. Both campaigns must belong to the user's account; job-change campaigns are not supported. Use this to explain how two campaigns differ.

usergems_mcp_campaign_get_detail

ChatGPT
Returns full detail for one campaign (workflow) by id, in five sections: (1) audience - the filter_id and filter conditions; (2) action_sequence - ordered action types with timing/delays; (3) action_payloads - email subject/body, slack target, CRM fields; (4) status_schedule - active state, owner assignment, schedule, sending limits, and branches - one entry per branch (outbound / marketing) with its own schedule and its own filter in branches[].conditions; (5) recent_runs - run history keyed by agent type ('outbound'/'marketing'), each with latest_workflow_log and latest_workflow_run ({started_at, finished_at, successful, failed, skipped, type, ...}). Sections 1-4 describe configuration only; recent_runs is the source for whether and when the campaign ran. latest_workflow_run.started_at gives the last run time; latest_workflow_log's successful/failed counts show whether it is working (latest_workflow_run is the most recent run of any kind, latest_workflow_log the most recent run that processed records, so they differ when recent runs matched nobody). A run with started_at and no finished_at is still in flight. The updated_at from usergems_mcp_campaign_list_workflows is the last config edit, not a run, and can be months old for a campaign that runs daily. An empty or absent recent_runs for an agent type means no run history is available, not that the campaign is inactive. Every assign_owner step in action_payloads also carries assign_owner.payloads[]: one entry per configured rule, in evaluation order (the first rule whose conditions match wins), with the same field names as an owner_payloads entry of usergems_mcp_create_campaign / usergems_mcp_edit_campaign: payload_name, conditions, assign_type (dri | specific_user | specific_user_round_robin | user_field), assign_user_ids (the round-robin roster, or the single owner for specific_user), assign_crm_object/assign_crm_field (the CRM lookup the owner is read from when assign_type is user_field), field_to_update_crm_object/field_to_update_crm_field (where the owner is written) and fallback_owner_user_ids. The roster of the campaign's active assign_owner steps is repeated under status_schedule.assign_owner_membership (one entry per rule, with the order of its step), so who is assigned or in the round robin can be answered from the status_schedule section alone. assign_user_ids are CRM user ids; campaign_list_crm_users resolves them to names. Reading membership needs only this tool, not usergems_mcp_edit_campaign. A campaign filters prospects in four places, and "the filter on this campaign" can mean any of them: (1) audience.conditions, the shared audience several campaigns can point at; (2) status_schedule.branches[].conditions, the per-branch filter that the campaign builder shows as "Outbound Filters" and "Marketing Filters", applied on top of the audience when that branch runs; (3) action_payloads[].payload.conditional_variants[].conditions, the condition block on a step (the builder's Try/Then); (4) action_payloads[].payload.payloads[].conditions, the CRM payload conditions of a step. Levels 3 and 4 live inside action_payloads, so a question about where a field is filtered on - which campaigns filter on it, where it is set to false, an audit of the conditions - is answered from all four, with action_payloads among the requested sections; an answer drawn from the audience and the branches alone reports a campaign as clean while the condition sits on one of its steps. conditions is null on a branch with no filter of its own. usergems_mcp_edit_campaign changes a branch filter through branches and a step's condition block through condition_updates. Read-only. The campaign must belong to the user's account; job-change campaigns are not supported.

usergems_mcp_campaign_list_workflows

ChatGPT
Lists workflows/campaigns for the company with rich filters. Supports partial name search (case-insensitive LIKE), active/inactive filter, audience filter, created_at window, and ordering. Returns id, name, active, audience ({id, name}, or null when the audience row was deleted), created_at, updated_at, and actions_count per row. Use this from the usergems_mcp_edit_campaign flow to resolve user references like "my last campaign", "the Pendo one", or "the campaign I created yesterday". After listing, use usergems_mcp_campaign_get_detail for a single campaign's full config, or usergems_mcp_campaign_compare to diff two campaigns. For "which campaigns use/do X" questions (signals, audience filters, action types), use usergems_mcp_campaign_search instead - with usergems_mcp_campaign_search_vocabulary first for the tenant's vocabulary - rather than listing everything. search matches campaign names only - to find an audience by name use usergems_mcp_list_audiences, which also sees audiences no campaign uses. The audience on each row plus the audience_id filter answers the reverse question, "which campaigns use this audience?" - the check that applies before editing an audience with usergems_mcp_save_audience.

usergems_mcp_campaign_search_vocabulary

ChatGPT
Returns the words this company's campaigns actually use: the signal names (with categories) referenced by campaign audience filters, the filter field keys in use, and the workflow action types in use. Useful before usergems_mcp_campaign_search, to translate the user's question into the tenant's own words - e.g. "contact-level intent" may correspond to a signal named "Website Visitors" with category website_visitor - then pass those words to usergems_mcp_campaign_search (and action types to its action_types parameter). This is the in-use vocabulary computed from the campaigns themselves, not the universe of available signals and fields; for every tenant signal with descriptions and use-case hints, use usergems_mcp_audience_filter_instructions with include_sections ["signals"].

usergems_mcp_case_study_playbook

ChatGPT
Useful when the user wants to add, import, or summarize customer case studies or customer stories for the Gem-E content library: a case study URL, a customers/case-studies directory page, an uploaded file with one or more stories, or pasted text. Call this BEFORE content_generate or content_create for any case study. This includes text the user pastes and asks to add or save as is: content_create saves exactly what it is given, so pasted text still goes through this playbook first to be put in the library format and previewed. It sets the required case study format for the Gem-E library, even if the user has their own case study skill. Returns the procedure: read the source with your own tools, write each story in the standard format, suggest an industry filter, preview, get one confirmation, then save exact values with content_create.

usergems_mcp_check_account_type_populated

ChatGPT
Canonical resolver for 'does this workspace have accounts tagged as <account_type>?'. Used before assembling a conditions block that filters on emailJob.company.accountType, in usergems_mcp_signal_campaign_branch_playbook branches (closed_lost_revive, multi_thread, competitor_takedown) that treat accountType as an optional overlay on signal-based scoping. When populated=false, the overlay would yield a 0-count audience, so signal-based scoping is the only option (see use_case_hint in usergems_mcp_audience_filter_instructions). Returns {account_type, populated, count, hint}. Read-only; safe to call multiple times per session. Scoped to the caller's company_id.

usergems_mcp_clone_campaign

ChatGPT
Clones an existing UserGems campaign into a NEW inactive draft. Useful for the common CSM patterns the usergems_mcp_signal_campaign_playbook documents — past-champions namedrop vs generic split, US/ROW region split, A/B testing the same flow with a different sequence — where you want a near-copy of an existing campaign with a few changes instead of rebuilding from scratch. Pass source_campaign_id and a new new_name; optionally override any of description, audience_conditions, schedule, or actions (full replacement). Any override you omit or send as null is copied verbatim from the source. The new campaign is inactive draft (the source is not modified). Caveat: if the source campaign has any action whose type is not yet supported by the create/edit MCP surface, the clone refuses — pass an actions override to replace the action list entirely, or edit the source in the app first.

usergems_mcp_clone_persona

ChatGPT
Copies a persona, keyword groups and all - the persona list page's duplicate button. This is how a user starts a variant: clone "Revenue Leaders", then narrow the copy with usergems_mcp_edit_persona. The copy keeps the original's criteria, importance and strict setting; it is a new persona, so nothing about the original changes. Without a new_name the copy is called "<name> (Copy)", exactly what the button produces. Like every other persona write, it needs confirm: true: without it the tool writes nothing and returns the source and destination names for review. The response includes the new persona's id and its edit URL.

usergems_mcp_company_instructions_playbook

ChatGPT
Useful when the user wants to add, change, or remove a rule in the company-wide Gem-E instructions (the Writing Agent page), which apply to every email in every campaign, or when usergems_mcp_instructions_playbook sends a company-wide rule here. Call this BEFORE update_company_messages_generator_instructions, usergems_mcp_publish_instructions, or usergems_mcp_discard_instruction_draft for company instructions. Returns the procedure: check for unpublished changes and ask about them, judge each rule against Gem-E defaults and the current lines, preview only the lines that change, save as a draft on a yes, check that nothing else changed, offer a before-and-after preview email, and publish only on a separate yes. Use it when the request is tied to UserGems: the user names UserGems, Gem-E, the Writing Agent, or the company-wide instructions, or the conversation is already about their UserGems setup. Not for rules meant for another connected tool or for how you write yourself.

usergems_mcp_conditional_instructions_playbook

ChatGPT
Useful when the user wants a writing rule for a group of prospects in the Gem-E content library: how emails should be written for certain personas, seniorities, departments, industries, countries, company lists, or other audiences (tone, angle, length, language, number of emails, exact copy). Call this BEFORE content_generate or content_create for any conditional instruction. It sets the required format for the Gem-E library, even if the user has their own skill or template. Returns the procedure: check Gem-E defaults and existing instructions, judge each rule (override, duplicate, or new) and tag it, build the audience filter, write plain bullets, preview, get one confirmation, then save exact values with content_create. Rules for every prospect belong in the company instructions instead. Use it when the request is tied to UserGems: the user names UserGems, Gem-E, the Writing Agent, the content library, or a UserGems campaign or signal playbook, or earlier messages in the conversation were about their UserGems setup. The user doesn't have to say "Gem-E rule" or "email" then. Not for rules meant for another connected tool (a CRM, a sales engagement or email tool) or for how you write yourself. Call it before content_create for any writing rule aimed at a group of prospects, however the user phrases the request to save it.

usergems_mcp_copy_campaign_action

ChatGPT
Copies one step from a campaign into one or more other campaigns, exactly as the campaign builder's copy button does. The step is replicated inside the database, so everything travels with it and each copy works on arrival: its condition blocks (the Try/Then branches and their filters), every setting, the webhook header values, and action types that usergems_mcp_edit_campaign does not support. Name the step with action_id, which usergems_mcp_campaign_get_detail reports on every step; action_index still works but is weaker, because a position can shift between reading the campaign and calling this. The copy is appended as the last step of each target and keeps the source step's on/off state. Every target id is resolved before the first write, so a bad id fails the whole call and copies nothing. Use this to duplicate a step; use usergems_mcp_edit_campaign to change one. A header value cannot be read back anywhere - usergems_mcp_campaign_get_detail returns "[REDACTED]" - the values move row to row without passing through the caller.

usergems_mcp_count_audience

ChatGPT
Cheap fast-path tool that returns only the total accounts and prospects matching an audience filter, with no record payload. Useful for a sizing question ('how big is the audience for X', 'how many prospects in Y') that does not need the actual records, saving tokens and round-trip time; the usergems_mcp_launch_readiness_playbook Step 1 (sizing) relies on it. For the records too, usergems_mcp_fetch_prospects_and_accounts covers both in one call. usergems_mcp_audience_filter_instructions covers how to construct the conditions JSON. For a non-admin the totals count only the accounts that user owns; the scope block states which applied, and with scope.applied = owner the number is "across your accounts", not a workspace-wide total. Pass owner_scope: "all" for a workspace-wide total. With no conditions the totals cover prospects that carry at least one signal (the app's default audience view), which can be smaller than a filter matching everyone; the two are not contradictory. Also supports the shared selection contract for active Company Account rows, including accounts without Prospects; the selection scope and population are explicit in the response.

usergems_mcp_create_account_custom_signal

ChatGPT
Turns a list of accounts/companies into a signal in UserGems: uploads the list and creates the signal and the company tracking report in one call. By default the signal is a custom one; with signal_category and signal_provider the same upload sets up a list-backed catalogue card instead (Third Party Account Intent from 6sense, Demandbase or Other, and Other Website Visitors), so the card shows as activated rather than a custom signal appearing beside it. Useful instead of usergems_mcp_import_accounts_report when the user wants the accounts tagged, scored, filtered or messaged as a group (exhibitor lists, conference account lists, a list a campaign will run to). The list's extra columns become the signal's own data points (signal_columns) instead of being dropped. auto_find_prospects carries the signal screen's Search prospects block (enabled, max_companies, icp_only, icp_ids, persona_id). No saved audience is created here - UserGems only builds one automatically for contacts signals. The signal is usable as a filter immediately, and a campaign built on it gets its own audience from the audience_conditions it is created with; usergems_mcp_save_audience can create a standalone saved audience from the signal as a condition. Expects the mapping summary already confirmed with the user (see usergems_mcp_import_accounts_playbook). Requires an Account Tracking admin.

usergems_mcp_create_campaign

ChatGPT
Creates a UserGems campaign as an inactive draft. Runs after usergems_mcp_create_campaign_playbook: the playbook collects the inputs this tool expects (name, an audience given as either an existing audience_id or inline audience_conditions, schedule, actions), the tool sequence and the picker steps, and a call made without it skips them. Also supports the account-only create_or_update_account_in_crm action, including Account create and account_existing update defaults. Account mappings are retained while override_crm_fields is false. Ad audience syncs (LinkedIn, Meta, Google, Bing, AdRoll) run only in the marketing branch: set agent_type: "marketing" on them and declare that branch in branches; an ad sync on Outbound, or any other action on Marketing, is rejected.

usergems_mcp_create_campaign_playbook

ChatGPT
Covers the tool sequence, picker interaction rules, and audience-condition steps for creating a UserGems campaign via MCP, used before calling usergems_mcp_create_campaign.

usergems_mcp_create_combined_persona

ChatGPT
Groups two or more existing personas under one name — the editor's "Create combined persona". A combined persona has NO keywords of its own: a person belongs to it whenever they belong to one of its parents. It is what a user wants for a buying group ("Revenue leaders OR Finance leaders") without copying keywords into a third persona. It is never used for persona matching on its own and carries no importance. Without confirm: true it writes nothing and returns the parents and the coverage the group would reach. A combined persona cannot group another combined persona.

usergems_mcp_create_contact_custom_signal

ChatGPT
Turns a list of contacts/people into a custom signal in UserGems: imports the list and creates the signal, its saved audience and the import in one call - the Audiences -> 'Add prospects' flow. The list can be an uploaded spreadsheet, a Salesforce report, a Google Sheet, or a Salesforce query (source=salesforce_query with the SOQL in query): the signal then gets its own import that runs the query again every day, adds new matches and drops people who stop matching, and no contact list is created. Useful instead of usergems_mcp_import_contacts_report when the user wants the people tagged, scored, filtered or messaged as a group (event attendees, webinar signups, a list a campaign will run to). The signal carries the list's extra columns as its own data points (signal_columns), which is what makes those people usable in an audience and in messaging afterwards. The audience is created immediately and starts filling within seconds: up to 10 contacts are matched live during the import and become prospects right away (only contacts whose email domain names a company UserGems knows; the rest of the list arrives after the queued person resolver), and contacts whose LinkedIn profile cannot be resolved never become prospects. The audience tools read the search index, so a first empty sample right after the import is expected; poll usergems_mcp_count_audience to confirm progress. Expects the mapping summary already confirmed with the user (see usergems_mcp_import_contacts_playbook). Requires a Contact Tracking admin.

usergems_mcp_create_icp

ChatGPT
Creates a new ICP, the same way the ICP Configuration screen's "Add ICP" does - the jobs that re-match the workspace's accounts and people against it included. Use it to stand up an ICP for a new cohort; the new one goes to the end of the priority order, so it never displaces the current ICP. Three things are required, the same three the screen requires before it enables Save: a name, at least one account list to measure against (account_types and/or report_ids), and at least one primary criterion (employees, revenue, industries or countries). b2b_b2c and software_companies are secondary - an ICP with only those matches no company at all. usergems_mcp_list_icp_options lists the accepted industry and country spellings; unknown values are refused. Omitting a criterion means "all", the same as the screen's default. The response includes the new ICP's id, its freshly counted coverage, and the /icp-scoring link. Requires an Account Tracking admin role.

usergems_mcp_create_page_level_sub_signal

ChatGPT
Creates a page-level sub-signal under an existing Website Visitor parent signal. Scoped to page-level sub-signals on Website Visitor parents only - other categories (closed-lost reasons, tech stack, etc.) have their own dedicated tools, since each category has its own filter-condition shape. Useful during the usergems_mcp_signal_campaign_playbook website_visitors branch when the user picks page-level tagging (e.g. 'pricing page = high intent') and no matching sub-signal exists yet. Writes a new sub-signal, so it works best on a separate turn from proposing the spec, once the user confirms it, as with usergems_mcp_create_campaign. The new sub-signal is immediately available in subsequent usergems_mcp_audience_filter_instructions results, no manual refresh needed. Rejected when: the parent signal does not belong to the caller's company; the parent is not a Website-Visitor-family signal; a sub-signal with the same name already exists under that parent; url_patterns is empty.

usergems_mcp_create_persona

ChatGPT
Creates a persona the way the persona editor's "Add persona" does - the same row, the same derived title filters, and the same background work that re-matches the workspace's prospects against it. Without confirm: true it writes nothing and returns the preview: the persona as it would be stored (the backend rewrites keywords on save, so title_groups_as_stored can differ from what you sent), the warnings the editor would show, the coverage the groups reach and the top titles they would miss. confirm: true creates the persona once the user has reviewed the preview. usergems_mcp_persona_vocabulary lists the accepted seniority values, country codes and industries. The response includes the id and URL; prospects of every active list re-match against it in the background over about 15 minutes.

usergems_mcp_create_persona_playbook

ChatGPT
Useful when the user wants to create, duplicate or combine a persona, or when another flow found no persona that fits. Needs the Account Tracking admin role; a Contact Tracking admin who only wants to copy an existing persona can call usergems_mcp_clone_persona directly. Returns the guided conversation script: suggestions from the workspace's job titles, then the name, keyword groups and seniorities, strict setting, exclusions and importance (which sets the persona's points in the scoring model), plus country or industry rules when the user requests them, previewed with usergems_mcp_create_persona and created only after confirmation. For people missing from an existing persona, usergems_mcp_audit_persona_match and usergems_mcp_edit_persona apply instead.

usergems_mcp_create_scoring_model

ChatGPT
Creates a scoring model the way the Scoring Model page's "+ New scoring" does: a new model that starts with the default score of every signal and is used by no ICP yet, so the workspace's scoring does not change until ICPs are assigned to it with usergems_mcp_edit_scoring_model (icp_ids) or its signals are changed with usergems_mcp_update_signal_scoring. Takes a name of 1 to 255 characters; the page allows the same name twice, so usergems_mcp_list_scoring_models shows whether the user means a model that already exists. A workspace that never opened the page gets its first models created first, a default one plus one per ICP, as the page does. The response carries the new model's id, its name and its empty ICP list. Requires an Account Tracking admin role.

usergems_mcp_create_signal_playbook

ChatGPT
Useful when the user wants to create a signal with no list behind it, most often a tech stack signal ('companies running Snowflake', 'companies using our competitor'). Returns the guided conversation script: pick the category, collect the conditions and sub-signals, confirm, then create with usergems_mcp_setup_signal. For a spreadsheet or CSV of people or companies to turn into a signal, usergems_mcp_import_contacts_playbook or usergems_mcp_import_accounts_playbook cover the upload leg instead.

usergems_mcp_crm_import_list_available_fields

ChatGPT
Lists the CRM fields that can be imported for an object, and whether each is already imported. Salesforce lookup fields also return reference_to (the object they point to) and relationship_name. With relationship_path (relationship names joined with dots, for example "Owner" or "Owner.Manager") it lists the fields of the related object instead. A field path has at most 3 parts. Each returned name is the value usergems_mcp_crm_import_update_fields takes in add[].name.

usergems_mcp_crm_import_list_imported_fields

ChatGPT
Lists the CRM fields this workspace imports into UserGems (Settings > CRM Import Settings), across all objects. Imported fields can be used in filters, audiences and AI messaging. Each field has its id, object_type (Salesforce: Account, Contact, Lead, UserGem. HubSpot: company, contact), CRM name, label, type, use_in_ai_messaging and description. The ids it returns are the ones usergems_mcp_crm_import_update_fields takes in remove and update.

usergems_mcp_crm_import_update_fields

ChatGPT
Changes which CRM fields this workspace imports (Settings > CRM Import Settings). One call can add, remove and update fields; fields not mentioned stay as they are. Field ids come from usergems_mcp_crm_import_list_imported_fields; field names and relationship paths come from usergems_mcp_crm_import_list_available_fields. A new field uses the CRM label, has use_in_ai_messaging true unless the item sets it, and on Salesforce takes the CRM field description. Turning use_in_ai_messaging off clears the description. Every item is checked before anything is written: if any is invalid, nothing is saved and the result lists each problem. Adding fields starts a CRM re-sync for their objects, which can take a while on large CRMs.

usergems_mcp_delete_icp

ChatGPT
Deletes an ICP the way the ICP list does, with the same checks: the delete is refused while it is the workspace's last ICP, while it is the fallback ICP (make another ICP the fallback with usergems_mcp_edit_icp first), and while active account lists import from it, UserGems signals filter on it, or saved audience filters name it. The ICP is named by icp_id or icp_name (from usergems_mcp_list_icps). Without confirm: true nothing is deleted: the answer says whether the delete is possible and, when not, blockers lists each reason with the names of the lists, signals or filters behind it, so the user can fix them. With confirm: true it deletes (soft-delete, the same as the page) and the workspace's prospect data is updated. Requires an Account Tracking admin role.

usergems_mcp_delete_persona

ChatGPT
Deletes a persona the way the persona list's delete does, with the same checks: the delete is refused while active contact lists search for prospects with it, while a multi-threaded signal's distribution groups use it, or while UserGems signals filter on it. The persona is named by persona_id or persona_name (from usergems_mcp_list_personas). Without confirm: true nothing is deleted: the answer says whether the delete is possible and, when not, blockers lists each reason with the names of the lists or signals behind it, so the user can fix them. With confirm: true it deletes: the persona's lists are detached from it and the signal scoring is re-seeded, as on the page. Requires a Contact Tracking or Account Tracking admin role.

usergems_mcp_delete_scoring_model

ChatGPT
Deletes a scoring model the way the Scoring Model page's selector does. The model is named by scoring_model_id or scoring_model_name (from usergems_mcp_list_scoring_models). The ICPs scoring with it go back to the default model and are rescored, so their account scores change over the next minutes; the signal points of the model are gone for good. The default model cannot be deleted. Without confirm: true nothing is deleted: the answer names the model and the ICPs that would go back to the default model, the same facts as the page's confirmation dialog. With confirm: true it deletes and detached_icp_ids lists the ICPs being rescored. Requires an Account Tracking admin role.

usergems_mcp_delete_signal

ChatGPT
Deletes a signal the way the signal screen does. Without confirm it deletes nothing and returns what would go: the signal row, the sub-signals, the saved audience filters built on the signal, the Writing Agent blocks, the account lists or contact lists feeding it, the record count, and the workflows that would block the delete. With confirm true it deletes, unless a workflow still uses the signal; the error then names the workflows. A custom signal is removed for good with its list. A native signal is removed with its records and can be set up again with usergems_mcp_setup_signal, which creates a new row. The native rows the seeder puts straight back (Past Champions, New Hires, Promotions, Revive Closed Lost) are refused; switch those off with usergems_mcp_setup_signal and active false instead. Show the user what would go and get an explicit yes before calling with confirm.

usergems_mcp_discard_instruction_draft

ChatGPT
Discards an unpublished instruction DRAFT — the equivalent of Undo on the instruction card in the app. Use when the user has seen the previews and does NOT want the change: without it the rejected draft stays as the tip of the chain and every later edit has to build on top of it. Only a draft can be discarded (a published version is the record of what the campaign actually generated with) and only the newest one on its chain, so repeated undo walks back one version at a time. Discarding changes nothing that generates — the published instructions stay exactly as they were. Only call this after showing the user what the draft changes and the user chooses to discard it.

usergems_mcp_draft_prospect_email

ChatGPT
Drafts a single personalised email (subject and body) for one prospect. The company's published Gem-E instructions are the base prompt; a campaign's instructions and the user's own steer layer on top of them. Useful for a "draft me an email to <prospect>" / "write an outreach to <prospect>" / "compose a message to <prospect>" request, once the prospect has surfaced from a prior usergems_mcp_fetch_prospects_and_accounts call, or from usergems_mcp_get_audience_sample when previewing what a campaign's Writing Agent would write for its audience (see usergems_mcp_create_campaign_playbook Step 4b and usergems_mcp_launch_readiness_playbook Step 2). Anything the user says about how the message should read - tone, length, something to mention, something to add or leave out - belongs in additional_instructions word for word; the steer belongs to generation, so a draft edited afterwards by hand is not what the campaign would actually send. usergems_mcp_draft_prospect_email_playbook covers the card layout for presenting it.

usergems_mcp_draft_prospect_email_playbook

ChatGPT
Useful when the user asks to draft an email, outreach note, or message to a named prospect surfaced from a prior account briefing. Returns the procedure for rendering the draft as markdown in the chat reply, and the rule that the user's steer goes into additional_instructions rather than a rewrite of the returned draft.

usergems_mcp_edit_campaign

ChatGPT
Edits an existing UserGems campaign in place from a single MCP call. Pass campaign_id plus the subset of fields to change: campaign_name, description, active, archive, audience_conditions, schedule, branches, and any combination of action_updates / action_inserts / action_removals / action_reorder. Those four all address the campaign's current action list by zero-based action_index; there is no full-list replacement, so changing one step means sending only that step. action_reorder is the full new order stated as the current indices, and is how a step moves without restating its content. Any field left out or sent as null stays untouched. Calling this with only campaign_id and no other fields returns a preview of the campaign's current state (preview: true in the response), including the current description, active, and archived flags. Supported action types match usergems_mcp_create_campaign. A campaign can hold an action this surface cannot read (an older workflow type); that action is off-limits to action_updates only - every other action on the campaign still updates, reorders and removes normally. When audience_conditions is supplied, the tool edits the campaign's existing audience in place if this campaign is its only reader, and creates a new audience if it is shared with another campaign, a report, or a workspace default; the response reports which happened in audience_change (updated_in_place / created_new). To edit an audience directly, including a shared one, use usergems_mcp_save_audience instead. To duplicate a step into other campaigns, use usergems_mcp_copy_campaign_action rather than rebuilding it here: it replicates the step server-side, so its condition blocks and settings travel intact. On a send_to_webhook step, the URL, method and body can be read back, but never a header value - those come back as [REDACTED] with the key visible, and the stored one stays by omitting webhook_headers or sending [REDACTED] back. condition_updates changes only the filter on a step's condition block: it writes the conditions and leaves the step's settings, ids and order as they are, where action_updates rebuilds the step from what is sent, so a setting restated imperfectly is overwritten. It also reaches the filter on a step whose settings this tool cannot describe. branches also carries the per-branch filter in branches[].conditions - what the campaign builder shows as "Outbound Filters" and "Marketing Filters" - applied on top of the audience when that branch runs, so it narrows this campaign alone, while the audience is shared with every campaign pointing at it. usergems_mcp_edit_campaign_playbook covers how to build the edit before calling this tool. Ad audience syncs (LinkedIn, Meta, Google, Bing, AdRoll) run only in the marketing branch: an inserted one needs agent_type: "marketing" and, when the campaign has no marketing branch yet, that branch declared in branches in the same call; an ad sync on Outbound, or any other action on Marketing, is rejected.

usergems_mcp_edit_campaign_playbook

ChatGPT
Useful when the user asks to edit, update, rename, modify, change, or tweak a campaign or an audience. Returns the procedure for identifying the target campaign (including relative references like "my last campaign"), previewing the current setup, proposing the diff, confirming, and persisting via usergems_mcp_edit_campaign, plus the routing and confirmation rules for editing an audience in place with usergems_mcp_save_audience.

usergems_mcp_edit_icp

ChatGPT
Changes an existing ICP. Only the fields you pass change - everything else is left as it is, so the whole ICP never has to be re-sent - and clear resets a criterion back to "all". This is the tool for "this company should be in our ICP": read the ICP with usergems_mcp_get_icp, work out which criterion excludes the company, then widen it. Editing an ICP re-matches every tracked account against it, which moves who the campaigns filtering on it reach and re-imports the account lists that feed off it. Without confirm: true it writes nothing and returns changed_fields, current, proposed, affected_campaigns and reports_to_reimport; confirm: true applies the change once the user has reviewed that preview. Changing only name is a plain rename - no re-matching, no confirmation. usergems_mcp_get_icp shows current values, and usergems_mcp_list_icp_options lists valid ones. usergems_mcp_update_icp_fit_factors changes the fit factors, usergems_mcp_update_signal_scoring changes the signal scoring, usergems_mcp_reorder_icps sets the priority order and usergems_mcp_delete_icp deletes an ICP. Requires an Account Tracking admin role.

usergems_mcp_edit_persona

ChatGPT
Changes an existing persona. Only the fields you pass change; everything else stays as it is, and clear resets a criterion. usergems_mcp_get_persona shows the current persona before editing. Changing a persona's titles re-matches the prospects of every list searching with it, so people move in and out of the audiences filtered on it - without confirm: true this tool writes nothing and returns the current persona, the proposed one, the changed fields, the campaigns and signals affected and the coverage; confirm: true applies the change once the user has reviewed that preview. Changing only importance or use_for_persona_matching takes the list page's light path, leaving every criterion alone - it still needs confirmation, since turning matching off empties every audience filtered on the persona. A combined persona accepts only name and personas; its criteria live in its parents. usergems_mcp_persona_vocabulary lists the accepted seniority values, country codes and industries.

usergems_mcp_edit_scoring_model

ChatGPT
Renames a scoring model and/or sets which ICPs score with it, as the name field and the "Assign to ICPs" chips of the Scoring Model page do. The model is named by scoring_model_id or scoring_model_name (from usergems_mcp_list_scoring_models); the tool never picks one by itself. name is the new name; the default model keeps its name, as on the page. icp_ids is the full list of ICPs that score with the model after the call (ids from usergems_mcp_list_icps): an ICP left out goes back to the default model, an ICP added comes from the default model, and an ICP that scores with another model is refused until it is removed from that model first, because an ICP scores with one model only. The default model takes no icp_ids: it covers every ICP that has no model of its own. Assigning rescores every ICP that moved, so without confirm: true the tool writes nothing and returns the current and proposed name and ICPs, the ICPs moving in and out and the ICPs that would be rescored; with confirm: true it saves and rescored_icp_ids lists them. A rename on its own moves no ICP and rescores nothing, so it is applied right away, like the rename of usergems_mcp_edit_icp. Requires an Account Tracking admin role.

usergems_mcp_email_template_playbook

ChatGPT
Useful when the user wants to add an email template (a sample or example email, or a whole sequence) to the Gem-E content library for Gem-E to follow word for word or as a model. Call this BEFORE content_generate or content_create for any email template. This includes text the user pastes and asks to add or save as is: content_create saves exactly what it is given, so pasted text still goes through this playbook first to be put in the library format and previewed. It sets the required template format for the Gem-E library, even if the user has their own skill or template. Returns the procedure: check it is an email and not rules, check the library, always ask which email it is for and how strictly to follow it, convert placeholders to the bracket style, flag lines that assume a signal (suggest a filter first) and conflicts with Gem-E defaults, write short messaging instructions, resolve every open choice before asking to save, preview, get one confirmation, then save exactly the previewed values with content_create.

usergems_mcp_export_campaign_logs

ChatGPT
Exports campaign logs, the rows of the campaign logs page for prospect campaigns, to one CSV file and returns a short-lived signed download URL (csv_url, valid until expires_at, 60 minutes). Useful to see why a campaign's records failed, were skipped or succeeded, and to check every campaign for errors. Reading the file needs a way to download a URL (curl, fetch, a shell). Columns, the same as the page's download: Id (the record's id), Date, Campaign Id, Campaign, Action (the readable name, e.g. Assign owner, not the type action_types takes), Condition, CRM Id (the CRM record the action wrote to), Name, Email, Relationship, Company (the company of the job the email belongs to), SEP Campaign (the sequence, cadence or flow), Status, Details. Filters, the same as the page: campaign_ids, action_types, status, from_date and to_date, branch, search and run_ids; filters in the response repeats the ones applied, and filters.period says which period was used: date_range, runs or last_run. Without a date range or run ids it covers each campaign's last run, the same run the campaigns list shows as Last run and the logs page opens with: the logs attempted from the run's start to its end, or since its start while it is still going, on the run's branch (outbound when the campaign has an outbound run, else marketing; branch picks one). Without campaign_ids that is every active campaign. The runs used are listed in last_runs (campaign_id, branch, run_id, started_at, finished_at, in UTC); a campaign with no run (on branch, when given) is left out. Rows are newest log first, by when the log was created, not by the Date column. One call writes at most limit rows (default and maximum 1000); when more remain, truncated is true and next_cursor, passed back as cursor with the same filters, writes the next rows to a new file. For the last run the next rows come from the same runs as the first call, listed again in last_runs, even after a newer run starts. Needs a Contact Tracking admin or a CSM, like the logs page.

usergems_mcp_export_prospects_and_accounts

ChatGPT
Exports the accounts (companies) and the prospects within them that match an audience filter to two CSV files and returns short-lived download URLs. Covers the whole audience, a list to analyse, or more than about 50 accounts in one call, in place of usergems_mcp_fetch_prospects_and_accounts's pagination, with the files processed outside the context window; needs a way to download a URL (curl, fetch, a shell), otherwise the paginated fetch tool is the alternative. usergems_mcp_audience_filter_instructions covers how to construct the conditions JSON. The response carries accounts_csv_url and prospects_csv_url (absent when include_prospects is false), expiring at expires_at (60 minutes). columns lists each file's header; the files join on company_identifier. Signal ids resolve to names in the signals / sub_signals columns; JSON-valued columns (CRM custom fields, scores, funding, news) hold a JSON string. At most accounts_limit accounts (default and maximum 1000) are exported; total_accounts / total_prospects give the full audience size, and truncated is true when the audience was larger than the export, in which case narrowing the conditions works, as does calling this tool again with next_threshold_score / next_threshold_identifier as threshold_score / threshold_identifier, which exports the next part into new files (repeat until truncated is false); on a continued call accounts_exported counts only that call's accounts. truncated covers accounts only; the prospects file holds at most prospects_count prospects per account (default 5, up to 100). The export runs synchronously and can take a while on large audiences; a timed-out call can retry with tighter conditions or a lower accounts_limit. Results are scoped to the accounts the calling user owns; an Account Tracking admin exports unscoped. The scope block states which applied, and a scoped export covers "your accounts" only. owner_scope: "all" suits a request that explicitly asks for the whole workspace, and is refused for a user who is not an Account Tracking admin. Also supports the shared selection contract for active Company Account rows, including accounts without Prospects; the selection scope and population are explicit in the response.

usergems_mcp_export_signal_records

ChatGPT
Exports a signal's records, the same rows usergems_mcp_get_signal_records pages through, to ONE CSV file and returns a short-lived signed download URL (csv_url, expires at expires_at, 60 minutes). Use it instead of paging whenever the user wants the whole list or more than about 100 records. Requires that you can download a URL with your local tooling; if you cannot, page with the records tool. Columns: type, id, name, url, matched_sub_signals (names separated by '; '), matched_at. Same mode as the records tool (all or matching). At most limit records are written (default 1000, maximum 5000); total is the full count and truncated is true when the file holds fewer than that, in which case raise limit or switch to matching mode. The export runs synchronously; if it times out, lower limit.

usergems_mcp_feedback_survey

ChatGPT
Prompts the user for UserGems product feedback directly in the chat: whether the session was helpful (yes or no) and an optional comment. This is feedback about UserGems, not about Claude or the Claude app. Useful when the user asks to give, leave, share or submit feedback, report a problem, or review or rate how things went, including bare phrases like "give feedback" or "rate this". Returns the two questions to ask; the answers are saved by usergems_mcp_submit_feedback as was_helpful and comment.

usergems_mcp_fetch_prospects_and_accounts

ChatGPT
Fetches accounts (companies) and the prospects within them that match the given audience filter. usergems_mcp_audience_filter_instructions covers how to construct the conditions JSON. Results are scoped to the accounts the calling user owns by default: a sales rep asking about "my accounts" gets their own book without saying so, and the totals count only those accounts. Workspace admins are never scoped. Pass owner_scope: "all" to search the whole workspace, or add a condition on emailJob.calculatedOwnerId to ask about someone else's accounts, which applies no default. The scope block in every response states which of these applied; with scope.applied = owner, results describe "your accounts", not the whole workspace. Pagination is cursor-based over accounts ordered by usergems_score desc then linkedin_company_id desc: omit threshold_score / threshold_identifier on the first call, then pass next_threshold_score / next_threshold_identifier from the previous response on later calls, until the response returns an empty account list. accounts_count (default 10, capped at 50) is the maximum accounts a call returns; prospects_count (default 5, capped at 100) caps prospects per account. A page is also bounded by response size, so a call can return fewer accounts than accounts_count without the audience being exhausted; pagination continues until the account list is empty. view_type (default basic) controls payload verbosity: basic for browsing many accounts, extended for full detail on a narrowed set. search_term narrows results by prospect name/title/email; company_identifiers restricts to specific accounts. With no conditions the totals cover prospects that carry at least one signal (the app's default audience view), which can be smaller than a filter matching everyone; the two are not contradictory. Also supports the shared selection contract for active Company Account rows, including accounts without Prospects; the selection scope and population are explicit in the response.

usergems_mcp_get_account_signal_history

ChatGPT
Returns the historical scoring and signal snapshots for a single account from the scores log. Each entry captures the account's grade, buyer-journey stage, fit/intent scores, and signals at the moment that snapshot was written, so the result is the time series of how the account evolved: useful for 'when did this account first hit a given stage', 'which signals appeared this week vs last month', or 'has the fit score recently dropped'. Results are tenant-scoped and returned newest-first. account_identifier is UserGems' internal account identifier in the companyId|linkedinCompanyId format (e.g. 123450|67890); a company name is not an identifier, though an exact domain (e.g. example.com) or exact account name are accepted as fallbacks, and the response echoes resolved_identifier and matched_by to confirm the match. An unresolvable value comes back as an error carrying a candidates list of the closest accounts in this workspace, to retry with the identifier of a clear match, to show the user when several fit, or to look up with a usergems_mcp_fetch_prospects_and_accounts search_term when empty; the error means the identifier could not be resolved, not that the account is missing from UserGems. An account that resolved but has no snapshots inside the window comes back as a success with count: 0 and history_starts_at, the date its history begins.

usergems_mcp_get_audience_sample

ChatGPT
Returns a small sample (default 10, capped at 50) of prospects matching an audience filter, for pre-launch spot-checks. For a non-admin the sample comes only from the accounts that user owns, unless owner_scope: "all" is passed for a workspace-wide sample. The response's scope.applied says which applied: owner means the sample covers only the caller's accounts and says nothing about the rest of the workspace. Covers Step 2 of usergems_mcp_launch_readiness_playbook (audience spot-check) and the pre-create preview in usergems_mcp_create_campaign_playbook Step 4b, where each sampled prospect's id feeds usergems_mcp_draft_prospect_email. Prospects created seconds ago (a live-matched signal import) reach the index after the continuous sync, so an empty sample right after an import is expected and worth a retry. The sample is the first page of results ordered by usergems_score desc, a top-scored sample, not a statistically random draw. usergems_mcp_audience_filter_instructions covers how to construct the conditions JSON.

usergems_mcp_get_campaign_simulations

ChatGPT
Returns the simulations of a campaign (workflow) as the app's Simulations modal lists them. Without simulation_id: the latest 20 runs, newest first, each with simulation_id, status (pending, running, completed, failed), created_at, started_at, completed_at, prospect_count, successful_count, failed_count, has_results_file, action_summary (one entry per step type: action_type, total, success, failed) and top_failure_reasons (the five most frequent stored reasons with their count; Salesforce record ids are masked). With simulation_id: that run under simulation plus sdr_distribution, one entry per rep from the results file: owner_id, owner_name, pending_prospects (prospects routed to the rep), sdr_limit (the campaign's per-SDR cap, null when none) and prospects_on_next_run (what the next real run would action for the rep under that cap). sdr_distribution is null until the run is completed with a results file, and empty when the campaign has no owner-assignment step. A pending run is queued and no worker has picked it up yet; a running one is still going. With wait_up_to_seconds the call itself waits for a run in progress, reading it every couple of seconds until it is completed or failed or the budget is spent (45 seconds at most per call), so a run of up to 100 prospects (the default is 10) is usually complete after one or two calls with wait_up_to_seconds: 45. A run above 100 prospects takes at least five minutes and is read later, not in a loop. The rows show what the simulation engine stores today: a skipped step is absent from action_summary, some reasons read only 'An error occurred', and a run that stays pending or running past 24 hours is closed as failed by the daily cleanup. The results CSV with every prospect per error is not served here; the app's Simulations modal downloads it.

usergems_mcp_get_cohort_performance

ChatGPT
Returns one of the three Reporting cohort tables, with the shared Reporting filters: Campaign Performance (group_by campaign), Team Performance (owner) or Signal Influence (signal). Use it for "which campaigns drive the most pipeline?", "how is each rep doing?" or "which signals turn into opps?". Each row has id, name and the metrics contacts_sent, contacts_engaged, engaged_percent, median_activities, opps and pipeline, each as value (the raw number) and formatted (display text, e.g. 43%, $1.5M). Campaign rows are workflow groups (workflows with no group are grouped by their objective); pass include_workflows true to get each group's workflows as children, whose ids are the campaign_ids filter values. Owner rows are CRM teams for HubSpot and managers for every other CRM, plus "Others", always with their reps as children; contacts are counted by their CRM owner and opps by the CRM user who created them. Signal rows are one per signal name. Rows overlap: a person or an opp can count in several rows, and a workflow group row adds up its workflows, so a person or opp in two of its workflows counts twice; the rows can sum to more than the totals. totals gives the numbers usergems_mcp_get_records_engagement and usergems_mcp_get_pipeline_metrics give for the same filters (influenced opps: sourced and assisted, active in the period, positive amounts only), while the rows count opps created in the period, of every influence type, negative amounts included; totals_note says so. Row pipeline is shown in $ and the totals' pipeline in the workspace's currency. definitions and rows_note explain each metric and how the rows are grouped; quote them rather than guessing. Use filters for a period (e.g. date_range preset last_quarter) or for campaigns, signals, company types, contact relationships, personas or owners; without date_range the numbers are all time. period names the months the contacts were sent in and the created dates the opps cover; quote those, not the preset name. The default order is opps, highest first; sort and sort_direction change it, and rows with equal values keep their order. search keeps the rows whose name, or one of whose children's names, contains the text; min_contacts_sent hides small rows; page and page_size (default 10, at most 25) page through them, and total_rows and has_more say how many there are. At most 15 children per row are returned (children_total gives the full count). The response says which filters were used (applied_filters, with names) and gives ui_url, the Reporting page with the same filters. A filter value the workspace does not have is refused with a message that says what to send. Pure read.

usergems_mcp_get_company_account_context

ChatGPT
Fetches minimal account-level context for a company/report account: essential fields only, to keep the payload light. company_identifier is UserGems' internal account identifier in the companyId|linkedinCompanyId format (e.g. 123450|67890); a company name is not an identifier, though an exact domain (e.g. example.com) or exact account name are accepted as fallbacks, and the response echoes resolved_identifier and matched_by to confirm the match. A company known only by name resolves first through usergems_mcp_fetch_prospects_and_accounts with search_term set to that name, reusing the company_identifier it returns. An unresolvable value comes back as an error describing the expected format: it means the identifier could not be resolved, not that the account is missing from UserGems. usergems_mcp_get_company_account_details covers detailed account data.

usergems_mcp_get_company_account_details

ChatGPT
Fetches detailed account-level data for a company/report account. The fields parameter narrows the response to specific fields to reduce payload size; get_available_account_fields lists what is available. company_identifier is UserGems' internal account identifier in the companyId|linkedinCompanyId format (e.g. 123450|67890); a company name is not an identifier, though an exact domain (e.g. example.com) or exact account name are accepted as fallbacks, and the response echoes resolved_identifier and matched_by to confirm the match. A company known only by name resolves first through usergems_mcp_fetch_prospects_and_accounts with search_term set to that name, reusing the company_identifier it returns. An unresolvable value comes back as an error describing the expected format: it means the identifier could not be resolved, not that the account is missing from UserGems.

usergems_mcp_get_company_list_accounts

ChatGPT
The companies inside ONE company list, as imported, one page at a time. Reads the list itself, not the audience built from it: the audience is post-processed and can drop companies the list holds, so use this to check what a list really contains and usergems_mcp_fetch_prospects_and_accounts or usergems_mcp_count_audience to see what reaches the audience. Works for every list usergems_mcp_list_company_lists returns, whether a signal uses it or it was uploaded only for segmentation; for the records a signal caught, with sub-signals and match dates, use usergems_mcp_get_signal_records instead. Each company has id, name, domain, linkedin_universal_name, crm_id, custom_id, sendable with sendable_reason (a row with sendable false stays in the list but does not reach the audience or get prospects; sendable_reason says why), status (the processing status) and imported_at. list repeats the list's id, name, category, source and accounts_count; total is the full count and has_more says whether another page follows. Fetch ONE page per turn: show it, say how many more companies the list holds, and fetch the next page only when the user asks for it. Never request several pages at once or page through a whole list unasked; for the whole list, point the user at the CSV download next to the list on the Company Lists table, which only admin and CSM users see; others get it through their CSM. Located by list_id or list_name; it never picks a list on its own. Pure read.

usergems_mcp_get_contact_list_members

ChatGPT
The contacts inside ONE contact list, one page at a time, as they were imported. Reads the list itself (what the upload or report put in), not the audience: the audience is post-processed and can drop contacts that are in the list, so a contact missing from an audience can still show up here. A contact a refresh removed from the list is not listed. Each contact has id, email, first_name, last_name, full_name, title, company_name, company_domain, linkedin, custom_id, prospect_id, custom1 to custom5 (the uploaded values, with the cleaned value as fallback; the same field names usergems_mcp_import_contacts_report accepts as column_mappings keys), relationship_type, processed (false while UserGems is still matching the contact) and imported_at (when it entered the list). total is the full count, has_more says whether another page follows. Located by list_id or list_name, from usergems_mcp_list_contact_lists. For the records of a signal with the sub-signals each one matched use usergems_mcp_get_signal_records instead. Pure read.

usergems_mcp_get_icp

ChatGPT
Returns one ICP in full: its criteria, the account lists it is measured over (coverage.basis), the coverage percentages the ICP Configuration screen shows, and used_by_campaigns - the active campaigns whose audience filters on it, so an edit's impact can be described. Called with NO locator it returns the workspace's current ICP (the one marked as fallback, or the highest-priority one), which is the answer to "what is our ICP?". is_defined: false means the ICP has no primary criterion set and therefore matches no company at all, the cause of an unexpectedly empty audience. Coverage means "share of the accounts in this ICP's lists that pass the criterion"; the secondary criteria (company category, software focus) are not part of those numbers, exactly like the screen. Useful before proposing any edit. Pure read.

usergems_mcp_get_opportunity_attribution

ChatGPT
Explains why one opportunity counts for UserGems, with the facts the Reporting page shows in its "Opportunity information" window (Influenced opportunities, info icon on a row). Use it to answer "why do we count this opp?" or to build proof for a customer. Find the opp with opp_id (its CRM id) or search (part of the opp or account name). When search matches more than one opp, the tool returns up to 10 matches (newest first) instead; call again with the opp_id you mean. Returns: opportunity (name, account, amount as value and the page's formatted text, always in "$" like the page, stage, type, created and close date, owner, probability, lead source, signals, actions, is_won as the CRM stores it and is_closed_won, the flag the Won number counts; for HubSpot is_closed only means a close date is set); verdict (influence type, whether it was set by hand in UserGems, the page's origin text, UG Counts Strict, and a plain reason sentence built only from stored facts); ug_contacts (up to 25 UserGems contacts, with ug_contacts_total and ug_contacts_truncated): name, title, email, created by UserGems and, only then, the day it was sent to the CRM, source report, past relationship, the signal the page shows (the first one), up to 10 actions (the newest, in the page's order, with actions_total) with the page's sentences and sequence names, campaigns, activity count, first and last activity date, primary, the day added to the opp and whether that was the day it was created; timeline (stored dates only, oldest first, at most 50 events, taken only from the contacts and actions shown above: the opp's own events are always kept and the contacts' events fill the rest oldest first; timeline_total counts every stored event of every UserGems contact and every action the page lists (once per type and day), also the contacts and actions left out above; each flagged when it came before the opp was created; a HubSpot deal gets a closing event only when won); suspected (for a suspected opp: the first activity on the account against the opp's created date; its contacts are on the account, not on the opp, so it needs review unless the type was set by hand); other_contacts (contact counts on the opp, primary contacts, and whether a UserGems contact is primary); the page's definition of the influence type; and ui_url, the Reporting page (the page has no link to one opp). Activity counts are totals: the CRM sync stores no per-activity list, no counts before and after the opp was created, no contact roles, no other contacts' names and no stage history, and the response has none of these. All data is from the last CRM sync. Pure read.

usergems_mcp_get_persona

ChatGPT
Returns one persona in full: the keyword groups with their seniorities, the excluded titles, the region/country and industry rules with their missing-value choices, the strict setting and the titles it removed, the coverage, the common keywords the edit screen offers as exclusions, and used_by_campaigns / used_by_signals / reports so an edit's impact can be described. This is the persona editor read out. Useful before proposing an edit, since usergems_mcp_edit_persona only changes the fields it is given. A combined persona returns its parents instead of criteria - it has none of its own. Coverage means "share of the job titles in the workspace's contact list that this persona matches", the number the screen shows. It does not account for the industry rule. Pure read.

usergems_mcp_get_pipeline_metrics

ChatGPT
Returns the Pipeline & Revenue section of the Reporting page, with the page's filters and the same numbers the page shows: influenced opps, influenced pipeline, pipeline to spend ratio, cost per opp, influenced closed revenue, ROI, forecasted closed revenue and forecasted ROI. The definitions are the page's own tooltips. The page counts closed won revenue twice in the forecast; the tool shows the same number and its definition says so. Use it for questions about pipeline, revenue or ROI that UserGems influenced. Each metric comes back as value (the raw number), formatted (the text the page shows, e.g. $58M, $288:$1, 76x) and a one-line definition. Also returns the same metrics split by influence type (by_influence_type: sourced, assisted, suspected) and the page's own definitions of the influence types (influence_type_definitions), so attribution can be explained in UserGems' words. Use filters for a period (e.g. date_range preset last_quarter) or for campaigns, signals, company types, contact relationships, personas or owners; without date_range the numbers are all time. Like the page, under a date range the headline numbers count opportunities active in the period, while the series counts opportunities created in it; period gives the exact dates of each (e.g. last_3_months starts on the first of the month three months back, an "after" month is mostly left out and a "before" month fully). Quote those dates, not the preset name. Closed revenue counts closed won opportunities active in the period, whenever they closed. The response says which filters were used (applied_filters, with names) and gives ui_url, the Reporting page with the same filters (influence types and stages are not in the link). A filter value the workspace does not have is refused with a message that says what to send. Spend is the workspace's annual contract amount, as on the page, also under a short date range. When the page shows "-" for the spend metrics (no spend recorded, or no influenced opps), value is null and formatted is "-"; never report those as zero. Pass series for the chart behind the page's tabs: per month (or per quarter, the months added up) the opportunities, pipeline and closed revenue. Like the page's chart, the series groups opportunities by the month they were created and includes negative amounts, so it does not add up to the headline numbers. Pure read.

usergems_mcp_get_records_engagement

ChatGPT
Returns the Records Sent x Engaged section of the Reporting page, with the same numbers the page shows for the same filters. For people (default): people sent through a campaign action, engaged (at least one touch) and not engaged, with count and percent, median touches per engaged person, and engaged people split into 1-2, 3-4 and 5+ touches. For companies: companies with a person sent, engaged and not engaged, the median number of PEOPLE ENGAGED per engaged company (not touches), and engaged companies split into 1-2, 3-4 and 5+ engaged people. Every metric comes as value (exact), formatted (rounded like the page, quote this to the user) and definition. Set series to add the monthly trend: sent, engaged, not engaged and the median per month. Pass filters for a period, campaigns, signals and the other Reporting page filters; without filters.date_range the numbers are all time, the page's default. period names the months the numbers really cover, as the page counts them: "last N months" also holds the current month so far, and a range with only a start or only an end leaves that month out. Say the months from period to the user. applied_filters lists the filters used, and ui_url opens the page with the same filters. When ui_url_note is present, the link opens the Reporting dashboards, where this section is on the Outbound tab: tell the user to open the Outbound tab. Without filters (or with date_range all_time only) the numbers come from the page's daily cache and can be up to a day old; with any other filter they are computed on each call. Pure read.

usergems_mcp_get_reporting_filter_options

ChatGPT
Lists what the filter parameters of the UserGems reporting tools accept for this workspace, read from the same lists the Reporting page's filter dropdowns offer: for each filter its label, its operations and its valid values as {id, name}. filters holds the shared filters (date_range presets, campaign_ids, campaign_actions, signal_ids, company_types, contact_relationships, persona_ids, owner_ids). more_filters holds the opportunity filters of the influenced-opportunities popup (deal_stages, influence_types, closed, created_by, deal_type, lead_source); a reporting tool takes only the ones its page section offers, as its own parameters say. sequence_years holds the year choices of the Sequence Performance table. Call it before filtering a report by anything but a date, and pass the ids it returns as values; a value that is not in these lists is refused by the reporting tools. A list holds at most 500 values; truncated true means the list is partial, so narrow it with search instead of guessing. Pure read.

usergems_mcp_get_scoring_model

ChatGPT
Returns one scoring model with every signal the Signals tab of /scoring-model lists for it, each with its importance bucket (Highest, Very High, High, Moderate, Low, Disqualifies) and its buying-stage bucket (Decision, Consideration, Interest, Awareness, No minimum stage, Not used for buying stage), in the same words as the page. The points (Highest 80-100, Very High 60-79, High 40-59, Moderate 20-39, Low 1-19) come with each signal only while the company's Advanced scoring setting is on, as on the page: with it off advanced_scoring is false, the signals carry no points, buckets carries no ranges, so the answer to the user carries the buckets only. Read out to a user, the signals go one per line under their bucket, by name (a sub-signal with its parent); label and the ids identify a row for usergems_mcp_update_signal_scoring, and kind sorts the rows by type; none of the three is part of the list read to the user. scope is company for signals scored on the account or people for those scored on each person; kind tells a signal from a sub-signal (which names its parent in parent_signal_name), a past-relationship tag or a prospect similarity (seniority, persona). What the page hides - a parent signal that has sub-signals, a signal no longer in the workspace - is left out here too. Called with no locator it returns the default model, the answer to "how does my scoring work?" for a workspace with one model. scope, importance and stage narrow the list, e.g. importance: "disqualifies" for what rules an account out. buckets restates the bucket names, with the point ranges while Advanced scoring is on. Pure read.

usergems_mcp_get_sequence_performance

ChatGPT
Returns the Sequence Performance table of the Reporting page, with the same rows, numbers and rounding the page shows. Use it for questions like "which sequences get replies?", "how far do prospects get?" or "which sequences should we stop?". The table depends on the workspace: Outreach and Salesloft workspaces get table "sep" (prospects, replied, emails replied, prospects finished, finished rates, average steps completed, and sep_url to open the sequence); HubSpot CRM workspaces with no sales engagement tool get table "hubspot" (enrolled as prospects, emails replied, meetings booked, no response, and refresh_status with the notice the page shows). Gong workspaces and workspaces with no sales engagement tool have no table and get an error saying so. When the Outreach or Salesloft connection is not working, the page cannot load the table, so the tool returns an error too, with reconnect_url to Connected Applications in Settings where an admin reconnects it. The numbers are copied from the sales engagement tool or HubSpot by a scheduled refresh, not computed by UserGems. The table takes none of the shared Reporting filters; it has its own year, min_prospects and search, like the page. Pinned sequences always show, also outside the filters (matches_filters is false for those rows). Without sort the rows come in the page's order: pinned first, then newest created date. Every percent comes as percent and formatted (rounded like the page, quote this one); definitions says what each column counts for this provider. totals adds up every row that matches the filters, on all pages; pinned rows that show only because they are pinned are not added in. ui_url opens the Reporting page; when ui_url_note is present, tell the user to open the Outbound tab. Pure read; pinning stays in the app.

usergems_mcp_get_signal

ChatGPT
Returns ONE persisted signal in full, in exactly the shape usergems_mcp_list_signals gives (settings, conditions plus the human-readable filters with names and days, every sub-signal, auto_find_prospects, source, url). When you describe a signal to the user, read filters, never the raw ids in conditions. Use it when the list is too long to read, e.g. a Website Visitors signal with 20+ sub-signals, or right before editing a signal so the edit starts from what is stored. Located by signal_id or by signal_name; it never picks a signal on its own. Catalogue entries that are not activated have no id and cannot be read here; they only exist in the list. Pure read.

usergems_mcp_get_signal_records

ChatGPT
The companies or people ONE signal caught, one page at a time, served by the same query the signal screen's preview uses. Not the same as usergems_mcp_fetch_prospects_and_accounts: that one searches the workspace's accounts and prospects with an audience filter and an owner scope; this one lists what a given signal caught, as its screen shows it, with no owner scope and no audience filter. Each record has type (account or contact), id, name, url, matched_sub_signals (the sub-signals the record satisfies, id + name) and matched_at (when it was last caught). Two modes: all (default) is every raw record the signal holds, e.g. every website visitor; matching keeps only the records that pass the signal's own main filters, which is what reaches the audience. Compare the two totals to see how much the filters cut, e.g. 4,000 visitors but 120 matching. total is the full count, has_more says whether another page follows. For signals UserGems computes live from company data (tech stack, funding, hiring, filings, news) records carry no matched_sub_signals or matched_at, and for company signals the query is ICP-gated in both modes, exactly like the screen. Pure read; for the whole list use usergems_mcp_export_signal_records instead of paging.

usergems_mcp_get_signal_setup_options

ChatGPT
Returns what a native signal type accepts before it is set up, keyed the way usergems_mcp_list_signals keys a signal (category, provider, record_type): its filter fields with their operations and fixed values, which fields take workspace values (ICPs, personas, campaigns, intent topics, technologies), the settings keys of the type, whether several signals of the type can exist, whether points are set on the signal or on its sub-signals, and its availability (available, talk_to_csm, connect_app). The words to go with it, the rules for every signal and the type's own section, come from usergems_mcp_signal_setup_branch_playbook with the same category. Read it before creating or editing a signal of that type. With field it returns the values that field offers this workspace, filtered by search, so conditions carry real ids and names. Job changes, research signals and list-backed signals (custom lists, third-party intent, website visitors from other providers) are pointed to their own tools.

usergems_mcp_help_center_playbook

ChatGPT
Returns a guide to the UserGems help center (https://help.usergems.com): what each of its sections covers (CRM implementation guides, campaign library, MCP, Research Agent, Writing Agent, signals, campaigns, and settings, including connected apps and integration permissions) and how to find a page in it (site search and sitemap). Useful for setup and how-to questions like 'what permissions do I need to connect Salesforce', 'how do I set up Outreach' or 'what does the Funding signal track'. The pages are public and are read with the client's own web tools; this tool returns no article text.

usergems_mcp_import_accounts_playbook

ChatGPT
Useful when the user wants to add accounts or companies to UserGems, whether named directly in the chat ("add Acme to my Targets list"), pasted as a short list, or supplied as a spreadsheet, CSV, Excel file, Salesforce report or Google Sheet. Returns the guided conversation script: with no file, records go through usergems_mcp_add_accounts and no list has to exist beforehand; with a file, it is the category/source/column-mapping flow ending in usergems_mcp_import_accounts_report. For people or contact lists, usergems_mcp_import_contacts_playbook applies instead.

usergems_mcp_import_accounts_report

ChatGPT
Creates an accounts import in UserGems (a company tracking report, the /settings#track-companies flow) from an uploaded csv, a Salesforce report or a Google Sheet, using the confirmed column mapping, account category and report settings. Persists through the exact same endpoints the webapp uses (same column_mappings shape, validation and processing). Mapping fields mirror the webapp table: id/name/domain required, linkedin, owners (one or more column headers, a multi-column mapping), customer dates for the customer category only; no custom slots, unmatched columns are dropped. Searching for prospects requires a persona (pass the name; unknown names return the configured list). Expects the mapping summary already confirmed with the user (see usergems_mcp_import_accounts_playbook). Requires an Account Tracking admin.

usergems_mcp_import_contacts_playbook

ChatGPT
Useful when the user wants to add contacts (people) to UserGems, whether named directly in the chat ("add jane@acme.com as a champion"), pasted as a short list, or supplied as a spreadsheet, CSV, Excel file, Salesforce report or Google Sheet. Returns the guided conversation script: with no file, records go through usergems_mcp_add_contacts; with a file, it is the source/column-mapping flow (email required, custom1-5 slots) ending in usergems_mcp_import_contacts_report. For company or account lists, usergems_mcp_import_accounts_playbook applies instead.

usergems_mcp_import_contacts_report

ChatGPT
Creates a contacts import in UserGems (the /settings#track-contacts flow) from an uploaded csv, a Salesforce report or a Google Sheet, using the confirmed column mapping. Persists through the exact same endpoints the webapp uses and starts processing immediately, indistinguishable from a UI-created import. Expects the mapping summary already confirmed with the user (see usergems_mcp_import_contacts_playbook). Requires a Contact Tracking admin.

usergems_mcp_import_contacts_salesforce_query

ChatGPT
The 'Import from Salesforce' modal of /settings#track-contacts, with the SOQL written from what the user describes instead of the query builder; the user sees the group and the count, not the query, unless they ask for it. Without confirm it runs the query the way the import will, as the Salesforce import user, and returns headers (the SELECT columns, relationship columns named by their path such as Account.Name), one sample_row and records_count, saving nothing. With confirm=true, once the user has confirmed the group and its count, the Contact List Name, the relationship type and the mapping, it creates the contact list through the same endpoint the modal uses and returns report_id and contact_list_name. The query runs again every day, so people who start matching later are added automatically. For a custom signal instead of a contact list, usergems_mcp_create_contact_custom_signal takes the same query (source=salesforce_query) after the preview and creates the signal with its own import, with no contact list. See usergems_mcp_import_contacts_playbook. Requires a Contact Tracking admin.

usergems_mcp_import_upload

ChatGPT
Opens an inline dropzone for uploading a spreadsheet (csv, xlsx, xls, up to 100 MB) straight to the UserGems backend. Returns an upload_token that usergems_mcp_await_import_upload takes to block until the user drops the file and returns the column headers plus a sample row. The file content never enters the conversation, so there is nothing for the user to paste. Only for the csv source of the import playbooks (usergems_mcp_import_contacts_playbook / usergems_mcp_import_accounts_playbook); Salesforce reports and Google Sheets use usergems_mcp_read_import_headers instead.

usergems_mcp_instructions_playbook

ChatGPT
Call this FIRST whenever the user wants to change how Gem-E writes emails: a rule, tone, length, language, angle, CTA, exact copy, the steps in a sequence (adding, dropping, or reordering emails, LinkedIn steps, or call briefings), or what Gem-E should or should not mention, whether for every email, one campaign, a group of prospects, or prospects with a certain signal. It decides where the change belongs (company instructions, campaign instructions, a conditional instruction, or a signal playbook) and which playbook to follow next. It saves nothing itself. Use it when the request is tied to UserGems: the user names UserGems, Gem-E, the Writing Agent, the content library, or a UserGems campaign or signal playbook, or earlier messages in the conversation were about their UserGems setup. The user doesn't have to say "Gem-E rule" or "email" then. Not for rules meant for another connected tool (a CRM, a sales engagement or email tool) or for how you write yourself. Call it before proposing or saving any writing change in UserGems (content items, campaigns, instructions), including a follow-up about a campaign or item you just looked up, or a request about one email or step in a sequence.

usergems_mcp_launch_readiness_playbook

ChatGPT
Returns the 6-step pre-activation gate for a sizing, spot-check, or launch-readiness question: sizing, sample, caps, suppression, test run (the app's simulation), and setup checklist, each step ending with a numbered menu of remaining steps. Useful for requests like 'how big is the audience for X', 'spot-check X', 'is X ready to go live', 'caps for X', 'suppress Y in X', or 'test run on X'. For a named existing campaign, write steps target that campaign; for an ad-hoc audience, they stay read-only advice on what to configure at launch. It ends with the audience ready to switch live in the in-app builder, with no pivot to campaign creation; campaigns are not activated from MCP.

usergems_mcp_list_audiences

ChatGPT
Finds a saved audience (filter) by name. This is the way to locate an audience when the user names one (e.g. "the ABX - CL x Referrals audience", "my ICP filter") without already having its id. search is a case-insensitive partial match on the audience name. To find an audience by name, use this tool, not usergems_mcp_campaign_list_workflows: that tool's search matches campaign names only, and an audience with no campaign attached never appears there. Each row returns id, name, conditions_count, is_default, and campaigns: every campaign reading that audience with its active flag, showing the blast radius of an edit before it is made. The id feeds usergems_mcp_save_audience to read and change the full conditions, and the same tool called with conditions and no id saves a new audience, no campaign needed. A shorter fragment or no search browses when nothing matches. include_conditions returns the saved definition through this read-only tool.

usergems_mcp_list_company_lists

ChatGPT
Lists every company list of the workspace the way the Company Lists table shows them, 20 per page ordered by category then newest first, each with its settings. Start here to find a list by name (including one you just created with usergems_mcp_import_accounts_report, usergems_mcp_add_accounts or an upload), to read how it is set up, or to get a list_id for usergems_mcp_get_company_list_accounts. Each list carries: id, name, category (customer, openOpp, competitor, target, closedLost, other, disqualified, signal) with category_label, source (csv, google_sheet, salesforce_report, salesforce_query, hubspot_list, audience_filter, or usergems when UserGems fills the list itself, e.g. a signal's list or an automatic import) with source_id (the CRM report or list id, the Google Sheet id, or the audience filter id), signal_id when a signal feeds or fills the list, research_id when a research wrote it, persona (id + name) and prospect_search (enabled, mode current_prospects or lookback) for lists UserGems finds prospects in, refresh (days and frequency), max_companies (the import cap), owner (the user the list belongs to), column_mappings (which column of the source fed each field), accounts_count (active companies in the list), active (false while paused), paused_at, last_imported_at and created_at. url opens the table. Not the same as list_reports: that one is the Research Agent's scope picker with ids and counts only. Deactivated and hidden lists are excluded, as on the screen. Pure read.

usergems_mcp_list_contact_lists

ChatGPT
Lists every contact list of the workspace with its settings, the Track contacts screen (/settings#track-contacts) read out: lists feeding a custom signal and lists uploaded only for segmentation alike. The read counterpart of usergems_mcp_import_contacts_report and usergems_mcp_import_contacts_salesforce_query, so a list created there can be found again by name. Each list carries: id, name (what the screen shows), source (csv, salesforce_report, salesforce_query, hubspot_list, google_sheet, or a native feed such as usergems_signals), source_id (the Salesforce report, HubSpot list or Google Sheet id behind it), query (the SOQL of a salesforce_query list, the one usergems_mcp_import_contacts_salesforce_query or the signal tools created it from; null otherwise), active and disabled_reason, deleting, relationship_type (id, name, code, category: the relationship the contacts are tracked under), signal (id and name when the list feeds a custom signal, else null), contacts_count (the size of the last import), contacts_tracked (how many of those UserGems tracks), limit_contacts (true when capped at 5000 contacts), refresh (cycle and next_date), owner (the user who uploaded it), column_mappings (field => column of the source, same field names the import tool accepts) and created_at / last_imported_at. Paginated; total is the full count and has_more says whether another page follows. For the contacts inside a list use usergems_mcp_get_contact_list_members; for the records a signal-fed list produced with sub-signal matches use usergems_mcp_get_signal_records. Pure read.

usergems_mcp_list_icp_options

ChatGPT
The values the ICP Configuration screen accepts, so an ICP is never created or edited with a value that silently matches nothing: this workspace's account lists (reports) and the account types it has lists for (account_types), plus the industry vocabulary (115 entries), the five regions, and the country list. Industries and countries are matched literally against the company data - a spelling the picker does not have matches zero companies. Pass sections to keep the answer small. Pure read.

usergems_mcp_list_icps

ChatGPT
Lists every Ideal Customer Profile of the workspace with its full criteria - employee range, revenue range, industries, regions and countries, company category and software focus - plus the account lists each one is measured over and its coverage percentages. This is the ICP Configuration tab of /icp-scoring, read out. A workspace usually has several ICPs ("Main (50-20k EE)", "SMB", ...); current_icp_id marks the one the workspace falls back to, which is what the user means by "our ICP". Start here for anything about the ICP setup, and for "why isn't this company in my audience?" - a company outside the ICP never appears in an audience filtered on it. The coverage numbers here are the stored ones, refreshed after every save, so this stays cheap on a large workspace; usergems_mcp_get_icp with recalculate_coverage: true gives a live count. Pure read. Takes no parameters.

usergems_mcp_list_influenced_opportunities

ChatGPT
Lists the opportunities UserGems influenced, one row per opportunity with the UserGems contact that drives the attribution: the opportunities behind influenced_opps in usergems_mcp_get_pipeline_metrics, with the same filters. Use it for "which opps did we influence last quarter?", "our biggest sourced deals" or "which opps are behind this pipeline number?". Each row has opp_id (the CRM id; pass it to usergems_mcp_get_opportunity_attribution to explain why one opp counts), the opp (name, type, stage, created and close date, amount as a number as the CRM holds it, probability, owner, lead source), the account (name, owner), the CRM campaign (crm_campaign_id, crm_campaign_name), the UserGems contact (name, email, title, the date UserGems found the contact, source report, past relationship, signals), engagement (first activity date, last activity date as contact and as lead, count of activities) and attribution flags (influence_type, where a type set by hand wins over the computed one; is_contact_created_in_crm_by_ug; added to the opp when it was created; is_primary; ug_counts_strict; count of opp contacts and of primary opp contacts). ug_counts_strict is the CRM sync's strict flag; it can differ from influence_type when the type was set by hand, and it is null for HubSpot. A value the CRM does not send is null; every row has the same keys. Under date_range the list holds the opportunities active in the period (created before it ends and not closed before it starts), as influenced_opps counts them. Every page has totals for the whole list: count, sum_amount (amounts above 0 only, as value and formatted) and by_influence_type; totals_note says what is counted. Without search and more_filters, count and sum_amount equal influenced_opps and influenced_pipeline of usergems_mcp_get_pipeline_metrics for the same filters, influence types and deal stages, unless that tool answers from its 24-hour cache. Answer questions about the whole list from totals; read the rows only when the question needs them. The default order is created date, newest first; sort and sort_direction change it, and opps with no value for the sort come last. Rows come page_size at a time; when has_more is true, send next_cursor as cursor, with the same other inputs, for the next page. Pages are read live, so a CRM sync between two calls can move an opp to another page; a changed totals.count shows that the list changed. A filter value the workspace does not have is refused with a message that says what to send. Pure read.

usergems_mcp_list_personas

ChatGPT
Lists every persona of the workspace - the Personas tab of /settings, read out. A persona is the set of job titles UserGems searches for and matches people against, so it decides who ends up in a prospect search and in any audience filtered on persona. Each entry carries the id and name (what usergems_mcp_import_accounts_report and usergems_mcp_setup_signal take), plus what the list page shows: coverage_pct, use_for_persona_matching, importance, strict, active_reports, and a short summary of the keyword groups, the excluded titles, country rule, industry rule and their missing-value choices. use_for_persona_matching: false means nobody is ever assigned to that persona, the usual cause of an unexpectedly empty audience. Coverage counts job titles only, not company industries, and is the stored number from the last save, so this stays cheap; usergems_mcp_get_persona with recalculate_coverage: true gives a live one. usergems_mcp_create_persona_playbook covers creating one when none of the existing personas fit or the list is empty. Pure read. Takes no parameters.

usergems_mcp_list_relationship_types

ChatGPT
Lists the workspace's relationship types ({id, name, is_default}) so the contacts import flow can display them with the default ('Other') pre-selected before creating an import with usergems_mcp_import_contacts_report. Read-only.

usergems_mcp_list_salesforce_reports

ChatGPT
Finds Salesforce reports by name so the user can reference a report in words instead of pasting its id. Returns {reports: [{id, name, folder_name, developer_name, last_modified_at}], truncated} for the non-private reports whose name contains the search term, most recently modified first. Salesforce orgs routinely hold several reports with the same name in different folders, so folder and last-modified date matter alongside the name. The chosen id is passed as source_id to usergems_mcp_read_import_headers. Searches as the Salesforce import user, so a found report is one the import can read. Private reports are not searchable. Read-only.

usergems_mcp_list_scoring_models

ChatGPT
Lists every scoring model of the workspace - the Signals tab of the Scoring Model page (/scoring-model/signals), read out. A scoring model is the set of signal points and buying-stage rules a group of ICPs scores with; the default model covers every ICP that has no model of its own. Each entry carries the id and name usergems_mcp_get_scoring_model takes, is_default, and icps - the ICPs scoring with it. Start here for "how does my scoring work today?". A workspace that never opened the page has no models yet: the list comes back empty and says so, each ICP then scores from its own signal points, and opening the page (or usergems_mcp_create_scoring_model) creates the first ones, a default model plus one per ICP, from the signal points the ICPs already use. usergems_mcp_edit_scoring_model and usergems_mcp_delete_scoring_model take the same ids. Pure read. Takes no parameters.

usergems_mcp_list_signals

ChatGPT
Lists every signal of the workspace, the /signals screen read out: the persisted signals first (activated and inactive, status active/inactive) with their FULL settings, then the native catalogue entries the workspace has not activated yet (status not_activated, id null, no settings). Start here for anything about the signal setup and before reviewing, editing or proposing a signal. Each persisted signal carries: name (the tag shown in audiences and the Chrome extension), category, provider, record_type (contacts or companies), active, show_tag (false when the signal is hidden from Gem-E), importance_score, conditions (the main signal filters: outer array OR-ed, inner AND-ed, each {field: {name, json}, operation, values}), filters (the same groups read out for humans: the screen's label for each field, the operation in words, window_days for date windows, and value_labels with the ICP, persona, intent topic, account list and LinkedIn campaign NAMES behind the ids; intent_frequency carries days and meaning: at least N distinct days with intent inside the tracking window), sub_signals (each with id, name, description, active, show_tag, importance_score, conditions, filters), settings, auto_find_prospects (company signals only: enabled, max_companies, icp_only, icp_ids + icps, persona_id + persona), source (uploaded signals only: type csv / salesforce_report / salesforce_query / hubspot_list / google_sheet, name, refresh), inputs (the lists that feed the signal, with what the account-lists table shows about each: account_lists[] with role signal_report / uploaded_list / customer_list, source, accounts_count, max_import_accounts, last_imported_at, paused_at; contact_lists[] with role uploaded_list / tracked_contacts, source, contacts_count, contacts_tracked, refresh; and a summary. Customer Competitors lists every active customer list of the workspace, narrowed to the lists selected by a customer_report_id condition when the signal has one; the job-change signals every tracked contact list. A signal with 0 records and empty or 0-account inputs has nothing to match, say that first) and url. availability is available, talk_to_csm or connect_app: talk_to_csm means the workspace's package does not include the signal, so one of those cannot be activated or configured from here; the CSM enables it. Catalogue entries that need an app connected first are connect_app with requires_connection. The settings come back in the shape the signal setup tools accept, so a signal can be read, changed and written back. Data only: whether a signal works well is a judgement for the review playbook, not this tool. Pure read; a workspace with 20+ sub-signals on one signal can make the answer long, so filter, or use usergems_mcp_get_signal for one signal.

usergems_mcp_new_feature_playbook

ChatGPT
Useful when the user wants to add a product feature, product update, launch announcement, or release notes to the Gem-E content library: a feature or product page URL, a release-notes or "what's new" page, an uploaded file, or pasted text. Call this BEFORE content_generate or content_create for any new feature. This includes text the user pastes and asks to add or save as is: content_create saves exactly what it is given, so pasted text still goes through this playbook first to be put in the library format and previewed. It sets the required new feature format for the Gem-E library, even if the user has their own skill or template. Returns the procedure: read the source with your own tools, write each feature in the standard format, suggest an end date, a release-date filter, and an audience filter when the user names one, preview, get one confirmation, then save exact values with content_create.

usergems_mcp_persona_vocabulary

ChatGPT
The values the persona editor accepts, so a value is never guessed: seniorities (the dropdown of the keyword groups), importances, strictness, country_modes, regions, countries, plus this workspace's own coverage_sources (the contact lists coverage can be measured over) and common_titles (the job titles those contacts actually carry). usergems_mcp_create_persona and usergems_mcp_edit_persona match seniorities and country codes literally; a value outside these lists is refused, and a persona built on a guess matches nobody. common_titles is the other reason to use it - when the user has no list of titles in mind, their own contacts are the material to build the keyword groups from. Pure read; nothing here is workspace-specific except the last two sections.

usergems_mcp_publish_instructions

ChatGPT
Publishes an instruction draft so it actually takes effect - campaign-level or company-wide, whichever the draft belongs to. Update tools save a draft rather than publish on their own, so the user can see the result first. Useful once the change is previewed (e.g. via usergems_mcp_draft_prospect_email with preview_instructions_chat_message_id) and the user has confirmed explicitly. Only the latest draft on a chain can be published. If the campaign is live, the tool refuses until campaign_is_live_acknowledged is set to true, which requires telling the user the campaign is live and that the next run sends real messages, and getting a specific yes to that - a general yes earlier in the conversation does not count.

usergems_mcp_read_import_headers

ChatGPT
Reads the column headers and one sample row of an import source for the column-mapping conversation: an already-uploaded spreadsheet (source=csv with the upload_id), a Salesforce report (source=salesforce_report with the report id) or a Google Sheet (source=google_sheet with the sheet id). Returns {headers, sample_row}, plus the source's own name for Google Sheets and Salesforce reports (a good report-name suggestion). It never returns the row data, so it is safe for arbitrarily large sources.

usergems_mcp_reorder_icps

ChatGPT
Sets the priority order of the workspace's ICPs, the same update as dragging the rows of the ICP list on /icp-scoring or on the ICP tab of the Scoring Model page. icp_ids is the full list of ICP ids in the wanted order, the first gets priority 1 (ids from usergems_mcp_list_icps); a list that misses an ICP, repeats one or names an unknown one is refused with the workspace's ICPs listed. The order decides which ICP an account scores with when it matches several: the first matching one. The fallback ICP is the one marked with the fallback flag (usergems_mcp_edit_icp), so the order does not change it; only when no ICP is marked is the first ICP the fallback, and the answer then says when it moves. Like the page, the reorder itself starts no re-matching and no rescore. Without confirm: true nothing is written and the answer shows the current and the proposed order; with confirm: true it saves. Requires an Account Tracking admin role.

usergems_mcp_resolve_closed_lost_reason_field

ChatGPT
Canonical resolver for 'where does this workspace store closed-lost reason?'. Used by the usergems_mcp_signal_campaign_playbook closed_lost_revive branch (Q1) at Phase 3, instead of inspecting usergems_mcp_audience_filter_instructions blind. Returns one of three shapes: (1) salesforce_field - the SF field is mapped into filterable fields, apply directly; (2) sub_signal - closed-lost reason lives as sub-signals under a 'Closed Lost' parent signal; (3) not_configured - the resolver's conservative substring patterns did not match. On not_configured, the ## Custom-field discovery section of the main signal_campaign_playbook covers the fallback: call usergems_mcp_audience_filter_instructions with a substring field_filter and rank candidates by their CSM-authored description. Handles workspace-specific shorthand (e.g. CL_Reason__c) the resolver's name-substring patterns are not built to catch. Read-only; safe to call multiple times per session. No parameters - operates on the caller's company implicitly.

usergems_mcp_save_audience

ChatGPT
Saves an audience (filter): creates a standalone one or edits an existing one in place. Any user can call it; no admin role is needed. Create: conditions (built with usergems_mcp_audience_filter_instructions) plus a name, with no audience_id or campaign_id. No campaign is needed or created, so this builds and saves a marketing audience on its own. The response returns created: true, audience.id and audience_url, which are the id and the link of the saved audience. A saved audience appears on the web app's Audiences page and in usergems_mcp_list_audiences, and usergems_mcp_create_campaign can take it as audience_id. Edit: the audience is located with audience_id, or with campaign_id for whatever audience that campaign currently uses. Every campaign pointing at the audience keeps its link and sees the new conditions, so an audience changes without orphaning the old one. Called with only a locator and no name / conditions, it writes nothing and returns the audience's name, its conditions, and affected_campaigns: every campaign that reads it, with its active flag. An edit is written only with confirm: true. Without it the call validates the change, writes nothing, and returns requires_confirmation: true, changed_fields, current, proposed and affected_campaigns, so the before and after can be reviewed with the user first (campaigns named, live ones flagged); the same call with confirm: true then writes it. An audience can be shared: a confirmed edit is immediately live for every campaign in affected_campaigns. Use this instead of usergems_mcp_edit_campaign's audience_conditions to change an existing audience; use audience_conditions only to point a campaign at a different audience. usergems_mcp_list_audiences finds an audience by name, the only way to reach one with no campaign attached. usergems_mcp_campaign_list_workflows answers the reverse question: each row carries its audience, and audience_id narrows the list to one audience's campaigns.

usergems_mcp_set_workflow_limits

ChatGPT
Creates or updates the WorkflowLimit row for a campaign - caps (per total / account / owner / dri / sdr, each with optional frequency: day/week/month/year), drip-mode (instantSending=false), skip-delays, and the cross-campaign ignoreCompanyLimits toggle. Useful for the usergems_mcp_launch_readiness_playbook Step 3 (caps), or whenever the user asks to 'cap to N/day', 'limit per AE' or 'drip rollout'. Read-only mode: call with only campaign_id (no settings) to fetch the current limits without mutating. Write mode: pass settings as a JSON object matching the WorkflowLimitSettings shape used by the in-app builder (account, owner, dri, sdr, total - each {active, limit, frequency} - plus the boolean toggles).

usergems_mcp_setup_signal

ChatGPT
Creates or updates a native signal, the signal setup screen as one call, and previews how many records match before saving. Takes the shape usergems_mcp_get_signal returns, so read a signal, change it and send it back: name, description, show_tag, active, importance_score, conditions, the full sub_signals list, settings and auto_find_prospects (company signals). Target an existing signal with signal_id, or a type with category (plus provider and record_type when the type has several): a type that allows one signal per workspace updates and switches on the row that exists instead of adding a second one, which also covers activating a not-activated card with its filters. Call usergems_mcp_get_signal_setup_options first for the fields, operations and values the type takes, and use dry_run before saving. Fields and operations are checked against that list. Job changes, research signals and list-backed signals (custom lists, third-party intent, website visitors from other providers) are pointed to their own tools.

usergems_mcp_signal_campaign_branch_playbook

ChatGPT
Returns the branch-specific instructions for a single play_type detected in usergems_mcp_signal_campaign_playbook Phase 1, used before Phase 2. Valid play_type values: past_champions, competitor_takedown, closed_lost_revive, multi_thread, website_visitors, job_changes, account_list_segment.

usergems_mcp_signal_campaign_playbook

ChatGPT
Useful when the user describes a signal-driven outbound campaign: past champions, competitor takedown, closed-lost revive, multi-thread, website visitors, job changes / new hires / promotions, or an account-list segment. Branches on play_type and returns the CSM-guided talk-track (probing questions, default filter recipe, default action stack, suppression defaults, anti-deviation rules) used before usergems_mcp_create_campaign_playbook and then usergems_mcp_create_campaign. Not for a campaign on an already saved audience - that goes straight to usergems_mcp_create_campaign_playbook with its audience_id.

usergems_mcp_signal_playbook_guidance_playbook

ChatGPT
Useful when the user wants to change how Gem-E handles one signal through its built-in signal playbook: add, change, or remove custom guidance for new hires, promotions, past champions or customers, closed-lost, open opportunities, colleagues at the account, company news (funding, expansion, partnerships, mergers, acquisitions, product announcements), hiring, tech stack, or website visits. Also for requests to keep colleagues' names or past employers out of emails across playbooks. Call this BEFORE content_edit on any signal playbook. Edits there go live immediately with no undo, so it returns the required procedure: find the playbook, check Gem-E defaults and the current guidance, judge and tag each rule, show the current and new guidance, get one clear yes for every save (removals and follow-ups included), save only the guidance field, then check it. It never renames a playbook or changes its defaults, filters, or on/off state. Use it when the request is tied to UserGems: the user names UserGems, Gem-E, the Writing Agent, the content library, or a UserGems campaign or signal playbook, or earlier messages in the conversation were about their UserGems setup. The user doesn't have to say "Gem-E rule" or "email" then. Not for rules meant for another connected tool (a CRM, a sales engagement or email tool) or for how you write yourself.

usergems_mcp_signal_setup_branch_playbook

ChatGPT
Returns the signal setup instructions for one signal type: the rules that apply to every signal (what to ask, how to teach the configuration without proposing it, how to list ICPs and personas) and the section of the requested type (what its filters and sub-signals can be built from, what the app creates by default). Call it with the category once usergems_mcp_get_signal_setup_options has given the type's data, and before usergems_mcp_setup_signal or usergems_mcp_create_account_custom_signal. Only the requested section is returned; the valid types are the sections the text has.

usergems_mcp_simulate_campaign

ChatGPT
Queues a simulation of a campaign (workflow), the app's Simulate workflow run. The campaign's pending prospects go through every step with no write to the CRM, the SEP, Slack or the ad platforms, everything is rolled back, and the run records what each step would have created, routed and enrolled, what failed and why, and how records split across reps. Returns the simulation_id with status pending, the prospect_limit it will run and wait_for_result; the run happens in a queued job and usergems_mcp_get_campaign_simulations with that id reads its status and, once completed, its results. Without limit it runs 10 prospects, which finishes within a minute or two, so the result is read back right away (a few reads, seconds apart, until completed or failed) and shown to the user in the same turn. Above 100 prospects wait_for_result is false: the run takes at least five minutes, the user is told it is running, and the result is read on their next message or in a scheduled check where the client can run one. Works on an inactive draft, so a campaign can be checked before it is activated in the app; the MCP does not activate campaigns. Same defaults as the app's Simulate modal otherwise: the limit counts attempted prospects, and no CRM data refresh runs first. Refused with the app's message while a simulation of the campaign is still pending or running today; the response then carries the id of that run. The simulation engine is reused as it is: a step that is skipped is absent from the summary, some failures carry only the generic 'An error occurred' message, and a run left pending or running by a lost worker is closed as failed by the daily cleanup after 24 hours.

usergems_mcp_submit_feedback

ChatGPT
Persists the UserGems product feedback collected by usergems_mcp_feedback_survey (feedback about UserGems, not about Claude). Takes an answers object with was_helpful ("yes" or "no", required) and comment (optional free text), passed as given. Writes one row to gem_e_feedback_submissions.

usergems_mcp_suggest_persona_titles

ChatGPT
The persona editor's "Show suggestions" button: reads the job titles this workspace's contacts actually carry and proposes the keyword groups that would cover the ones a draft persona misses, plus the titles worth excluding. It also returns the coverage before and after, so the value of the suggestions can be judged. Useful while building a persona - with no title_groups it suggests from scratch, which is the right start when the user has no list of titles in mind; with a draft it suggests what to add. The suggestions are a starting point for review, not something to save unreviewed: they come from one contact list and routinely include a role the user does not sell to. It walks the contact list twice and can take up to a minute. Writes nothing. Returns a plain error when the workspace has no contact list to read from.

usergems_mcp_update_icp_fit_factors

ChatGPT
Changes the fit factors of one ICP the way the Fit factors tab of the Scoring Model page does, through the page's own scoring save. Fit factors are the company traits an account is scored on (industry, tech stack, company size, funding, growth, hiring, news, departments, focus, target market, announcements), plus the account-type tags (target, ICP, customer, competitor, disqualified account). Called with no changes it reads the tab and writes nothing: factors lists, per importance bucket, the factors the tab shows (the 30 highest scored plus the manual and disqualified ones and the account-type tags, or with strict scoring the saved selection; the hidden factors still count unless strict scoring is on) with their label, category and, while points_shown is true, their points; usergems_mcp_get_icp does not list them. Each change names a factor by its label (as factors or the catalogue spells it, e.g. salesforce; a unique factor name matched case-insensitively works too) and one of: importance (highest, very_high, high, moderate, low), which lands it at the bottom of that bucket like the page's "Move to" menu, re-spacing the factors moved in this call evenly between the last untouched factor of the bucket and the bucket's lowest points (the bucket's middle when it is empty; a factor already in that bucket stays where it is); points, like typing them (1 to 100, which the tab offers only while the company's Advanced scoring setting is on; outside the range the nearest bound); disqualify: true, which moves it to the Disqualifying bucket (an account with that trait scores nothing); remove: true, like the page's Remove (the factor leaves the tab and no longer counts; an account-type tag stays listed at 0); or reset: true, which puts a factor set by hand back on its catalogue points (a no-op on any other, as the page offers Reset only there). Stored negative points are a penalty, reported as Negative with the points, not a disqualification. A factor not listed on the tab is added by a change, like "+ Add factor". strict_scoring switches the tab's strict scoring setting (true: only the listed factors count, with their points locked) and limit (10, 30, 50, 100, all) its "Show top" setting, which decides what is listed and, with strict scoring on, what is locked. Changes apply one after the other and are saved in one go; with strict scoring on, the factors the tab lists (the saved selection or the highest scored, plus the ones added, minus the ones removed) are sent as the strict selection, as the page does, so the save locks them and stores the rest at 0; accounts are rescored by the next scoring run. Without confirm: true nothing is written: changes lists, per factor, the bucket before and after (with the points while points_shown is true), strict_scoring the toggle before and after, and selection the factors a strict save would lock or unlock. With confirm: true it saves. url is the page of the ICP. Requires an Account Tracking admin role.

usergems_mcp_update_signal_scoring

ChatGPT
Changes the importance (points) and/or the buying stage of signals in one scoring model, the way the Signals tab of the Scoring Model page (/scoring-model/signals) does. Each change names one signal (signal_id, sub_signal_id or signal_name as usergems_mcp_get_scoring_model lists them, plus scope for a signal that scores in both scopes) and one way to move it: importance (a bucket name) lands it at the bottom of that bucket like the page's "Move to" menu; after and/or before (names of other rows in the same scope) drop it next to them like a drag, so it takes the rounded midpoint of its two neighbours' points, with the bucket edge standing in for a missing neighbour; points keeps the exact value, 1 to 100, like typing it, which the page offers only while the company's Advanced scoring setting is on (with it off the tool refuses points and says so). disqualifies stores what the page stores (-1000 and the flag for a company signal, -100 for a people one). stage moves the signal between the buying-stage buckets; not_used also turns the signal's decay off, as on the page; it needs the Buying Stages add-on and never applies to a prospect similarity. One call is one page session: every row moved in it stays moved, and each move spaces out the whole run of moved rows evenly between the nearest untouched neighbours again, as the page does before Save, so several drops into one gap land on evenly spread points; typed points are kept as they are and later moves space around them. The whole list is saved in one go and every ICP on the model is rescored once, so put all the changes of one request in one call. Without confirm nothing is written: changes lists, per signal, the importance and stage before and after, with the points while Advanced scoring is on (advanced_scoring; with it off the answer names no points at all), and placed says where it landed, one signal per line when read out. With confirm: true it saves through the page's own save, keeping every setting the change does not name (stage, decay, recency) as it is, and rescored_icp_ids lists the ICPs being rescored; a list whose changes cancel out writes nothing.

usergems_mcp_value_proposition_playbook

ChatGPT
Useful when the user wants to build, add, or update the seller's value proposition in the Gem-E content library: what their company does, its products and integrations, and the pain points it solves for each persona, from a product or overview page, several pages, an uploaded file, or pasted text. Call this BEFORE content_generate or content_create for any value proposition. This includes text the user pastes and asks to add or save as is: content_create saves exactly what it is given, so pasted text still goes through this playbook first to be put in the library format and previewed. It sets the required value proposition format for the Gem-E library, even if the user has their own skill or template. Returns the procedure: check the library (only one value proposition is used per prospect, picked top-down), read the sources with your own tools, list the existing value propositions, how they are picked, and the personas at the top of the preview, write the value proposition and persona pain points in the standard format, flag anything taken from other sources, preview, get one confirmation, then save exact values with content_create.

Capabilities

WritesInteractive

Example Prompts

Click any prompt to copy it.

Similar Apps

Listed on MCP App Store

Listed on MCP App Store

Add this badge to your site or README. It links to this page.

HTML

<a href="https://mcp-app-store.keenethics-labs.com/app/usergems"><img src="https://mcp-app-store.keenethics-labs.com/badges/listed-on-mcp-app-store.svg" alt="Listed on MCP App Store" width="220" height="44"></a>

Markdown

[![Listed on MCP App Store](https://mcp-app-store.keenethics-labs.com/badges/listed-on-mcp-app-store.svg)](https://mcp-app-store.keenethics-labs.com/app/usergems)