HubSpot

<purpose> Retrieves guidance and usage instructions for a set of HubSpot tools. </purpose> <when_to_use> - If a tool's description isn't enough to commit to using it - To find if a tool's inputs or outputs have further semantic meaning - To learn understand if and how certain tools can work together </when_to_use>

tool_guidance

Searches HubSpot schema to discover available data types or look up known types directly. <capabilities> - Searches across all HubSpot data types available to the current user - Returns type names that can be used as input to other tools - Shows read/write access status for each type based on the current user's permissions </capabilities> <usage_guidance> - Use this tool FIRST when you need to identify which data types exist before querying data - Use SEARCH_OBJECT_TYPES when you don't know the exact type name - Use GET_OBJECT_TYPES when you already know the type names (e.g. CONTACT, DEAL), or with an empty typeNameFilter list to retrieve all available types - Check readAccess/writeAccess before attempting operations on a type </usage_guidance> <examples> <example> <user_input>How many support requests did we get last month?</user_input> <thoughts>The user is asking about support requests. I need to find the right data type to query.</thoughts> <tool_call>{"query": {"_queryType": "SEARCH_OBJECT_TYPES", "searchTerms": "support requests tickets"}}</tool_call> </example> <example> <user_input>Show me our fleet vehicle records</user_input> <thoughts>Fleet vehicles is likely a custom object. Let me discover it first.</thoughts> <tool_call>{"query": {"_queryType": "SEARCH_OBJECT_TYPES", "searchTerms": "fleet vehicles"}}</tool_call> </example> <example> <user_input>How many products do we have?</user_input> <thoughts>"products" is ambiguous — it may be HubSpot's standard Products object or a custom object like p12345_product_models, and semantic search tends to rank the standard one first, so I won't just take the top hit. I'll review all candidates and, if more than one plausibly matches, ask the user to clarify before querying.</thoughts> <tool_call>{"query": {"_queryType": "SEARCH_OBJECT_TYPES", "searchTerms": "products"}}</tool_call> </example> <example> <user_input>What fields are on contacts and deals?</user_input> <thoughts>The user already named the types. I can look them up directly.</thoughts> <tool_call>{"query": {"_queryType": "GET_OBJECT_TYPES", "typeNameFilter": ["CONTACT", "DEAL"]}}</tool_call> </example> <example> <user_input>What types of data does HubSpot have?</user_input> <thoughts>The user wants to see all available types. I'll use GET_OBJECT_TYPES and omit typeNameFilter to retrieve everything.</thoughts> <tool_call>{"query": {"_queryType": "GET_OBJECT_TYPES"}}</tool_call> </example> </examples>

REQUIRED FIRST STEP: before your first call, invoke tool_guidance for "get_campaign_attribution_reports" and follow it. The dimension names, filter syntax, date-range semantics, grouping rules, and query patterns live in tool_guidance, not in this description; calling this tool without them produces wrong or failed queries. Attribution data tool: all metrics (revenue, deal amounts, deal counts, contact counts) are scoped to the closed-won deal attribution pipeline. Use for revenue, attributed deal, and attributed contact questions. CONTACT_COUNT = contacts whose interactions influenced closed-won deals; this is NOT a "new contacts generated" metric. For non-attribution contact queries (new contacts, influenced contacts, sessions), use read_campaign_data with GET_ANALYTICS. Scope note: this data covers closed-won / attributed deals only. For deals at any stage (open, opportunity, qualifiedtobuy, and so on), use read_campaign_data with operation=GET_ASSET_METRICS and assetType=DEAL (returns name, stage, amount, close date for all associated deals) or search_crm_objects with a campaign association filter. For long-running queries, this returns a PROCESSING status with a taskId to poll for results.

