Provides tools for managing HubSpot CRM, including contacts, companies, deals, pipelines, lists, marketing emails, forms, workflows, and properties.
MCP server for HubSpot CRM — 33 tools covering contacts, companies, deals, pipelines, lists, marketing emails, forms, workflows, and properties.
Tool | Description |
| Full-text search across contacts |
| Get a contact by ID with associations |
| Look up contacts by exact email |
| Most recently created contacts, filterable by lifecycle stage |
| Create a new contact |
| Update properties on an existing contact |
Tool | Description |
| Full-text search across companies |
| Get a company by ID with associations |
| List contacts associated with a company |
Tool | Description |
| Full-text search across deals |
| Get a deal by ID with amount, stage, and associations |
| List deals in a specific pipeline stage |
| Most recently created deals, with optional open-only filter |
Tool | Description |
| List all pipelines with stage IDs |
| Deal counts and total amounts by stage — funnel snapshot |
Tool | Description |
| List all contact lists (static and active) |
| Get list metadata including member count |
| Get contacts in a list |
Tool | Description |
| List marketing email campaigns |
| Opens, clicks, bounces, unsubscribes for an email |
| List emails filtered by state (DRAFT, SCHEDULED, PUBLISHED, ARCHIVED) |
Tool | Description |
| List all HubSpot forms |
| Get full form definition including fields |
| Get recent form submissions with field values |
Tool | Description |
| List all automation workflows |
| Get full workflow details including triggers and actions |
Tool | Description |
| List all CRM properties for an object type |
| Get full property definition including enum options |
Tool | Description |
| List HubSpot users that can be assigned to CRM records |
Tool | Description |
| Structured CRM search with custom filters against any object type |
Related MCP server: hubspot-mcp
In HubSpot, go to Settings → Integrations → Private Apps
Create a new private app
Grant scopes: crm.objects.contacts.read, crm.objects.companies.read, crm.objects.deals.read, crm.lists.read, automation, forms, marketing-email
Copy the access token
{
"mcpServers": {
"hubspot": {
"command": "npx",
"args": ["-y", "hubspot-marketing-mcp"],
"env": {
"HUBSPOT_ACCESS_TOKEN": "pat-na1-xxxxxxxxxxxx"
}
}
}
}claude mcp add hubspot -e HUBSPOT_ACCESS_TOKEN=pat-na1-xxxxxxxxxxxx -- npx -y hubspot-marketing-mcpVariable | Required | Description |
| Yes | HubSpot Private App access token ( |
MIT
Look up contacts by exact email address. Returns up to 5 matches.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | Contact's email address |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the burden. It discloses a return limit of 5 matches, but lacks info on authentication, rate limits, or behavior when no match found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, immediate verb, no filler. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple lookup with one parameter and no output schema, the description adequately covers purpose and return limit. It could mention response structure but is complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the parameter description. The description adds 'exact' and 'up to 5 matches', providing useful behavioral context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Look up contacts by exact email address' with a specific verb and resource, and distinguishes from sibling tools like hs_get_contact (by ID) and hs_search_contacts (fuzzy search) by emphasizing exact match.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when you have an exact email, but it does not explicitly state when not to use or compare to alternatives like hs_search_contacts or hs_recent_contacts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new HubSpot contact. Email is required; all other fields are optional.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | |||
| firstname | No | ||
| lastname | No | ||
| phone | No | ||
| company | No | ||
| jobtitle | No | ||
| lifecyclestage | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No behavioral details beyond creation. Does not mention idempotency, duplicate handling, permissions, or rate limits. With no annotations, the description should provide more context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very short and to the point, but lacks necessary detail for a creation tool. Not an example of effective conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, no description of return value, error handling, or duplicate policies. The description is insufficient for an agent to fully understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only states Email is required and others optional. Does not explain field meanings, formats, or valid values (e.g., phone, lifecyclestage). Schema coverage is 0%, so description should compensate but fails.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool creates a HubSpot contact and mentions required vs optional fields. However, does not differentiate from sibling tools like hs_update_contact.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as hs_update_contact or hs_search_contacts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Escape hatch: run a structured CRM search with custom filter conditions against any object type. Use when preset tools don't cover your query. Docs: developers.hubspot.com/docs/api/crm/search
| Name | Required | Description | Default |
|---|---|---|---|
| objectType | Yes | CRM object type to search | |
| filters | Yes | Filter conditions to apply | |
| properties | No | Properties to return | |
| sorts | No | ||
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only states 'search', implying read-only, but does not confirm idempotence, permissions, or side effects. No mention of rate limits, pagination, or error behavior. A docs link is given but does not inline key details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences plus a link. Front-loaded with 'Escape hatch' for instant context, no wasted words, and every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a search tool given the presence of many siblings, but lacks behavioral transparency and parameter detail. Does not mention result format, pagination, or read-only nature, which are important for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions 'custom filter conditions' and 'any object type', but does not elaborate on how to use the parameters (e.g., filter structure, operator semantics, property selection, sorting, limit). Schema descriptions cover 60% of parameters, but the description adds no value beyond them, failing to compensate for the remaining 40%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it performs a structured CRM search against any object type, and explicitly distinguishes from preset tools by labeling itself an 'escape hatch'. This makes its purpose specific and differentiated from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Directly advises to use when preset tools don't cover the query, providing clear context for tool selection. Lacks explicit exclusion of other scenarios but the guidance is sufficient for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List deals in a specific pipeline stage, sorted by amount descending.
| Name | Required | Description | Default |
|---|---|---|---|
| pipelineId | Yes | Pipeline ID (from list_pipelines) | |
| stageId | Yes | Stage ID (from list_pipelines) | |
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses sorting by amount descending and filtering by stage, but does not mention pagination, error behavior, or missing data handling. The behavior is adequately, if not fully, transparent for a simple list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the core functionality. No unnecessary words, and every part is informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a relatively simple tool with good schema documentation, the description is mostly complete. It clarifies the sorting and filtering. However, the absence of an output schema means the agent does not know the return structure, though this is common for list tools. Overall, it leaves few gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 67% of parameters with descriptions (pipelineId and stageId), and the limit parameter has min/max/default. The description adds no additional meaning beyond the schema, such as parameter relationships or acceptable values. Baseline 3 is appropriate given the high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists deals in a specific pipeline stage, sorted by amount descending. The verb 'list' and resource 'deals' are specific, and it distinguishes from siblings like hs_search_deals or hs_recent_deals by specifying the filter and ordering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (listing deals by stage) but does not explicitly state when to use this tool over alternatives like hs_search_deals or hs_recent_deals. No exclusions or conditions are mentioned, so the guidance is adequate but minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get recent submissions for a form including all field values and submission timestamps.
| Name | Required | Description | Default |
|---|---|---|---|
| formGuid | Yes | HubSpot form GUID | |
| limit | No | ||
| after | No | Paging cursor from a previous call |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states what the tool returns but does not disclose behavioral traits such as ordering, pagination behavior, permissions needed, or rate limits. The agent has no insight into side effects or access requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 13 words, front-loaded with verb and resource. No unnecessary words, and every part contributes to understanding the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 3 parameters and no output schema, the description is concise but lacks detail on the exact output structure (e.g., array of objects, field names). It mentions 'all field values' but doesn't specify the format. Adequate for basic understanding but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67% (two of three parameters have descriptions). The description adds context by specifying the output includes 'all field values and submission timestamps', implying that the limit parameter controls how many recent submissions. This adds slight value beyond the schema, but does not detail parameters further. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get recent submissions for a form including all field values and submission timestamps.' The verb 'get' and resource 'recent submissions for a form' are specific. This distinguishes it from siblings like 'hs_get_form' which likely returns form structure, not submissions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention scenarios where other tools might be more appropriate, such as when needing form definitions (hs_get_form) or other types of submissions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a single company by ID with all standard properties and associated contact/deal IDs.
| Name | Required | Description | Default |
|---|---|---|---|
| companyId | Yes | HubSpot company ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description adds value by specifying the return content (standard properties and associated contact/deal IDs), which goes beyond the schema. It does not cover rate limits or auth, but it's adequate for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no waste, front-loaded with the action and resource; highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (1 parameter, no output schema), the description fully explains what the tool does and returns, making it sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage for the single parameter with a description 'HubSpot company ID'; the tool description adds no further semantic details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a single company by ID, includes standard properties and associated IDs, distinguishing it from siblings like hs_search_companies (search) and hs_get_contact (different entity).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a company ID but lacks explicit guidance on when to use alternatives (e.g., hs_search_companies) or exclusion scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a single contact by ID with all standard properties and associated company/deal IDs.
| Name | Required | Description | Default |
|---|---|---|---|
| contactId | Yes | HubSpot contact ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. It implies read-only operation ('Retrieve') but does not disclose auth requirements, rate limits, or what happens if contact not found. Adequate for a simple get, but could be more explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, front-loaded sentence with no wasted words. Efficiently conveys purpose and key return content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description reasonably states what is returned (standard properties + company/deal IDs). Lacks details on response format or edge cases, but acceptable for a simple retrieval.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with description 'HubSpot contact ID' for the only parameter. Description adds no additional meaning beyond the schema; baseline score holds.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Retrieve a single contact by ID' with specific verb and resource, and distinguishes from siblings like hs_contact_by_email and hs_search_contacts by focusing on ID-based retrieval and including return details (standard properties, associated IDs).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives. Does not mention prerequisites (e.g., having the contact ID) or contrast with similar siblings like hs_contact_by_email or hs_search_contacts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a single deal by ID with amount, stage, close date, and associated contacts/companies.
| Name | Required | Description | Default |
|---|---|---|---|
| dealId | Yes | HubSpot deal ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description does a good job. It indicates a read operation ('retrieve') and mentions specific fields returned. Although no output schema exists, the listed fields provide adequate transparency for a simple get-by-ID tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the tool's purpose and key return data.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool with one parameter and no output schema, the description is fairly complete. It specifies what is retrieved and key fields. Minor gaps: could mention how the dealId is obtained, but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the only parameter (dealId) at 100%. The description adds no additional meaning beyond the schema's 'HubSpot deal ID'. For a single simple parameter, this is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a single deal by ID and lists key fields (amount, stage, close date, contacts/companies). It distinguishes from siblings like hs_search_deals (search multiple) and hs_deals_by_stage (filtered).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (need a single deal by ID) but does not explicitly state when not to use or suggest alternatives. Siblings are available, so the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get performance statistics (opens, clicks, bounces, unsubscribes) for a specific marketing email.
| Name | Required | Description | Default |
|---|---|---|---|
| emailId | Yes | HubSpot marketing email ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It does not mention read-only behavior, authentication needs, rate limits, or return format. For a tool that retrieves data, more behavioral context is expected beyond listing metric names.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence that efficiently conveys the tool's purpose and the metrics involved. No wasted words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description adequately covers what it does and what metrics are returned. It lacks details on return format but is sufficient for a single-purpose tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (the single parameter emailId is described as 'HubSpot marketing email ID'). The description reiterates 'specific marketing email' but adds no new semantic meaning beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'performance statistics for a specific marketing email', listing the specific metrics (opens, clicks, bounces, unsubscribes). It distinguishes from siblings like hs_list_marketing_emails which lists emails rather than providing stats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when stats for a specific email are needed. No explicit when-not or alternative is given, but the context is clear enough given the single purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full form definition including fields, required properties, and redirect settings.
| Name | Required | Description | Default |
|---|---|---|---|
| formGuid | Yes | HubSpot form GUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that the tool returns full form definition including fields, required properties, and redirect settings, indicating a read operation with no destructive side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that is concise and front-loaded, efficiently conveying the tool's purpose without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get operation with one parameter and no output schema, the description fully explains what the tool returns. It is complete and sufficient for an agent to understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter 'formGuid' described as 'HubSpot form GUID'. The description does not add additional meaning beyond the schema, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get full form definition including fields, required properties, and redirect settings.' This is a specific verb and resource, and it distinguishes from sibling 'hs_list_forms' which likely only lists forms without full details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'hs_list_forms'. The description does not specify prerequisites or context in which this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get metadata for a specific contact list including membership count and list type.
| Name | Required | Description | Default |
|---|---|---|---|
| listId | Yes | HubSpot contact list ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the tool returns membership count and list type, but does not mention behavior on invalid listId, rate limits, or whether it's read-only (likely). The description is sparse but not contradictory.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with verb and resource, no superfluous words. Exceptionally concise for the information conveyed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one parameter and no output schema, the description covers the primary return fields (membership count, list type). It could mention the response format but the lack of output schema limits expectations. Slight gap but mostly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with a description 'HubSpot contact list ID'. The description adds 'specific contact list' which aligns but adds no new semantic detail. Baseline 3 is appropriate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'get', the resource 'metadata for a specific contact list', and the included fields 'membership count and list type'. This distinguishes it from sibling tools like hs_list_lists (which likely lists all lists) and hs_list_members (which gets members).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by describing what the tool does, but it does not explicitly state when to use it versus alternatives like hs_list_lists. No when-to-use or when-not-to-use guidance is provided, though the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full definition of a single CRM property including options/enum values and validation rules.
| Name | Required | Description | Default |
|---|---|---|---|
| objectType | Yes | ||
| propertyName | Yes | Internal property name, e.g. 'lifecyclestage' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool returns a 'full definition' with options and validation rules, indicating a read operation. However, with no annotations, it lacks details on authentication, performance, or absence of side effects. The transparency is adequate but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no extraneous words. It is front-loaded with the key action. Slight improvement could be made by breaking into bullet points, but it is already concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two parameters and no output schema or annotations, the description adequately explains what the tool returns (full definition including options and validation rules). It is complete enough for an agent to understand the basic behavior, though it could mention the absence of side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%; only propertyName has a description. The tool description does not explain parameters, leaving objectType's purpose implicit (though the enum hints at CRM objects). The description fails to compensate for the schema's gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'full definition of a single CRM property', and specifies included details like options and validation rules. It differentiates from sibling tools like hs_list_properties by emphasizing singularity and depth.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., hs_list_properties), nor does it mention prerequisites or when not to use it. The agent must infer usage from the tool name and context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full details of a workflow including enrollment triggers, actions, and settings.
| Name | Required | Description | Default |
|---|---|---|---|
| workflowId | Yes | HubSpot workflow (automation) ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description does not disclose read-only nature, authentication requirements, rate limits, or any side effects. The burden is on the description, and it fails to meet it adequately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, concise and front-loaded with key details. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-id tool with one parameter and no output schema, the description suffices by listing what details are returned. However, could mention expected response structure or error cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the only parameter 'workflowId' is well-described in the schema. The tool description does not add extra semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action (Get), resource (workflow), and specific details returned (enrollment triggers, actions, settings). This distinguishes it from sibling tool hs_list_workflows, which likely returns summaries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this versus alternatives like hs_list_workflows. Lacks context for prerequisites or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all contacts associated with a company.
| Name | Required | Description | Default |
|---|---|---|---|
| companyId | Yes | HubSpot company ID | |
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden but only states a basic read operation. It fails to disclose ordering, pagination behavior, side effects, or any constraints. As a minimal description, it adds little beyond the name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (one sentence) but lacks structure. It is front-loaded with purpose but misses the opportunity to present additional context efficiently. Could be improved with bullet points or a more informative single sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema means the return format is completely unspecified. The description does not hint at what fields are returned, error conditions, or pagination handling. For a simple tool, this is a significant gap given no other documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (companyId described, limit not). The description does not mention the limit parameter or its default/range, leaving the agent to infer from the schema alone. No additional semantic value is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action (list) and resource (contacts) within a context (associated with a company), which distinguishes it from sibling tools like hs_search_contacts or hs_get_contact.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as hs_search_contacts or hs_recent_contacts. The description lacks context about prerequisites, exclusions, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List marketing email campaigns ordered by most recently updated.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. Does not state read-only nature, pagination behavior, or rate limits. Only notes ordering by recent update.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with verb and resource. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no parameter details, description omits what data is returned per campaign. For a list tool with pagination, more detail on response structure is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage for two parameters (limit, offset). Description adds no parameter information, leaving agent to infer meaning from names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it lists marketing email campaigns with ordering by most recently updated. Differentiates from sibling hs_list_marketing_emails through ordering specificity, but could clarify distinction further.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like hs_list_marketing_emails or hs_get_email_campaign_stats. Missing context on preferred scenarios or filtering.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all HubSpot forms ordered by most recently updated.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It only states the ordering behavior but does not disclose whether the operation is read-only, authentication needs, rate limits, or pagination details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise, but it lacks structure and additional context. While not verbose, it could be improved by front-loading key details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool with one parameter and no output schema, the description is too minimal. It does not explain the return format or how the 'limit' parameter affects results, leaving gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning no parameter descriptions are provided in the schema. The description adds no information about the 'limit' parameter, leaving the agent without guidance on its usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'list', the resource 'HubSpot forms', and adds a specific ordering detail 'ordered by most recently updated'. This distinguishes it from sibling list tools like hs_list_lists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, exclusions, or context for when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all HubSpot contact lists (static and active). Optionally filter by name substring.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | No | Filter by list name substring |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions listing all lists but does not disclose behavioral traits such as read-only nature, rate limits, authentication requirements, or what happens with no results. For a listing tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no redundancy. The core purpose is front-loaded, and every word adds value. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the basic operation but lacks details on return format, pagination behavior, and limit semantics. Since there is no output schema, the description should compensate but fails to describe the response structure, making it incomplete for an agent to fully understand the output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (query has description, limit does not). The description adds a phrase 'Optionally filter by name substring' which reinforces the query parameter but adds no new meaning beyond the schema. The limit parameter is not described, leaving the agent unclear about its effect.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists all HubSpot contact lists (static and active) with optional name filtering. The verb 'list' and resource 'HubSpot contact lists' are specific. However, it does not explicitly differentiate from sibling tools like 'hs_get_list' (single list) or 'hs_crm_search', though the tool name suggests plural.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you want to retrieve all contact lists, but no explicit guidance on when not to use this tool or alternatives. Siblings like 'hs_get_list' exist for single list retrieval, but no reference is made.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List marketing emails, optionally filtered by publication state (DRAFT, SCHEDULED, PUBLISHED, ARCHIVED).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| state | No | Filter by publication state |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the full burden. It does not disclose any side effects, permissions, or behavioral traits beyond the basic listing operation. The description lacks information on ordering, pagination, or whether the list is exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action and resource. It contains no unnecessary words and is easy to parse. Perfect conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with two optional parameters and no output schema, the description is adequate but lacks details like default limit behavior, ordering, and what constitutes a marketing email. It does not reference any output format or pagination, which would be helpful for agents.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to the 'state' parameter by listing the enum values explicitly, which the schema already includes but with only a brief description. The 'limit' parameter is not explained beyond its schema constraints (integer, range, default). With 50% schema coverage, the description partially compensates for the state parameter but not for limit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List marketing emails' with optional filtering by state, which distinguishes it from general list tools. However, it does not explicitly differentiate from sibling tools like hs_list_email_campaigns, so a score of 4 is appropriate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, context, or comparisons with sibling tools like hs_list_email_campaigns or hs_get_email_campaign_stats.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get contacts that are members of a specific list.
| Name | Required | Description | Default |
|---|---|---|---|
| listId | Yes | HubSpot contact list ID | |
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must convey behavioral traits. It implies a read-only operation but lacks details on pagination, error states, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no fluff, but under-specified. Conciseness is good but sacrifices completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, no explanation of return values, pagination, or error handling. Incomplete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description adds no meaning beyond the input schema. The limit parameter is undocumented in the schema and description. Only listId is briefly explained in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get contacts that are members of a specific list,' specifying the action and resource. It differentiates from sibling tools like hs_get_list or hs_list_company_contacts, though it could be more explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like hs_get_list or hs_search_contacts. No prerequisites, error handling, or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List HubSpot users (owners) that can be assigned to CRM records. Filter by email to look up a specific rep.
| Name | Required | Description | Default |
|---|---|---|---|
| No | Filter by owner email address | ||
| includeInactive | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries behavioral transparency. It indicates listing and filtering but does not disclose effects of includeInactive parameter, auth needs, or rate limits. Partial but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with core purpose. No fluff, efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given two parameters and no output schema, the description covers the purpose and one use case but omits explanation of includeInactive, return format, or pagination. Adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% with email parameter having a schema description and includeInactive lacking one. The description adds no value beyond the schema for email and completely ignores includeInactive. Thus it does not compensate for the missing schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists HubSpot users (owners) assignable to CRM records and mentions filtering by email. It distinguishes itself from sibling list tools like hs_list_forms.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for looking up a specific rep via email, but lacks explicit when-not-to-use or alternatives. No comparison with other tools, though no direct sibling duplicates its function.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all CRM pipelines (deals or tickets) with their stage IDs. Use stage IDs with hs_deals_by_stage.
| Name | Required | Description | Default |
|---|---|---|---|
| objectType | No | CRM object type to list pipelines for | deals |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It states the tool lists all pipelines with stage IDs but omits details like pagination, rate limits, or authentication requirements. For a simple listing tool, this is adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two efficient sentences, front-loaded with purpose. No extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description partially explains return values (stage IDs) but lacks full structure. For a simple listing tool with one optional parameter, it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (parameter described with enum and default). The description only slightly paraphrases the schema ('deals or tickets') without adding new semantic information, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'all CRM pipelines' with the specific output 'stage IDs'. It distinguishes from sibling tools like hs_pipeline_summary by indicating the output is useful for hs_deals_by_stage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells the agent to use stage IDs with hs_deals_by_stage, providing a downstream usage context. However, it does not explicitly mention when not to use this tool or compare to alternatives like hs_pipeline_summary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all properties defined for a CRM object type. Use customOnly=true to see only custom fields.
| Name | Required | Description | Default |
|---|---|---|---|
| objectType | Yes | CRM object type | |
| customOnly | No | Return only custom properties |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must cover behavioral traits. It only implies a read operation without disclosing details like pagination, rate limits, or authentication needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, no fluff, front-loaded with purpose and a usage hint.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple list tool with well-documented parameters, but no output schema means return structure is left to the agent's assumptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters, and description adds no new info beyond restating the schema's 'customOnly' description. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states action ('List') and resource ('properties for a CRM object type'), distinguishing it from sibling 'hs_get_property' which retrieves a single property.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides helpful guidance for 'customOnly' parameter but does not mention when to use this tool versus alternative listing tools or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all HubSpot automation workflows with name, type, and enabled status.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description does not disclose behavioral traits such as pagination, rate limits, whether it shows all workflows or only active ones, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, no fluff. Front-loaded with key information. However, lacks structure for complex details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, so description partially fills gaps by listing returned fields. But missing pagination info and clarity on scope (all workflows?). Adequate for a simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% with no description for the 'limit' parameter. The description does not explain the parameter's purpose or behavior beyond listing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'List', resource 'HubSpot automation workflows', and specific returned fields (name, type, enabled status). Differentiates from sibling tools that list other resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like hs_get_workflow for a single workflow or other list tools. Does not mention any prerequisites or contextual usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deal counts and total amounts aggregated by pipeline stage — a quick funnel snapshot for a given pipeline.
| Name | Required | Description | Default |
|---|---|---|---|
| pipelineId | Yes | Pipeline ID (from list_pipelines) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Lacks detail on e.g., whether all stages are returned, read-only nature, or any limits. 'Aggregated by pipeline stage' is present but not expanded.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded, no redundant words. Efficient and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple 1-param tool with no output schema, but could benefit from describing the output shape (e.g., per-stage breakdown, totals).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with pipelineId having a clear description. The tool description adds 'for a given pipeline' which is consistent but not new information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'deal counts and total amounts aggregated by pipeline stage', a specific verb+resource combination. Distinguishes from siblings like hs_deals_by_stage by focusing on aggregated metrics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use vs alternatives. Implies a 'quick funnel snapshot' but doesn't contrast with hs_deals_by_stage or other similar tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most recently created contacts, optionally filtered by lifecycle stage (lead, marketingqualifiedlead, opportunity, customer, etc.).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| lifecycleStage | No | Filter by lifecycle stage, e.g. 'lead', 'marketingqualifiedlead', 'opportunity', 'customer' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description lacks details on pagination, ordering, scope (e.g., 'visible to user'), or what 'recent' means. Insufficient for a list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, single sentence, front-loaded with core purpose. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema; description does not specify returned fields or structure. Incomplete for a list endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Description mentions lifecycleStage, which is also described in schema. No mention of limit parameter. Schema coverage is 50%, description adds minimal value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it returns recently created contacts with optional lifecycle stage filtering. Distinct from siblings like hs_get_contact (single contact by ID) and hs_search_contacts (search).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage for listing recent contacts, but no explicit guidance on when to use vs alternatives like hs_contact_by_email or hs_get_contact.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most recently created deals. Pass openOnly=true to exclude closed deals.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| openOnly | No | Exclude closed deals |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions filtering by openOnly but does not disclose order, pagination, time window for 'recent', rate limits, or whether it is read-only. The behavioral transparency is insufficient for a tool with no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two short sentences. The first sentence immediately conveys the core purpose, and the second sentence provides a key usage hint. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description should explain return values or structure. It does not. Also lacks details on ordering, default limit behavior, or the definition of 'recent'. The description is incomplete for practical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only openOnly has a description); the description paraphrases that parameter but adds no new meaning. The limit parameter is not described in either the schema or the description. The description fails to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description immediately states the tool retrieves 'Most recently created deals', which is a specific verb+resource. It distinguishes itself from sibling tools like hs_search_deals and hs_deals_by_stage by focusing on recency.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as hs_search_deals or hs_deals_by_stage. Does not explain prerequisites or scenarios where it is inappropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full-text search across companies by name, domain, or industry.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Full-text search (company name, domain, etc.) | |
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states it performs full-text search on certain fields but does not disclose behavioral traits such as pagination, ordering, rate limits, or whether results are partial. For a search tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the core action and scope. No extraneous information, every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with two parameters, the description covers what is searched. However, it lacks output schema and does not mention return format or ordering. Given the low complexity, it is mostly complete but could include a note on result structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage (both 'query' and 'limit' are described). The description adds no additional semantic meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'search' and resource 'companies', specifying fields like name, domain, or industry. It naturally distinguishes from sibling tools such as hs_search_contacts and hs_search_deals.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for company search but provides no explicit guidance on when to use this tool versus alternative search tools (e.g., hs_crm_search, hs_get_company). No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full-text search across contacts by name, email, company, or any indexed field.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Full-text search string (name, email, company, etc.) | |
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It reveals the search behavior but omits details like read-only nature, return format, pagination, or limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with key info, no unnecessary words. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and simple parameters, description covers the search intent. But missing details on return structure and pagination for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 'query' with a description; 'limit' lacks description (50% coverage). Description adds value by listing searchable fields, compensating for schema gaps partially.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it performs full-text search across contacts, specifying searchable fields (name, email, company). This distinguishes it from siblings like hs_get_contact (exact) or hs_search_companies.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives like hs_crm_search or hs_contact_by_email. The description implies usage for full-text search but lacks exclusions or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full-text search across deals by name.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Full-text search (deal name, etc.) | |
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description lacks behavioral details such as read-only nature, pagination, case sensitivity, or matching behavior. As a search tool, it should disclose these traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that directly states the purpose. It is front-loaded and wastes no words, though it could be slightly more informative without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (2 parameters, no output schema), the description is insufficient. It does not explain return format, pagination defaults, or any constraints beyond the schema. The agent lacks key context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds minimal value beyond the schema: it specifies 'by name', but the schema already indicates 'deal name, etc.' The limit parameter has no description in schema or description. Schema coverage is 50%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it performs full-text search across deals by name. This distinguishes it from sibling search tools like hs_search_companies and hs_search_contacts, though it could specify if additional fields are searched.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like hs_crm_search or hs_deals_by_stage. The description does not include any context about when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update one or more properties on an existing contact.
| Name | Required | Description | Default |
|---|---|---|---|
| contactId | Yes | HubSpot contact ID | |
| properties | Yes | Properties to update, e.g. { jobtitle: 'VP Marketing' } |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description must disclose behavior. It states 'Update' but does not explain what happens if contactId is invalid, whether partial updates are supported, or what the tool returns. Missing critical behavioral details for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no redundancy, front-loaded with core action. Every word contributes to purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks return value information (no output schema) and guidance on valid property names. With nested object parameters, more detail would improve completeness. Sibling hs_list_properties suggests property validation exists but is not mentioned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters with descriptions. The description adds no extra meaning beyond the schema. Baseline 3 for 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update one or more properties on an existing contact', specifying the verb (Update), resource (contact), and scope (one or more properties). It distinguishes from siblings like hs_create_contact and hs_get_contact.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives. It does not mention that it should be used for existing contacts only, nor does it point to hs_create_contact for new contacts. Implicit but insufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.0.0hs_contact_by_emailhs_create_contacths_crm_searchhs_deals_by_stagehs_form_submissionshs_get_companyhs_get_contacths_get_dealhs_get_email_campaign_statshs_get_formhs_get_lisths_get_propertyhs_get_workflowhs_list_company_contactshs_list_email_campaignshs_list_formshs_list_listshs_list_marketing_emailshs_list_membershs_list_ownershs_list_pipelineshs_list_propertieshs_list_workflowshs_pipeline_summaryhs_recent_contactshs_recent_dealshs_search_companieshs_search_contactshs_search_dealshs_update_contactEach tool targets a distinct HubSpot object or action (e.g., contact, company, deal, form, list, workflow). There is no overlap between tools like hs_search_companies, hs_search_contacts, and hs_search_deals, and the escape hatch hs_crm_search is clearly differentiated as a custom query tool. All tools have unique purposes.
The majority of tools follow a consistent verb_noun pattern with snake_case and the 'hs_' prefix (e.g., hs_create_contact, hs_get_company, hs_search_deals). However, a few tools deviate slightly (hs_contact_by_email, hs_crm_search, hs_form_submissions, hs_pipeline_summary), breaking the strict pattern. Overall, the naming is mostly predictable.
30 tools cover a wide range of HubSpot objects and operations, which is appropriate for a comprehensive CRM integration. While slightly on the higher side, each tool serves a distinct purpose and the count is reasonable given the complexity of HubSpot's API surface.
The toolset is heavily read-oriented, with only one create (hs_create_contact) and one update (hs_update_contact) operation. Missing create, update, and delete for companies, deals, forms, lists, workflows, marketing emails, properties, and pipelines. This is a significant gap that will prevent agents from performing essential CRM write operations.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
The HubSpot MCP Server acts as a bridge that enables AI assistants and Large Language Models to securely interact with HubSpot CRM data through natural conversation, without requiring users to understand complex API structures. It provides read-only access to standard CRM objects (contacts, companies, deals, tickets, products, invoices, and more) and their associations, secured via OAuth 2.0, allowing AI agents to perform tasks like summarizing deals, fetching company updates, and looking up record changes.
MCP server for the HubSpot Integrations Center HubDB: search and retrieve integration data.
API-first CRM for LLMs - contacts, companies, deals and activities over a native MCP server.
Marketo MCP server for AI. 130 tools to operate Marketo from Claude, Cursor, or ChatGPT.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/ZLeventer/hubspot-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
