hubspot-update-engagement
Modify existing HubSpot engagements (Notes or Tasks) by updating attributes, content, or metadata. Requires engagement ID and allows selective field updates while preserving unchanged data. Use for CRM maintenance.
Instructions
🛡️ Guardrails:
1. Data Modification Warning: This tool modifies HubSpot data. Only use when the user has explicitly requested to update their CRM.
🎯 Purpose:
1. Updates an existing HubSpot engagement (Note or Task).
2. Allows modification of engagement attributes, content, and metadata.
📋 Prerequisites:
1. You need the engagement ID to update an existing engagement.
2. Use the hubspot-get-engagement tool to get the current engagement details if needed.
3. Use the hubspot-get-user-details tool to get the owner ID.
🧭 Usage Guidance:
1. Use for updating NOTE content or TASK details (subject, description, status).
2. Only include the fields you want to update - other fields will remain unchanged.
3. HubSpot notes and task descriptions support HTML formatting. However headings (<h1>, <h2>, etc.) look ugly in the CRM. So use them sparingly.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| associations | Yes | Associated records for this engagement | |
| engagementId | Yes | The ID of the engagement to update | |
| metadata | Yes | Metadata specific to the engagement type (Note or Task) | |
| ownerId | No | The ID of the owner of this engagement | |
| timestamp | No | Timestamp for the engagement (milliseconds since epoch). |
Input Schema (JSON Schema)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"associations": {
"additionalProperties": false,
"description": "Associated records for this engagement",
"properties": {
"companyIds": {
"default": [],
"items": {
"type": "integer"
},
"type": "array"
},
"contactIds": {
"default": [],
"items": {
"type": "integer"
},
"type": "array"
},
"dealIds": {
"default": [],
"items": {
"type": "integer"
},
"type": "array"
},
"ownerIds": {
"default": [],
"items": {
"type": "integer"
},
"type": "array"
},
"ticketIds": {
"default": [],
"items": {
"type": "integer"
},
"type": "array"
}
},
"type": "object"
},
"engagementId": {
"description": "The ID of the engagement to update",
"exclusiveMinimum": 0,
"type": "integer"
},
"metadata": {
"additionalProperties": true,
"description": "Metadata specific to the engagement type (Note or Task)",
"properties": {},
"type": "object"
},
"ownerId": {
"description": "The ID of the owner of this engagement",
"exclusiveMinimum": 0,
"type": "integer"
},
"timestamp": {
"description": "Timestamp for the engagement (milliseconds since epoch).",
"type": "integer"
}
},
"required": [
"engagementId",
"metadata",
"associations"
],
"type": "object"
}
Implementation Reference
- The async process method in UpdateEngagementTool class that executes the core logic of the 'hubspot-update-engagement' tool by constructing a PATCH request to the HubSpot engagements API and handling the response or error.async process(args) { try { const { engagementId, ownerId, timestamp, metadata, associations } = args; // Build request body with only provided fields const requestBody = { ...(ownerId || timestamp !== undefined ? { engagement: { ...(ownerId && { ownerId }), ...(timestamp !== undefined && { timestamp }), }, } : {}), ...(Object.keys(metadata).length > 0 && { metadata }), ...(Object.keys(associations).length > 0 && { associations }), }; const response = await this.client.patch(`/engagements/v1/engagements/${engagementId}`, { body: requestBody, }); return { content: [ { type: 'text', text: JSON.stringify({ status: 'success', engagement: response, message: `Successfully updated engagement ${engagementId}`, }, null, 2), }, ], }; } catch (error) { return { content: [ { type: 'text', text: `Error updating HubSpot engagement: ${error instanceof Error ? error.message : String(error)}`, }, ], isError: true, }; } }
- Zod schema defining the input validation for the tool, including engagementId, ownerId, timestamp, metadata, and associations.const UpdateEngagementSchema = z.object({ engagementId: z.number().int().positive().describe('The ID of the engagement to update'), ownerId: z .number() .int() .positive() .optional() .describe('The ID of the owner of this engagement'), timestamp: z .number() .int() .optional() .describe('Timestamp for the engagement (milliseconds since epoch).'), metadata: z .object({}) .passthrough() .describe('Metadata specific to the engagement type (Note or Task)'), associations: AssociationsSchema.describe('Associated records for this engagement'), });
- dist/tools/engagements/updateEngagementTool.js:25-53 (registration)ToolDefinition object that defines the tool's name 'hubspot-update-engagement', description, input schema conversion, and annotations. Passed to BaseTool constructor.const ToolDefinition = { name: 'hubspot-update-engagement', description: ` 🛡️ Guardrails: 1. Data Modification Warning: This tool modifies HubSpot data. Only use when the user has explicitly requested to update their CRM. 🎯 Purpose: 1. Updates an existing HubSpot engagement (Note or Task). 2. Allows modification of engagement attributes, content, and metadata. 📋 Prerequisites: 1. You need the engagement ID to update an existing engagement. 2. Use the hubspot-get-engagement tool to get the current engagement details if needed. 3. Use the hubspot-get-user-details tool to get the owner ID. 🧭 Usage Guidance: 1. Use for updating NOTE content or TASK details (subject, description, status). 2. Only include the fields you want to update - other fields will remain unchanged. 3. HubSpot notes and task descriptions support HTML formatting. However headings (<h1>, <h2>, etc.) look ugly in the CRM. So use them sparingly. `, inputSchema: zodToJsonSchema(UpdateEngagementSchema), annotations: { title: 'Update Engagement', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true, }, };
- dist/tools/toolsRegistry.js:42-42 (registration)The call to registerTool that instantiates and registers the UpdateEngagementTool in the tools registry.registerTool(new UpdateEngagementTool());