Run a content analytics report across landing pages, website pages, and blog posts in the portal. Returns: TOTALS: ranked rows of contentId, contentTitle, and the requested metric value. TIME_SERIES: per-contentId series of {timestamp, value} points for the requested metric and period. SUMMARY: aggregated per-period points (one value per bucket) for the requested metric. PEOPLE: list of contacts/visitors (contactId or session identifier, plus available identity fields) who viewed the specified contentIds. Pick mode by intent: TOTALS to rank, TIME_SERIES to chart trends per page, SUMMARY for a single aggregated trend, PEOPLE for who-viewed lookups. TIME_SERIES/PEOPLE require contentIds. Examples: mode=TOTALS metric=VIEWS limit=10 -> top 10 pages by views. mode=TIME_SERIES contentIds=[123] metric=SUBMISSIONS period=LAST_30_DAYS -> daily submissions for page 123. Requires 'Read analytics related to pages, blogs and other content assets' permission and a Pro or Enterprise portal.

Fetches multiple CRM objects of the same object type in a single request. <returns> A list of CRM objects with their properties, identified by their unique IDs, containing: - id: Unique identifier for the CRM object - properties: Key-value pairs of property names and their values - createdAt: Timestamp when the object was created - updatedAt: Timestamp when the object was last updated - url: URL to view the object in HubSpot </returns> <usage_guidance> - Use the `search_crm_objects` tool to list a few objects first without a filter criteria - Then use the `get_crm_objects` tool to retrieve those objects by their IDs without any properties in the tool input to understand the data model - This will help you understand the structure of the objects and their properties </usage_guidance>

Lists organization-wide teams, job titles (roles), seats, and account information (eg timezone, currency). Use the include parameter to request only the data you need. <returns> - GUIDANCE (optional): Returned if additional context is required so provide a useful response Only fields listed in the include parameter are returned (or all fields if include is omitted): - TEAMS: Team objects with name, member's owner IDs, and metadata (org-wide, not personal — for the current user's team use get_user_details with include=[TEAMS_AND_ROLES]) - SEATS: Available seat type names in the organization (use these as filters with search_crm_objects on USER objectType to count how many users hold each seat) - JOB_TITLES: Job titles/roles present in the organization - ACCOUNT_INFORMATION: Account timezone, currency, account type, UI domain, account ID, portal name, and create date (epoch millis). Portal name and create date require the portal-context-metadata rollout </returns> <usage_guidance> - IMPORTANT: Check if user query contains first-person language ("my team", "my role", "my manager", "my direct reports") - If query uses "my", "I", or "me" referring to personal context → Use get_user_details instead - EXCEPTION: "my teams" or "which teams am I on" should use this tool since get_user_details only returns a single primaryTeam - If query is organization-wide ("our marketing team", "the sales team", "all managers", "my teams") → Use this tool - Use the include parameter to fetch only what you need and reduce response size - Include TEAMS when you need team membership or structure - Include SEATS when you need available seat types - Include JOB_TITLES when you need roles/job titles to filter users by role - Include ACCOUNT_INFORMATION when you need the account's timezone, currency, account type, UI domain, portal name, or create date - To find or count users by role or seat, use the returned job titles or seat types as filters with search_crm_objects on USER objectType - SEATS returns only seat type names, not user counts — you MUST follow up with search_crm_objects to get user counts per seat type - When the user references a team's data (e.g., 'our sales team's deals', 'marketing team pipeline'), use this tool first with include=[TEAMS] to resolve team membership to owner IDs, then pass those IDs as filters to search_crm_objects. - To find "my teams" (plural), call this tool with include=[TEAMS] and find teams with the user's ownerId -- [IMPORTANT]: DO NOT use member name for matching, only use ownerId - [IMPORTANT] If the `guidance` field is present, read it carefully before responding — it may contain a user-facing message (e.g., missing permissions requiring reauthorization) that must be relayed to the user, or an agent-internal hint (e.g., name disambiguation) that should influence how you process the results </usage_guidance> <examples> <example> <user_query>Who works in sales at my company?</user_query> <action>Use this tool with include=[TEAMS] to get teams, then filter for sales-related ones</action> </example> <example> <user_query>Show me deals for MY team?</user_query> <action>Do NOT use this tool, use get_user_details instead</action> </example> <example> <user_query>Search deals for all marketers</user_query> <action>Use this tool with include=[JOB_TITLES] to find marketing-related roles</action> </example> <example> <user_query>How many users have each seat type?</user_query> <action>Use this tool with include=[SEATS] to get seat type names, then use search_crm_objects on USER objectType filtering by each seat type to count users per seat</action> </example> <example> <user_query>Show me our sales team's deal pipeline</user_query> <action>Use this tool with include=[TEAMS] to get the sales team's member owner IDs, then use search_crm_objects to filter deals by those owner IDs.</action> </example> <example> <user_query>Which teams am I on?</user_query> <action>Use this tool with include=[TEAMS] to get all teams, then find teams that contain the member's ownerID (NOT MEMBER'S NAME)</action> </example> </examples>

