Search HubSpot contacts by free-text term and return one page of matches.

Use this to find contacts by name, email, company, or any other indexed property. Prefer crm_list_contacts when there is no term to match on, and crm_get_contact when the record id is already known.

Read-only. Needs the crm.objects.contacts.read scope; without it the call is denied before any CRM data request is made and the denial is written to the audit log. Search results are never cached, so every call reaches HubSpot. Pass the returned 'after' cursor back to walk further pages; a null 'after' means this was the last page. Archived contacts are excluded.

List HubSpot contacts in record-id order, one page at a time.

Use this to walk the whole contact set. Prefer crm_search_contacts when there is a term to match on, since listing everything is slower and burns rate limit.

Read-only. Needs the crm.objects.contacts.read scope; a missing scope is denied locally and recorded in the audit log. Not cached. Pass the returned 'after' cursor back for the next page and stop when it comes back null. Archived contacts are excluded.

Fetch one HubSpot contact by record id with its email, name, phone, and company.

Use this once an id is known. Use crm_search_contacts to find the id first.

Read-only. Needs the crm.objects.contacts.read scope. Served from an in-process cache with a 300 second default TTL; writes made through this server invalidate the entry immediately, and a cache hit is recorded in the audit log as a cache hit rather than a live read. Raises a not-found error for an unknown or archived id.

Create one HubSpot contact from the properties given and return the new record.

Use this for single creates, especially ones a retry might repeat. Use crm_batch_create_contacts to load many rows at once, and crm_update_contact to change a record that already exists.

Writes, additively. Needs the crm.objects.contacts.write scope. The call is keyed by 'idempotency_key', or by a hash of the properties when none is given, and a repeat of the same key replays the stored record instead of creating a second one. That key store lives in this process, so it covers retries within a session and not restarts. Cached contact reads are invalidated. At least one property must be supplied or the call fails validation.

Update properties on an existing HubSpot contact and return the updated record.

Use this to change a known record. Use crm_create_contact for records that do not exist yet.

Writes. Only the properties passed are sent, and each one overwrites the value HubSpot held before, so the previous value is lost; properties left out are untouched. Applying the same values again produces the same record, which makes a retry safe. Needs the crm.objects.contacts.write scope. Invalidates this contact's cache entry. Raises a not-found error for an unknown or archived id, and a validation error when no property is supplied.

Archive (soft-delete) a HubSpot contact so it drops out of active views.

Use this instead of asking a human to delete in the UI. This server never issues a hard delete; HubSpot keeps archived records restorable from its own UI for a limited window.

Writes, and destructive from an agent's point of view. Needs the crm.objects.contacts.write scope. Archiving the same id again leaves it archived. The record is dropped from the read cache and stops appearing in list and search results. Raises a not-found error for an id that never existed.

Create many HubSpot contacts in one request and report the outcome of every row.

Use this for bulk loads. Use crm_create_contact instead when a retry must not risk duplicates.

Writes, additively. Needs the crm.objects.contacts.write scope. Returns 'succeeded' with the created records and 'failed' with the input index, HubSpot status code, category, message, and original row for every rejection, so a partial failure never hides the rows that did save. This path does not go through the idempotency store: running the same batch twice can create duplicates, so re-send only the rows listed in 'failed'. Cached contact reads are invalidated.

Search HubSpot deals by free-text term and return one page of matches.

Use this to find deals by name, amount, or stage text. Use crm_get_deal when the record id is already known, and crm_list_pipelines to translate the returned pipeline and stage ids into readable labels.

Read-only. Needs the crm.objects.deals.read scope; a missing scope is denied locally and recorded in the audit log. Not cached. Pass the returned 'after' cursor back for the next page and stop when it is null. Archived deals are excluded.

Fetch one HubSpot deal by record id with its name, amount, pipeline, and stage.

Use this once an id is known; use crm_search_deals to find the id first.

Read-only. Needs the crm.objects.deals.read scope. Served from an in-process cache with a 300 second default TTL, and writes made through this server invalidate the entry immediately. Raises a not-found error for an unknown or archived id.

Create one HubSpot deal from the properties given and return the new record.

Call crm_list_pipelines first when setting 'pipeline' or 'dealstage', because HubSpot only accepts a stage id that belongs to the chosen pipeline. Use crm_update_deal to move an existing deal.

Writes, additively. Needs the crm.objects.deals.write scope. The call is keyed by 'idempotency_key', or by a hash of the properties when none is given, and a repeat of the same key replays the stored record instead of creating a second one. That key store lives in this process, so it covers retries within a session and not restarts. Cached deal reads are invalidated. At least one property must be supplied.

Update properties on an existing HubSpot deal, including moving it to a new stage.

Use this to advance a deal through its pipeline. The deal's pipeline itself is not changeable here; create the deal in the right pipeline instead.

Writes. Only the properties passed are sent, and each one overwrites the value HubSpot held before; properties left out are untouched. Applying the same values again produces the same record, which makes a retry safe. Needs the crm.objects.deals.write scope. Invalidates this deal's cache entry. Raises a not-found error for an unknown or archived id, and a validation error when no property is supplied.

Archive (soft-delete) a HubSpot deal so it drops off the pipeline board.

Prefer moving a lost deal to a closed-lost stage with crm_update_deal, which keeps it in reporting. Archive only when the record should not have existed.

Writes, and destructive from an agent's point of view. Needs the crm.objects.deals.write scope. Archiving the same id again leaves it archived. The record is dropped from the read cache and stops appearing in searches. Raises a not-found error for an id that never existed.

List every deal pipeline in the account with its stages in display order.

Call this before creating or moving a deal: it is the source of the 'pipeline' and 'dealstage' ids those tools need, and HubSpot rejects a stage id from the wrong pipeline.

Read-only. Needs the crm.schemas.deals.read scope. Served from an in-process cache with a 300 second default TTL, since pipeline definitions rarely change. Returns an empty list only if the account genuinely has no deal pipelines.

Fetch one deal pipeline by id with its stages sorted by display order.

Use this when the pipeline id is already known and only its stages are needed. Use crm_list_pipelines to discover ids.

Read-only. Needs the crm.schemas.deals.read scope. Unlike the pipeline list, this call is not cached and always reaches HubSpot. Raises a not-found error for an unknown id.

Export this session's audit trail as JSON Lines, one record per line.

Use this to hand a reviewer evidence of what the agent did, or to attach the trail to a ticket or change record.

Read-only and entirely local: it reads an in-memory buffer, makes no HubSpot call, and needs no scope. Every other tool call in the session is present, including calls denied for a missing scope and calls that raised an error, each with an id, timestamp, actor, tool name, outcome, the arguments, a short result summary, and the idempotency key where one applied. Email addresses and phone numbers are redacted before a record is stored. The buffer is not persisted, so it starts empty every time the server starts and an export after a restart covers only the new session.