HubSpot

Routing

1. CRM and commerce objects: use the consolidated CRM read tool with object_type; pass record_id for one row or omit it to list. Use the consolidated CRM upsert tool for create/update when that object type is writable by the connected token.
2. Metadata surfaces: use specialized tools for owners, properties, account details, token metadata, and lists when the task explicitly asks for them.
3. Delete/archive: use the delete tool with hubspot:{objectType}:{numericId} only after reading the record first.

Data model

• Contacts are people; companies are accounts; deals are opportunities.
• Engagement objects include emails, calls, meetings, notes, and tasks.
• Commerce objects include products, line items, carts, quotes, invoices, orders, and commerce subscriptions. Some commerce objects are read-only for a given connection even when related objects are writable.
• Lists, properties, owners, and account metadata are separate surfaces with separate scopes.
• Associations are directional; read existing records and association metadata before linking objects.

Scopes

• Tool visibility follows the connected token's granted scopes. If a tool is missing, the connected HubSpot account did not grant the scope required for that tool.
• Broad app installs request every optional scope HubSpot will currently deploy for the granular project app. CMS, marketing, files, imports/exports, schemas, user objects, tickets, and automation remain unavailable until HubSpot exposes deployable scopes for those surfaces.
• A 403 that names a missing scope is not a retry problem. Reconnect with a permission set that includes that scope, or use a tool whose required scopes are already granted.
• Owners, users, workflows, and some admin endpoints can reject user-level tokens even when the scope exists. Prefer ordinary CRM read/upsert tools for record work.

Properties

• Use HubSpot internal property names such as firstname, dealname, hs_object_id, and hubspot_owner_id, not UI labels.
• Read property definitions or a sample row before filters and writes. For new deals, use pipeline metadata for pipeline and dealstage.

Record IDs

• Single CRM reads use object_type plus the numeric record_id.
• Cross-tool references and delete/archive use hubspot:{objectType}:{id}.