Fetches property definitions including data types and enumeration values. <capabilities> - Particularly useful for discovering valid options in enumeration-type properties - To search for actual data, use search_crm_objects </capabilities> <returns> List of property definition objects containing: - name: Property identifier - label: Display label - description: Property description - type: Data type (string, enumeration, number, etc.) - options: For enumeration types, list of valid values with labels </returns> <usage_guidance> - Property details can be unexpectedly large. Consider fetching in batches - It's not advised to pass an objects full list of properties into this tool </usage_guidance>

Returns user, team and hub info; CRM/marketing object and tool availability. <usage_guidance> - This tool must be used before performing any operations with Hubspot tools to determine the identity of the user, and permissions they have on their Hubspot account - This tool only return information for the current user. Search for "users" objectType using the search_crm_objects tool to find other users/owners in the HubSpot account - This tool provides the availability of crm object types to the current user. Use these values in tools which expect crm object type parameters - This tool provides more accurate availability of the other tools provided by this MCP service. This is critical when tool returned in the response is not `AVAILABLE` - Every non `AVAILABLE` object type or tool requires some user interaction to resolve, noting that some issues cannot be resolved by just the user themselves - Each object type returns TWO separate availability statuses: `read` for view/search operations and `write` for create/update operations. Check the appropriate permission based on the operation you intend to perform - Use the "include" param to request only the sections you need; omitting it or passing an empty list returns USER_INFORMATION and TOOL_INFORMATION only — TEAMS_AND_ROLES must be explicitly requested - For account-level settings (timezone, currency, account type, UI domain), use get_organization_details with include=[ACCOUNT_INFORMATION] instead of this tool - TEAMS_AND_ROLES returns context specific to the current user only (their primary team, job title, direct reports); for org-wide team or role data, including "my TEAMS", use get_organization_details - IMPORTANT: directReports are not the same as team members. If directReports is empty and the user asked about direct reports: stop, inform the user that no direct reports are configured, and ask whether they want to proceed with team members instead — do not automatically substitute team members for direct reports </usage_guidance> <availability_guidance> <status name="AVAILABLE">It is free to use without issue</status> <status name="REQUIRES_REAUTHORIZATION">The user needs to perform a new authorization flow through HubSpot to unlock new access. This is possible through disconnecting and reconnecting the HubSpot connector through their settings</status> <status name="REQUIRES_PERMISSION_MODIFICATION">The user lacks the correct permission in their HubSpot account. If the only way to resolve a task is to use this tool or object, you should inform the user of their lacking permissions and let them decide if they want to ask their administrator for more privilege</status> <status name="REQUIRES_ACCOUNT_MODIFICATION">The whole HubSpot account lacks the correct permissions and would require an account upgrade. Again, inform the user about these tools or objects only if the presented task can only be solved using them</status> <status name="BLOCKED_FOR_PORTALS_WITH_SENSITIVE_DATA">The operation involves sensitive data, and no troubleshooting will unblock usage of the object or tool. If the only way to resolve a task is to use this tool or object, inform the user of the issue and ask them how they would like to proceed</status> <status name="NOT_AVAILABLE">There is no action the user can take to enable the object or tool. It is simply unavailable for use</status> </availability_guidance> <returns> - Always returned: user ID and Hub ID (accountId) - Only fields listed in the include parameter are returned (or all fields if include is omitted): - USER_INFORMATION: owner ID, name, and email for the current user - TOOL_INFORMATION: a mapping of CRM object types to separate `read` and `write` availability statuses; a mapping of other MCP tools to current availability - TEAMS_AND_ROLES: the current user's job title, assigned seats, primary team with member owner IDs, and direct report owner IDs (personal context only — use get_organization_details for org-wide team/role data) - If the `guidance` field is present, relay its message to the user — it may indicate unrecognized include values, missing permissions requiring reauthorization, or other issues - If present, the onboarded field indicates whether the portal has completed initial setup (true = onboarded, false = new portal that has not been set up yet) </returns> <examples> <example> <user_query>Compare workload across my direct reports</user_query> <action>Call with include=[TEAMS_AND_ROLES]. If directReports is empty, ask the user if they would like to compare workload across their primary team members instead. DO NOT use team members unless user confirms.</action> </example> </examples>

Creates or updates HubSpot marketing campaigns and manages asset associations. <prerequisites> Use CRM tools to retrieve the campaign's campaignCrmObjectId before using CAMPAIGN_UPDATE or CAMPAIGN_ASSET operations. </prerequisites> <mandatory_confirmation_process> Always show proposed changes in a table and get explicit user approval before creating or updating campaigns or modifying asset associations. This step is CRITICAL. <confirmation_rules> - **First confirmation only**: Add this line after the approval prompt: "Want to skip confirmations for this chat? Just ask." - **After 1 confirmation**: Stop offering the skip option, but keep confirming - **If user opts out**: Skip confirmations for remainder of session </confirmation_rules> <confirmation_format> Proposed Changes: | operationType | Field | Value | |-----------------|-------------|-------------------| | CAMPAIGN_CREATE | displayName | Q3 Brand Campaign | Approve? [✅ Yes / ❌ No] Want to skip confirmations for this chat? Just ask. </confirmation_format> </mandatory_confirmation_process> <operations> The `operationType` field is required on every request: - CAMPAIGN_CREATE: set `createRequest` with required `displayName`, optional `startDate`, `endDate`, `goal`, `audience`, `notes`, `customProperties`. - CAMPAIGN_UPDATE: set `updateRequest` with required `campaignCrmObjectId`, optional `displayName`, `startDate`, `endDate`, `goal`, `audience`, `notes`, `customProperties`. - CAMPAIGN_ASSET: set `assetRequest` with required `campaignCrmObjectId`, `assetOperations` (non-empty list of `{action, assetObjectType, crmObjectIds}`). Each entry has its own ADD|REMOVE action. Check `assetOperationFailures` in the response — if non-empty, those operations failed; succeeded ones are already applied. Call CAMPAIGN_ASSET_TYPES_LIST first. - CAMPAIGN_ASSET_TYPES_LIST: no additional fields required. </operations>

Creates or updates CRM objects with properties. Create object associations. <prerequisites> Use the get_user_details tool to identify the ownerId and check supported object types. </prerequisites> <mandatory_confirmation_process> Always show proposed changes in a table and get explicit user approval before creating or updating CRM objects. This step is CRITICAL for you to use this tool correctly. <confirmation_rules> - **First confirmation only**: Add this line after the approval prompt: "Want to skip confirmations for this chat? Just ask." - **After 1 confirmation**: Stop offering the skip option, but keep confirming - **If user opts out**: Skip confirmations for remainder of session </confirmation_rules> <confirmation_format> Proposed Changes: | Object Type | ID | Property | Current Value | New Value | |-------------|-----|----------|-----------------|--------------------| | Contact | 123 | email | old@example.com | new@example.com | Approve? [✅ Yes / ❌ No] Want to skip confirmations for this chat? Just ask. </confirmation_format> </mandatory_confirmation_process> <creating_associations> To create associations between CRM objects: - Use the createRequest attribute to create a new CRM object and associate it with an existing CRM object - Use the updateRequest attribute to associate two existing objects - ALWAYS ask user to confirm which specific objects should be associated before creating associations - Example workflow: create contact → get contact ID → find company ID → confirm with user → create an association </creating_associations> <guidance> - Limit upsert objects and associations to a MAXIMUM of 10 objects per request - Not all properties are editable. Use search_properties tool to list available properties or search_crm_objects to sample existing data before making changes </guidance>