Search accounts/contacts; resolve exact IDs before adding or changing notes/tags. General company and prospect imports: preview the entire intended scope, review errors and cost, then invoke the matching start operation with its exact import_token and a stable operation_id. Poll workspace jobs; partial coverage is not completion.
Archive or restore accounts
accounts.archive.v2
Use when: Park accounts the workspace is no longer working, so they stop appearing in lists, scoring, enrichment and outreach without being deleted. Pass restore true to bring archived accounts back.
Avoid when: Do not use this to remove a duplicate — merge it with accounts.merge.execute.v2. Do not use it to stop one campaign; pause the campaign instead.
Effects: Archives the accounts and their contacts, PAUSES any in-flight HiveLoops, cancels their pending drafts, and cancels their Parallel signal monitors. Restoring revives the accounts and contacts, but paused loops stay paused and signal monitoring must be re-enabled by hand.
Cost: No gateway rate is configured. Check the Core workflow preview/quote for downstream charges and final settlement. Gateway rate code: none; downstream billing may apply.
Access: actions:execute. Approval: exact_scope_single_action. A stable operation UUID is required.
Keep the same operation and operation_id when retrying identical work. Reconcile an uncertain result before new work; never replay an old V1 write under a new V2 ID.
Check status, execution_state, error_code, output and evidence/resource references. Queued work is not complete: poll jobs.status.get.v2 in domain.workspace.v2. For read-back verification require read_back_verified=true where returned; reconcile failures without creating another object.
Invocation example using fictional fixtures
{
"tool": "domain.accounts.v2",
"arguments": {
"params": {
"action": "invoke",
"operation": "accounts.archive.v2",
"arguments": {
"account_ids": [
"00000000-0000-4000-8000-000000000001"
]
},
"operation_id": "00000000-0000-4000-8000-000000000003"
}
},
"notice": "Fictional fixture IDs and example text. Resolve real IDs, use returned preview tokens and approve exact side effects before execution. Input validation is not proof of provider readiness or a successful business outcome."
}
Input schema: fields, defaults and constraints
{
"additionalProperties": false,
"properties": {
"action_proposal_id": {
"anyOf": [
{
"format": "uuid",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional. Hivekind fills this from the MCP consent grant.",
"title": "Action Proposal Id"
},
"account_ids": {
"description": "Accounts to archive, or to restore when restore=true.",
"items": {
"format": "uuid",
"type": "string"
},
"maxItems": 500,
"minItems": 1,
"title": "Account Ids",
"type": "array"
},
"restore": {
"default": false,
"description": "False archives the accounts; true restores previously archived ones. Restoring does NOT resume paused HiveLoops or re-enable signal monitoring — see not_restored on the result.",
"title": "Restore",
"type": "boolean"
}
},
"required": [
"account_ids"
],
"title": "McpMcpPublicAccountsArchiveInputV2",
"type": "object"
}
Output schema inside the result envelope
{
"additionalProperties": false,
"description": "V2 result for accounts.archive.v2; preserves the established validators.",
"properties": {
"restored": {
"default": false,
"description": "True when this call restored rather than archived.",
"title": "Restored",
"type": "boolean"
},
"account_ids": {
"default": [],
"description": "Accounts whose status actually changed.",
"items": {
"type": "string"
},
"maxItems": 500,
"title": "Account Ids",
"type": "array"
},
"skipped": {
"default": [],
"description": "Ids asked about but not changed: outside the workspace, or already in the requested state.",
"items": {
"type": "string"
},
"maxItems": 500,
"title": "Skipped",
"type": "array"
},
"contacts_changed": {
"default": 0,
"description": "Contacts archived alongside their account, or restored with it.",
"minimum": 0,
"title": "Contacts Changed",
"type": "integer"
},
"activations_paused": {
"default": 0,
"minimum": 0,
"title": "Activations Paused",
"type": "integer"
},
"drafts_cancelled": {
"default": 0,
"minimum": 0,
"title": "Drafts Cancelled",
"type": "integer"
},
"monitors_archived": {
"default": 0,
"minimum": 0,
"title": "Monitors Archived",
"type": "integer"
},
"not_restored": {
"default": [],
"description": "Restore only: what the caller must still do by hand. Repeat these to the user verbatim.",
"items": {
"type": "string"
},
"maxItems": 8,
"title": "Not Restored",
"type": "array"
},
"errors": {
"default": [],
"items": {
"type": "string"
},
"maxItems": 32,
"title": "Errors",
"type": "array"
}
},
"title": "PublicAccountsArchiveResultV2",
"type": "object"
}
Get account
accounts.get.v2
Use when: Load one account by id when resource reads are unavailable. Its campaigns field lists every campaign the account belongs to, with each campaign's status. A matched rubric disqualifier pins the account to the lowest grade whatever it scored, so read icp_disqualified and icp_disqualification_reason before treating a high score beside a low grade as wrong.
Avoid when: Prefer hivekind://account/{id}. Use accounts.search.v2 if you do not have an id.
Effects: Reads current workspace state.
Cost: No gateway credit charge; reads saved workspace data without starting paid provider work. Gateway rate code: none; downstream billing may apply.
Access: accounts:read. Approval: operation authorization. Reads do not need an operation UUID.
Keep the same operation and operation_id when retrying identical work. Reconcile an uncertain result before new work; never replay an old V1 write under a new V2 ID.
Check status, execution_state, error_code, output and evidence/resource references. Queued work is not complete: poll jobs.status.get.v2 in domain.workspace.v2. For read-back verification require read_back_verified=true where returned; reconcile failures without creating another object.
Invocation example using fictional fixtures
{
"tool": "domain.accounts.v2",
"arguments": {
"params": {
"action": "invoke",
"operation": "accounts.get.v2",
"arguments": {
"account_id": "00000000-0000-4000-8000-000000000001"
},
"operation_id": "00000000-0000-4000-8000-000000000003"
}
},
"notice": "Fictional fixture IDs and example text. Resolve real IDs, use returned preview tokens and approve exact side effects before execution. Input validation is not proof of provider readiness or a successful business outcome."
}
Input schema: fields, defaults and constraints
{
"additionalProperties": false,
"properties": {
"account_id": {
"description": "Exact account UUID returned by a Hivekind search, list, get, preview, or resource call.",
"format": "uuid",
"title": "Account Id",
"type": "string"
}
},
"required": [
"account_id"
],
"title": "McpPublicAccountsGetInputV2",
"type": "object"
}
Output schema inside the result envelope
{
"$defs": {
"AccountCampaignMembershipV1": {
"additionalProperties": false,
"description": "One campaign an account belongs to (HIVE-1388).",
"properties": {
"campaign_id": {
"format": "uuid",
"title": "Campaign Id",
"type": "string"
},
"name": {
"maxLength": 255,
"title": "Name",
"type": "string"
},
"status": {
"description": "The campaign's status: \"active\", \"draft\", \"paused\", or \"archived\" once it has been archived, whatever it was before.",
"maxLength": 64,
"title": "Status",
"type": "string"
},
"added_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "When the account joined the campaign (UTC).",
"title": "Added At"
}
},
"required": [
"campaign_id",
"name",
"status"
],
"title": "AccountCampaignMembershipV1",
"type": "object"
}
},
"additionalProperties": false,
"description": "V2 result for accounts.get.v2; preserves the established validators.",
"properties": {
"account_id": {
"format": "uuid",
"title": "Account Id",
"type": "string"
},
"name": {
"maxLength": 255,
"minLength": 1,
"title": "Name",
"type": "string"
},
"domain": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Domain"
},
"industry": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Industry"
},
"region": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Region"
},
"employee_count": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Employee Count"
},
"owner_id": {
"anyOf": [
{
"format": "uuid",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Owner Id"
},
"account_type": {
"anyOf": [
{
"maxLength": 64,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Account Type"
},
"icp_score": {
"anyOf": [
{
"maximum": 100,
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Icp Score"
},
"icp_grade": {
"anyOf": [
{
"maxLength": 32,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Icp Grade"
},
"updated_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "When the account record last changed (UTC).",
"title": "Updated At"
},
"icp_disqualified": {
"default": false,
"description": "True when a rubric disqualifier matched this account. A disqualifier pins the account to the rubric's lowest tier no matter how well it scored, so a high icp_score beside a low icp_grade is expected here, not a data error.",
"title": "Icp Disqualified",
"type": "boolean"
},
"icp_disqualification_reason": {
"anyOf": [
{
"maxLength": 500,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Which disqualifier matched and why. Null unless icp_disqualified is true.",
"title": "Icp Disqualification Reason"
},
"network_strength": {
"default": 0,
"description": "Connection strength from distinct usable LinkedIn workspace members and Channel Partner organizations, capped at three.",
"maximum": 3,
"minimum": 0,
"title": "Network Strength",
"type": "integer"
},
"independent_source_count": {
"default": 0,
"description": "Uncapped number of distinct usable network sources.",
"minimum": 0,
"title": "Independent Source Count",
"type": "integer"
},
"linkedin_member_count": {
"default": 0,
"description": "Distinct consented workspace LinkedIn members with a usable route.",
"minimum": 0,
"title": "Linkedin Member Count",
"type": "integer"
},
"partner_count": {
"default": 0,
"description": "Distinct active Channel Partner organizations with confirmed usable routes.",
"minimum": 0,
"title": "Partner Count",
"type": "integer"
},
"partner_names": {
"default": [],
"description": "Names of active Channel Partners providing usable routes.",
"items": {
"type": "string"
},
"maxItems": 20,
"title": "Partner Names",
"type": "array"
},
"tags": {
"default": [],
"description": "Account tags on this account (free-form workspace labels).",
"items": {
"type": "string"
},
"maxItems": 50,
"title": "Tags",
"type": "array"
},
"web_url": {
"anyOf": [
{
"maxLength": 2048,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Browser link to this account in the Hivekind app. Use it verbatim whenever you link the record for a person, including inside note bodies; never build a link by hand or use a hivekind:// URI, which is an MCP resource handle, not a page. Null when the server has no app URL configured.",
"title": "Web Url"
},
"campaigns": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/AccountCampaignMembershipV1"
},
"maxItems": 50,
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Every campaign this account belongs to, archived ones included, newest membership first. An empty list means it is in none; null means this tool did not look.",
"title": "Campaigns"
}
},
"required": [
"account_id",
"name"
],
"title": "PublicAccountsGetResultV2",
"type": "object"
}
Preview a company import
accounts.import.preview.v2
Use when: Show what a company list would land as in Hive Base and how many rows match accounts that already exist. Send the file whole; the response's column_policy names source-system noise. Pass an exact Partner Account and confirmed or sourced semantics to prepare a partner-network import.
Avoid when: Do not use this when the rows carry people — those belong to prospects.import.preview.v2.
Effects: Writes nothing. Returns an import_token that accounts.import.start.v2 can commit.
Cost: No gateway rate is configured. Check the Core workflow preview/quote for downstream charges and final settlement. Gateway rate code: none; downstream billing may apply.
Access: runs:create. Approval: operation authorization. A stable operation UUID is required.
Keep the same operation and operation_id when retrying identical work. Reconcile an uncertain result before new work; never replay an old V1 write under a new V2 ID.
Check status, execution_state, error_code, output and evidence/resource references. Queued work is not complete: poll jobs.status.get.v2 in domain.workspace.v2. For read-back verification require read_back_verified=true where returned; reconcile failures without creating another object.
Invocation example using fictional fixtures
{
"tool": "domain.accounts.v2",
"arguments": {
"params": {
"action": "invoke",
"operation": "accounts.import.preview.v2",
"arguments": {
"companies": [
{
"domain": "example.com",
"name": "Example company"
}
]
},
"operation_id": "00000000-0000-4000-8000-000000000003"
}
},
"notice": "Fictional fixture IDs and example text. Resolve real IDs, use returned preview tokens and approve exact side effects before execution. Input validation is not proof of provider readiness or a successful business outcome."
}
Input schema: fields, defaults and constraints
{
"$defs": {
"CompanyInputV1": {
"additionalProperties": false,
"description": "Fields mirror the account CSV importer's canonical columns exactly, so a\nstructured row and an uploaded file take the same path with no remapping.",
"properties": {
"name": {
"maxLength": 255,
"minLength": 1,
"title": "Name",
"type": "string"
},
"domain": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Domain"
},
"industry": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Industry"
},
"city": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "City"
},
"country": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Country"
},
"employee_count": {
"anyOf": [
{
"maximum": 10000000,
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Employee Count"
},
"annual_revenue": {
"anyOf": [
{
"maxLength": 64,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Annual Revenue"
},
"account_type": {
"anyOf": [
{
"maxLength": 64,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Account Type"
},
"account_tier": {
"anyOf": [
{
"maxLength": 64,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Account Tier"
},
"owner_email": {
"anyOf": [
{
"maxLength": 320,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Owner Email"
}
},
"required": [
"name"
],
"title": "CompanyInputV1",
"type": "object"
}
},
"additionalProperties": false,
"properties": {
"csv_text": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Verbatim contents of a CSV the caller holds. Send the file exactly as it is: never retype values, reorder or drop rows, summarise, or leave columns out. The server maps arbitrary column layouts itself, and the preview reports which columns it reads as source-system noise, and why, in column_policy. Decide there with the user -- not here.",
"title": "Csv Text"
},
"exclude_columns": {
"default": [],
"description": "Source columns to leave out, after the user agreed to it. Leave empty on a first preview. Naming a column the server protects, or one that is mapped to a canonical field, fails the whole call.",
"items": {
"type": "string"
},
"maxItems": 200,
"title": "Exclude Columns",
"type": "array"
},
"keep_columns": {
"default": [],
"description": "Source columns to retain whatever the server makes of them. Use it when the user says a column matters. Outranks exclude_columns.",
"items": {
"type": "string"
},
"maxItems": 200,
"title": "Keep Columns",
"type": "array"
},
"tags": {
"anyOf": [
{
"items": {
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"maxItems": 10,
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Account tags (1-64 characters each, at most 10) added to every account this import creates or matches -- existing accounts get the tag and nothing else on them changes. Matched case-insensitively against existing tags; resolve them with accounts.tags.list.v2 first. The preview's import_token locks these in: omit tags on the commit to reuse them, and a different list is refused. Separate from the source badge.",
"title": "Tags"
},
"companies": {
"default": [],
"description": "Companies used by the public accounts import preview input v2 operation.",
"items": {
"$ref": "#/$defs/CompanyInputV1"
},
"maxItems": 2000,
"title": "Companies",
"type": "array"
},
"partner_account_id": {
"anyOf": [
{
"format": "uuid",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Exact active Channel Partner Account whose network supplied these companies. When set, existing Accounts are preserved and routes are attached instead of reclassifying them.",
"title": "Partner Account Id"
},
"partner_relationship_status": {
"anyOf": [
{
"enum": [
"confirmed",
"sourced"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Required with partner_account_id. Confirmed means the Partner attests a usable relationship; sourced stays visible but adds no strength.",
"title": "Partner Relationship Status"
}
},
"title": "McpPublicAccountsImportPreviewInputV2",
"type": "object"
}
Output schema inside the result envelope
{
"$defs": {
"ExcludedColumnV1": {
"additionalProperties": false,
"description": "One source column the server left out, or proposes leaving out.",
"properties": {
"column": {
"maxLength": 255,
"title": "Column",
"type": "string"
},
"reason": {
"enum": [
"empty_column",
"opaque_source_id",
"payment_metadata",
"source_system_link",
"caller_selected"
],
"title": "Reason",
"type": "string"
},
"detail": {
"default": "",
"maxLength": 500,
"title": "Detail",
"type": "string"
}
},
"required": [
"column",
"reason"
],
"title": "ExcludedColumnV1",
"type": "object"
},
"ImportColumnPolicyV1": {
"additionalProperties": false,
"description": "What the server made of the file's columns.\n\n``applied`` is the field that matters. False -- the default for any preview\nthat was not given a selection -- means ``excluded_columns`` is a proposal\nand every column was still imported. Show it to the user, take their answer,\nand send it back as ``exclude_columns`` if they agree. Never act on it alone.",
"properties": {
"version": {
"default": 1,
"title": "Version",
"type": "integer"
},
"applied": {
"default": false,
"title": "Applied",
"type": "boolean"
},
"retained_columns": {
"default": [],
"items": {
"type": "string"
},
"title": "Retained Columns",
"type": "array"
},
"excluded_columns": {
"default": [],
"items": {
"$ref": "#/$defs/ExcludedColumnV1"
},
"title": "Excluded Columns",
"type": "array"
}
},
"title": "ImportColumnPolicyV1",
"type": "object"
},
"JsonValue": {}
},
"additionalProperties": false,
"description": "V2 result for accounts.import.preview.v2; preserves the established validators.",
"properties": {
"column_policy": {
"anyOf": [
{
"$ref": "#/$defs/ImportColumnPolicyV1"
},
{
"type": "null"
}
],
"default": null,
"description": "What the server made of the file's columns. When applied is false this is a proposal only and nothing was left out."
},
"import_token": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Pass to the matching commit tool to reuse exactly these rows. Null when no cache backend was reachable -- resend the data instead.",
"title": "Import Token"
},
"rows_parsed": {
"default": 0,
"minimum": 0,
"title": "Rows Parsed",
"type": "integer"
},
"column_mapping": {
"additionalProperties": {
"type": "string"
},
"title": "Column Mapping",
"type": "object"
},
"matches_existing_accounts": {
"default": 0,
"minimum": 0,
"title": "Matches Existing Accounts",
"type": "integer"
},
"new_companies": {
"default": 0,
"minimum": 0,
"title": "New Companies",
"type": "integer"
},
"sample_rows": {
"default": [],
"items": {
"additionalProperties": {
"$ref": "#/$defs/JsonValue"
},
"type": "object"
},
"maxItems": 5,
"title": "Sample Rows",
"type": "array"
},
"tags": {
"default": [],
"description": "Account tags the import_token is locked to.",
"items": {
"type": "string"
},
"title": "Tags",
"type": "array"
},
"accounts_to_tag": {
"default": 0,
"description": "Accounts the commit would tag: matches_existing_accounts plus new_companies. Zero when no tags were given.",
"minimum": 0,
"title": "Accounts To Tag",
"type": "integer"
}
},
"title": "PublicAccountsImportPreviewResultV2",
"type": "object"
}
Import companies
accounts.import.start.v2
Use when: Create accounts from a company list, or attach them to an exact Channel Partner when partner context is supplied. Partner imports preserve existing Accounts and do not auto-score.
Avoid when: Do not use this to add people; it never creates contacts.
Effects: Queues a job that creates accounts and may score them. Created and matched accounts are badged with the import source when you pass source (name, kind; the id comes back as source_id). Poll jobs.status.get.v2.
Cost: No gateway rate is configured. Check the Core workflow preview/quote for downstream charges and final settlement. Gateway rate code: none; downstream billing may apply.
Access: actions:execute. Approval: exact_scope_single_action. A stable operation UUID is required.
Keep the same operation and operation_id when retrying identical work. Reconcile an uncertain result before new work; never replay an old V1 write under a new V2 ID.
Check status, execution_state, error_code, output and evidence/resource references. Queued work is not complete: poll jobs.status.get.v2 in domain.workspace.v2. For read-back verification require read_back_verified=true where returned; reconcile failures without creating another object.
Invocation example using fictional fixtures
{
"tool": "domain.accounts.v2",
"arguments": {
"params": {
"action": "invoke",
"operation": "accounts.import.start.v2",
"arguments": {
"import_token": "use-the-exact-token-from-the-approved-preview"
},
"operation_id": "00000000-0000-4000-8000-000000000003"
}
},
"notice": "Fictional fixture IDs and example text. Resolve real IDs, use returned preview tokens and approve exact side effects before execution. Input validation is not proof of provider readiness or a successful business outcome."
}
Input schema: fields, defaults and constraints
{
"$defs": {
"CompanyInputV1": {
"additionalProperties": false,
"description": "Fields mirror the account CSV importer's canonical columns exactly, so a\nstructured row and an uploaded file take the same path with no remapping.",
"properties": {
"name": {
"maxLength": 255,
"minLength": 1,
"title": "Name",
"type": "string"
},
"domain": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Domain"
},
"industry": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Industry"
},
"city": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "City"
},
"country": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Country"
},
"employee_count": {
"anyOf": [
{
"maximum": 10000000,
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Employee Count"
},
"annual_revenue": {
"anyOf": [
{
"maxLength": 64,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Annual Revenue"
},
"account_type": {
"anyOf": [
{
"maxLength": 64,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Account Type"
},
"account_tier": {
"anyOf": [
{
"maxLength": 64,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Account Tier"
},
"owner_email": {
"anyOf": [
{
"maxLength": 320,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Owner Email"
}
},
"required": [
"name"
],
"title": "CompanyInputV1",
"type": "object"
},
"ImportSourceInputV1": {
"additionalProperties": false,
"description": "Where this list came from. Every record the import creates or matches is badged with it.",
"properties": {
"source_id": {
"anyOf": [
{
"format": "uuid",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Add to an existing source instead of creating one.",
"title": "Source Id"
},
"name": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "New source name, e.g. 'AI for CFOs workshop'. Omit to name it after the file.",
"title": "Name"
},
"kind": {
"default": "list",
"enum": [
"workshop",
"event",
"webinar",
"list",
"other"
],
"title": "Kind",
"type": "string"
},
"occurred_on": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Occurred On"
},
"details": {
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"description": "Location, host, link, notes. Flat: at most 20 keys (each up to 64 characters), values are text up to 1000 characters, numbers, booleans or null. No nested objects or lists.",
"title": "Details",
"type": "object"
}
},
"title": "ImportSourceInputV1",
"type": "object"
}
},
"additionalProperties": false,
"properties": {
"csv_text": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Verbatim contents of a CSV the caller holds. Send the file exactly as it is: never retype values, reorder or drop rows, summarise, or leave columns out. The server maps arbitrary column layouts itself, and the preview reports which columns it reads as source-system noise, and why, in column_policy. Decide there with the user -- not here.",
"title": "Csv Text"
},
"exclude_columns": {
"default": [],
"description": "Source columns to leave out, after the user agreed to it. Leave empty on a first preview. Naming a column the server protects, or one that is mapped to a canonical field, fails the whole call.",
"items": {
"type": "string"
},
"maxItems": 200,
"title": "Exclude Columns",
"type": "array"
},
"keep_columns": {
"default": [],
"description": "Source columns to retain whatever the server makes of them. Use it when the user says a column matters. Outranks exclude_columns.",
"items": {
"type": "string"
},
"maxItems": 200,
"title": "Keep Columns",
"type": "array"
},
"tags": {
"anyOf": [
{
"items": {
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"maxItems": 10,
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Account tags (1-64 characters each, at most 10) added to every account this import creates or matches -- existing accounts get the tag and nothing else on them changes. Matched case-insensitively against existing tags; resolve them with accounts.tags.list.v2 first. The preview's import_token locks these in: omit tags on the commit to reuse them, and a different list is refused. Separate from the source badge.",
"title": "Tags"
},
"companies": {
"default": [],
"description": "Companies used by the public accounts import start input v2 operation.",
"items": {
"$ref": "#/$defs/CompanyInputV1"
},
"maxItems": 2000,
"title": "Companies",
"type": "array"
},
"partner_account_id": {
"anyOf": [
{
"format": "uuid",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Exact active Channel Partner Account whose network supplied these companies. When set, existing Accounts are preserved and routes are attached instead of reclassifying them.",
"title": "Partner Account Id"
},
"partner_relationship_status": {
"anyOf": [
{
"enum": [
"confirmed",
"sourced"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Required with partner_account_id. Confirmed means the Partner attests a usable relationship; sourced stays visible but adds no strength.",
"title": "Partner Relationship Status"
},
"source": {
"anyOf": [
{
"$ref": "#/$defs/ImportSourceInputV1"
},
{
"type": "null"
}
],
"default": null,
"description": "Label this list so every account and contact it creates or matches is badged with where it came from (workshop, event, webinar, list). The id comes back as source_id on the result."
},
"action_proposal_id": {
"anyOf": [
{
"format": "uuid",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional. Hivekind fills this from the MCP consent grant.",
"title": "Action Proposal Id"
},
"import_token": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Import token used by the public accounts import start input v2 operation.",
"title": "Import Token"
}
},
"title": "McpMcpPublicAccountsImportStartInputV2",
"type": "object"
}
Use when: You need accounts selected by name, domain, owner, region, industry, saved ICP, or unified LinkedIn-plus-Partner network strength. Use network_strength_then_icp to rank warm accounts while retaining ungraded matches.
Avoid when: The audience requires contact-level LinkedIn evidence, buyer roles, or signals; use targets.preview.v2.
Effects: Applies network-strength and ICP filters before pagination, then returns one bounded, deterministically sorted page. Read only.
Cost: No gateway credit charge; reads saved workspace data without starting paid provider work. Gateway rate code: none; downstream billing may apply.
Access: accounts:read. Approval: operation authorization. Reads do not need an operation UUID.
Keep the same operation and operation_id when retrying identical work. Reconcile an uncertain result before new work; never replay an old V1 write under a new V2 ID.
Check status, execution_state, error_code, output and evidence/resource references. Queued work is not complete: poll jobs.status.get.v2 in domain.workspace.v2. For read-back verification require read_back_verified=true where returned; reconcile failures without creating another object.
Invocation example using fictional fixtures
{
"tool": "domain.accounts.v2",
"arguments": {
"params": {
"action": "invoke",
"operation": "accounts.search.v2",
"arguments": {},
"operation_id": "00000000-0000-4000-8000-000000000003"
}
},
"notice": "Fictional fixture IDs and example text. Resolve real IDs, use returned preview tokens and approve exact side effects before execution. Input validation is not proof of provider readiness or a successful business outcome."
}
Input schema: fields, defaults and constraints
{
"additionalProperties": false,
"properties": {
"query": {
"default": "*",
"description": "Search text. Use a name, domain, title, or other identifying phrase relevant to this operation.",
"maxLength": 1000,
"minLength": 1,
"title": "Query",
"type": "string"
},
"match_mode": {
"default": "contains",
"description": "How query is matched against an account's name and domain. \"contains\" finds it anywhere in either; \"prefix\" matches the start; \"exact\" matches the whole name or the whole domain, case insensitively. Reach for exact or prefix when you already know the company's name — a short word matches a great many companies in the middle of a longer name.",
"enum": [
"contains",
"exact",
"prefix"
],
"title": "Match Mode",
"type": "string"
},
"account_ids": {
"default": [],
"description": "Exact account UUIDs returned by a Hivekind search, list, get, preview, or resource call.",
"items": {
"format": "uuid",
"type": "string"
},
"maxItems": 100,
"title": "Account Ids",
"type": "array"
},
"tags": {
"default": [],
"description": "Only accounts carrying these account tags, matched case-insensitively. See tags_match. List the workspace's tags with accounts.tags.list.v2.",
"items": {
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"maxItems": 10,
"title": "Tags",
"type": "array"
},
"tags_match": {
"default": "any",
"description": "any: an account with at least one of tags. all: every one of them.",
"enum": [
"any",
"all"
],
"title": "Tags Match",
"type": "string"
},
"campaign_ids": {
"default": [],
"description": "Only accounts that belong to any of these campaigns (archived campaigns included). Combines with every other filter. Page through with offset to pull a whole campaign's accounts.",
"items": {
"format": "uuid",
"type": "string"
},
"maxItems": 50,
"title": "Campaign Ids",
"type": "array"
},
"source_ids": {
"default": [],
"description": "Only accounts linked to any of these import sources (workshop, event, webinar or list badges).",
"items": {
"format": "uuid",
"type": "string"
},
"maxItems": 50,
"title": "Source Ids",
"type": "array"
},
"icp_grades": {
"default": [],
"description": "Icp grades used by the accounts search input v2 operation.",
"items": {
"type": "string"
},
"maxItems": 8,
"title": "Icp Grades",
"type": "array"
},
"industries": {
"default": [],
"description": "Industries used by the accounts search input v2 operation.",
"items": {
"type": "string"
},
"maxItems": 50,
"title": "Industries",
"type": "array"
},
"regions": {
"default": [],
"description": "Regions used by the accounts search input v2 operation.",
"items": {
"type": "string"
},
"maxItems": 50,
"title": "Regions",
"type": "array"
},
"owner_ids": {
"default": [],
"description": "Exact owner UUIDs returned by a Hivekind search, list, get, preview, or resource call.",
"items": {
"format": "uuid",
"type": "string"
},
"maxItems": 100,
"title": "Owner Ids",
"type": "array"
},
"owner_scope": {
"default": "any",
"description": "Owner scope used by the accounts search input v2 operation.",
"enum": [
"any",
"assigned",
"unassigned",
"mine"
],
"title": "Owner Scope",
"type": "string"
},
"account_types": {
"default": [],
"description": "Account types used by the accounts search input v2 operation.",
"items": {
"type": "string"
},
"maxItems": 20,
"title": "Account Types",
"type": "array"
},
"in_hiveloop": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "In hiveloop used by the accounts search input v2 operation.",
"title": "In Hiveloop"
},
"minimum_icp_score": {
"anyOf": [
{
"maximum": 100,
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum icp score used to bound matching records.",
"title": "Minimum Icp Score"
},
"maximum_icp_score": {
"anyOf": [
{
"maximum": 100,
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Maximum icp score used to bound matching records.",
"title": "Maximum Icp Score"
},
"minimum_employee_count": {
"anyOf": [
{
"maximum": 10000000,
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Minimum employee count used to bound matching records.",
"title": "Minimum Employee Count"
},
"maximum_employee_count": {
"anyOf": [
{
"maximum": 10000000,
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Maximum employee count used to bound matching records.",
"title": "Maximum Employee Count"
},
"network_sources": {
"default": [
"linkedin",
"partner"
],
"description": "Network source types counted for filtering and ranking. LinkedIn uses self plus consented workspace members; partner uses confirmed usable active Channel Partner routes.",
"items": {
"enum": [
"linkedin",
"partner"
],
"type": "string"
},
"maxItems": 2,
"minItems": 1,
"title": "Network Sources",
"type": "array"
},
"minimum_network_strength": {
"anyOf": [
{
"maximum": 3,
"minimum": 1,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Require at least this many distinct usable network sources, capped at three. Applied before sorting and pagination.",
"title": "Minimum Network Strength"
},
"sort_by": {
"default": "updated_at",
"description": "updated_at (the default) lists the accounts added or changed most recently first. Pass icp_score to rank by fit, or network_strength_then_icp to rank by reachable network.",
"enum": [
"updated_at",
"icp_score",
"name",
"created_at",
"network_strength_then_icp"
],
"title": "Sort By",
"type": "string"
},
"sort_direction": {
"default": "desc",
"description": "Sort direction used by the accounts search input v2 operation.",
"enum": [
"asc",
"desc"
],
"title": "Sort Direction",
"type": "string"
},
"offset": {
"default": 0,
"description": "Zero-based number of matching records to skip for pagination.",
"maximum": 1000000,
"minimum": 0,
"title": "Offset",
"type": "integer"
},
"limit": {
"default": 25,
"description": "Maximum number of records to return in this page.",
"maximum": 100,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
"title": "McpAccountsSearchInputV2",
"type": "object"
}
Output schema inside the result envelope
{
"$defs": {
"AccountCampaignMembershipV1": {
"additionalProperties": false,
"description": "One campaign an account belongs to (HIVE-1388).",
"properties": {
"campaign_id": {
"format": "uuid",
"title": "Campaign Id",
"type": "string"
},
"name": {
"maxLength": 255,
"title": "Name",
"type": "string"
},
"status": {
"description": "The campaign's status: \"active\", \"draft\", \"paused\", or \"archived\" once it has been archived, whatever it was before.",
"maxLength": 64,
"title": "Status",
"type": "string"
},
"added_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "When the account joined the campaign (UTC).",
"title": "Added At"
}
},
"required": [
"campaign_id",
"name",
"status"
],
"title": "AccountCampaignMembershipV1",
"type": "object"
},
"AccountSummaryV1": {
"additionalProperties": false,
"properties": {
"account_id": {
"format": "uuid",
"title": "Account Id",
"type": "string"
},
"name": {
"maxLength": 255,
"minLength": 1,
"title": "Name",
"type": "string"
},
"domain": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Domain"
},
"industry": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Industry"
},
"region": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Region"
},
"employee_count": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Employee Count"
},
"owner_id": {
"anyOf": [
{
"format": "uuid",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Owner Id"
},
"account_type": {
"anyOf": [
{
"maxLength": 64,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Account Type"
},
"icp_score": {
"anyOf": [
{
"maximum": 100,
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Icp Score"
},
"icp_grade": {
"anyOf": [
{
"maxLength": 32,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Icp Grade"
},
"updated_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "When the account record last changed (UTC).",
"title": "Updated At"
},
"icp_disqualified": {
"default": false,
"description": "True when a rubric disqualifier matched this account. A disqualifier pins the account to the rubric's lowest tier no matter how well it scored, so a high icp_score beside a low icp_grade is expected here, not a data error.",
"title": "Icp Disqualified",
"type": "boolean"
},
"icp_disqualification_reason": {
"anyOf": [
{
"maxLength": 500,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Which disqualifier matched and why. Null unless icp_disqualified is true.",
"title": "Icp Disqualification Reason"
},
"network_strength": {
"default": 0,
"description": "Connection strength from distinct usable LinkedIn workspace members and Channel Partner organizations, capped at three.",
"maximum": 3,
"minimum": 0,
"title": "Network Strength",
"type": "integer"
},
"independent_source_count": {
"default": 0,
"description": "Uncapped number of distinct usable network sources.",
"minimum": 0,
"title": "Independent Source Count",
"type": "integer"
},
"linkedin_member_count": {
"default": 0,
"description": "Distinct consented workspace LinkedIn members with a usable route.",
"minimum": 0,
"title": "Linkedin Member Count",
"type": "integer"
},
"partner_count": {
"default": 0,
"description": "Distinct active Channel Partner organizations with confirmed usable routes.",
"minimum": 0,
"title": "Partner Count",
"type": "integer"
},
"partner_names": {
"default": [],
"description": "Names of active Channel Partners providing usable routes.",
"items": {
"type": "string"
},
"maxItems": 20,
"title": "Partner Names",
"type": "array"
},
"tags": {
"default": [],
"description": "Account tags on this account (free-form workspace labels).",
"items": {
"type": "string"
},
"maxItems": 50,
"title": "Tags",
"type": "array"
},
"web_url": {
"anyOf": [
{
"maxLength": 2048,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Browser link to this account in the Hivekind app. Use it verbatim whenever you link the record for a person, including inside note bodies; never build a link by hand or use a hivekind:// URI, which is an MCP resource handle, not a page. Null when the server has no app URL configured.",
"title": "Web Url"
},
"campaigns": {
"anyOf": [
{
"items": {
"$ref": "#/$defs/AccountCampaignMembershipV1"
},
"maxItems": 50,
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Every campaign this account belongs to, archived ones included, newest membership first. An empty list means it is in none; null means this tool did not look.",
"title": "Campaigns"
}
},
"required": [
"account_id",
"name"
],
"title": "AccountSummaryV1",
"type": "object"
}
},
"additionalProperties": false,
"properties": {
"accounts": {
"default": [],
"items": {
"$ref": "#/$defs/AccountSummaryV1"
},
"title": "Accounts",
"type": "array"
},
"total": {
"default": 0,
"minimum": 0,
"title": "Total",
"type": "integer"
},
"offset": {
"default": 0,
"minimum": 0,
"title": "Offset",
"type": "integer"
},
"limit": {
"default": 25,
"maximum": 100,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
"title": "AccountsSearchResultV2",
"type": "object"
}
Tag accounts
accounts.tags.apply.v2
Use when: Add or remove free-form account tags (e.g. "TechWeek 2026") on many accounts at once. Pick the accounts with exactly one of account_ids (up to 500), campaign_id (every account in that campaign's audience) or event_id (every account the event's roster was matched to or created). Resolve existing tag names with accounts.tags.list.v2 first, then call with dry_run true and show the user how many accounts would change before applying.
Avoid when: Do not use this to edit account fields — that is accounts.update.v2 — or to add accounts to a campaign, which is campaigns.audience.add.v2. Do not use it to badge where a list came from: imports already badge their source. To tag accounts as they are imported, pass tags on the import tools instead.
Effects: Adds or removes tags only. No credits are spent, nothing is re-scored, and contacts, HiveLoops and drafts are untouched. Tag names are trimmed and matched case-insensitively; a name with no existing match creates a new tag with the casing given. Archived accounts and ids outside the workspace are skipped with a reason; accounts that already have the tag are reported as unchanged. dry_run true writes nothing.
Cost: No gateway rate is configured. Check the Core workflow preview/quote for downstream charges and final settlement. Gateway rate code: none; downstream billing may apply.
Access: actions:execute. Approval: exact_scope_single_action. A stable operation UUID is required.
Keep the same operation and operation_id when retrying identical work. Reconcile an uncertain result before new work; never replay an old V1 write under a new V2 ID.
Check status, execution_state, error_code, output and evidence/resource references. Queued work is not complete: poll jobs.status.get.v2 in domain.workspace.v2. For read-back verification require read_back_verified=true where returned; reconcile failures without creating another object.
Invocation example using fictional fixtures
{
"tool": "domain.accounts.v2",
"arguments": {
"params": {
"action": "invoke",
"operation": "accounts.tags.apply.v2",
"arguments": {
"account_ids": [
"00000000-0000-4000-8000-000000000001"
],
"add_tags": [
"Event attendee"
]
},
"operation_id": "00000000-0000-4000-8000-000000000003"
}
},
"notice": "Fictional fixture IDs and example text. Resolve real IDs, use returned preview tokens and approve exact side effects before execution. Input validation is not proof of provider readiness or a successful business outcome."
}
Input schema: fields, defaults and constraints
{
"additionalProperties": false,
"properties": {
"action_proposal_id": {
"anyOf": [
{
"format": "uuid",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional. Hivekind fills this from the MCP consent grant.",
"title": "Action Proposal Id"
},
"account_ids": {
"anyOf": [
{
"items": {
"format": "uuid",
"type": "string"
},
"maxItems": 500,
"minItems": 1,
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Exact accounts to tag. One of account_ids, campaign_id or event_id.",
"title": "Account Ids"
},
"campaign_id": {
"anyOf": [
{
"format": "uuid",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Tag every account in this campaign's audience.",
"title": "Campaign Id"
},
"event_id": {
"anyOf": [
{
"format": "uuid",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Tag every account this event's roster was matched to or created.",
"title": "Event Id"
},
"add_tags": {
"default": [],
"description": "Add tags used by the public accounts tags apply input v2 operation.",
"items": {
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"maxItems": 10,
"title": "Add Tags",
"type": "array"
},
"remove_tags": {
"default": [],
"description": "Remove tags used by the public accounts tags apply input v2 operation.",
"items": {
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"maxItems": 10,
"title": "Remove Tags",
"type": "array"
},
"dry_run": {
"default": false,
"description": "Report what would change and write nothing. Run this first and show the user.",
"title": "Dry Run",
"type": "boolean"
}
},
"title": "McpMcpPublicAccountsTagsApplyInputV2",
"type": "object"
}
Output schema inside the result envelope
{
"$defs": {
"AccountTagRefV1": {
"additionalProperties": false,
"properties": {
"tag_id": {
"anyOf": [
{
"format": "uuid",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Null only in a dry run, for a tag the real run would create.",
"title": "Tag Id"
},
"name": {
"maxLength": 64,
"minLength": 1,
"title": "Name",
"type": "string"
},
"color": {
"maxLength": 32,
"minLength": 1,
"title": "Color",
"type": "string"
},
"exists": {
"default": true,
"description": "False when the tag does not exist yet (dry run only).",
"title": "Exists",
"type": "boolean"
}
},
"required": [
"name",
"color"
],
"title": "AccountTagRefV1",
"type": "object"
},
"AccountTagSkipV1": {
"additionalProperties": false,
"properties": {
"account_id": {
"format": "uuid",
"title": "Account Id",
"type": "string"
},
"reason": {
"description": "archived: the account is archived. not_found: no such account in this workspace.",
"enum": [
"archived",
"not_found"
],
"title": "Reason",
"type": "string"
}
},
"required": [
"account_id",
"reason"
],
"title": "AccountTagSkipV1",
"type": "object"
}
},
"additionalProperties": false,
"description": "V2 result for accounts.tags.apply.v2; preserves the established validators.",
"properties": {
"dry_run": {
"title": "Dry Run",
"type": "boolean"
},
"selector": {
"enum": [
"account_ids",
"campaign_id",
"event_id"
],
"title": "Selector",
"type": "string"
},
"selected": {
"description": "Accounts the selector picked, before skips.",
"minimum": 0,
"title": "Selected",
"type": "integer"
},
"tagged": {
"description": "Accounts that changed (or would, in a dry run).",
"minimum": 0,
"title": "Tagged",
"type": "integer"
},
"unchanged": {
"description": "Accounts that already had every tag asked for.",
"minimum": 0,
"title": "Unchanged",
"type": "integer"
},
"skipped": {
"default": [],
"items": {
"$ref": "#/$defs/AccountTagSkipV1"
},
"maxItems": 500,
"title": "Skipped",
"type": "array"
},
"tags": {
"default": [],
"description": "Tags added, as stored.",
"items": {
"$ref": "#/$defs/AccountTagRefV1"
},
"maxItems": 10,
"title": "Tags",
"type": "array"
},
"removed_tags": {
"default": [],
"items": {
"$ref": "#/$defs/AccountTagRefV1"
},
"maxItems": 10,
"title": "Removed Tags",
"type": "array"
},
"tagged_account_ids": {
"default": [],
"items": {
"format": "uuid",
"type": "string"
},
"maxItems": 500,
"title": "Tagged Account Ids",
"type": "array"
},
"ids_truncated": {
"default": false,
"title": "Ids Truncated",
"type": "boolean"
}
},
"required": [
"dry_run",
"selector",
"selected",
"tagged",
"unchanged"
],
"title": "PublicAccountsTagsApplyResultV2",
"type": "object"
}
List account tags
accounts.tags.list.v2
Use when: See which account tags the workspace already uses and how many active accounts carry each, so a new tag reuses an existing name instead of creating a near-duplicate. Use query to look up a name.
Avoid when: Do not use this to find the accounts carrying a tag — that is accounts.search.v2 with tags. Import source badges (workshops, events, lists) are not tags.
Effects: Reads current workspace state.
Cost: No gateway credit charge; reads saved workspace data without starting paid provider work. Gateway rate code: none; downstream billing may apply.
Access: accounts:read. Approval: operation authorization. Reads do not need an operation UUID.
Keep the same operation and operation_id when retrying identical work. Reconcile an uncertain result before new work; never replay an old V1 write under a new V2 ID.
Check status, execution_state, error_code, output and evidence/resource references. Queued work is not complete: poll jobs.status.get.v2 in domain.workspace.v2. For read-back verification require read_back_verified=true where returned; reconcile failures without creating another object.
Invocation example using fictional fixtures
{
"tool": "domain.accounts.v2",
"arguments": {
"params": {
"action": "invoke",
"operation": "accounts.tags.list.v2",
"arguments": {},
"operation_id": "00000000-0000-4000-8000-000000000003"
}
},
"notice": "Fictional fixture IDs and example text. Resolve real IDs, use returned preview tokens and approve exact side effects before execution. Input validation is not proof of provider readiness or a successful business outcome."
}
Input schema: fields, defaults and constraints
{
"additionalProperties": false,
"properties": {
"query": {
"anyOf": [
{
"maxLength": 64,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Only tags whose name contains this, case-insensitively.",
"title": "Query"
},
"limit": {
"default": 100,
"description": "Maximum number of records to return in this page.",
"maximum": 200,
"minimum": 1,
"title": "Limit",
"type": "integer"
}
},
"title": "McpPublicAccountsTagsListInputV2",
"type": "object"
}
Use when: You need stable contact IDs at one account or across a bounded workspace search, including LinkedIn-shaped audiences: who a teammate connected with in a date range (connected_after/before), exact profile-URL lookup (linkedin_urls), relationship state or owner, source, last-interaction recency, and exclude_suppressed / exclude_in_active_campaign. account_ids in the result feed campaigns.launch directly.
Avoid when: You need verified relationship evidence; call network.paths.get.v2 after resolving contacts.
Effects: Returns a bounded contact page. Read only.
Cost: No gateway credit charge; reads saved workspace data without starting paid provider work. Gateway rate code: none; downstream billing may apply.
Access: accounts:read. Approval: operation authorization. Reads do not need an operation UUID.
Keep the same operation and operation_id when retrying identical work. Reconcile an uncertain result before new work; never replay an old V1 write under a new V2 ID.
Check status, execution_state, error_code, output and evidence/resource references. Queued work is not complete: poll jobs.status.get.v2 in domain.workspace.v2. For read-back verification require read_back_verified=true where returned; reconcile failures without creating another object.
Invocation example using fictional fixtures
{
"tool": "domain.accounts.v2",
"arguments": {
"params": {
"action": "invoke",
"operation": "contacts.search.v2",
"arguments": {},
"operation_id": "00000000-0000-4000-8000-000000000003"
}
},
"notice": "Fictional fixture IDs and example text. Resolve real IDs, use returned preview tokens and approve exact side effects before execution. Input validation is not proof of provider readiness or a successful business outcome."
}
Input schema: fields, defaults and constraints
{
"additionalProperties": false,
"properties": {
"query": {
"default": "*",
"description": "Search text. Use a name, domain, title, or other identifying phrase relevant to this operation.",
"maxLength": 255,
"minLength": 1,
"title": "Query",
"type": "string"
},
"offset": {
"default": 0,
"description": "Zero-based number of matching records to skip for pagination.",
"maximum": 1000000,
"minimum": 0,
"title": "Offset",
"type": "integer"
},
"account_id": {
"anyOf": [
{
"format": "uuid",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Exact account UUID returned by a Hivekind search, list, get, preview, or resource call.",
"title": "Account Id"
},
"buyer_role": {
"anyOf": [
{
"maxLength": 160,
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Buyer role used by the contacts search input v2 operation.",
"title": "Buyer Role"
},
"source_ids": {
"default": [],
"description": "Only contacts linked to any of these import sources (workshop, event, webinar or list badges).",
"items": {
"format": "uuid",
"type": "string"
},
"maxItems": 50,
"title": "Source Ids",
"type": "array"
},
"limit": {
"default": 20,
"description": "Maximum number of records to return in this page.",
"maximum": 50,
"minimum": 1,
"title": "Limit",
"type": "integer"
},
"sort_by": {
"default": "updated_at",
"description": "updated_at (the default) lists the contacts added or changed most recently first; icp_score ranks by fit.",
"enum": [
"updated_at",
"icp_score",
"name"
],
"title": "Sort By",
"type": "string"
},
"sort_direction": {
"default": "desc",
"description": "Sort direction used by the contacts search input v2 operation.",
"enum": [
"asc",
"desc"
],
"title": "Sort Direction",
"type": "string"
},
"linkedin_urls": {
"default": [],
"description": "Exact LinkedIn profile URLs to resolve to contacts (scheme, www, trailing slash and query string are ignored).",
"items": {
"type": "string"
},
"maxItems": 50,
"title": "Linkedin Urls",
"type": "array"
},
"connected_after": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Only contacts a visible teammate connected with on LinkedIn on or after this UTC date.",
"title": "Connected After"
},
"connected_before": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Only contacts a visible teammate connected with on LinkedIn on or before this UTC date (inclusive).",
"title": "Connected Before"
},
"relationship_status": {
"anyOf": [
{
"enum": [
"connected",
"invite_sent",
"none"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "connected = 1st-degree connection; invite_sent = our connection request is pending; none = neither.",
"title": "Relationship Status"
},
"relationship_owner_user_id": {
"anyOf": [
{
"format": "uuid",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Only contacts this team member is connected with on LinkedIn.",
"title": "Relationship Owner User Id"
},
"network_scope": {
"default": "workspace_consented",
"description": "Whose LinkedIn connections count: only the caller's, or also teammates who consented to share their network.",
"enum": [
"self",
"workspace_consented"
],
"title": "Network Scope",
"type": "string"
},
"source": {
"anyOf": [
{
"enum": [
"linkedin_sync",
"event_roster",
"apollo",
"hubspot"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "How the contact entered Hive Base.",
"title": "Source"
},
"last_interaction_after": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Only contacts whose last touch (sent message, signal or LinkedIn action) is on or after this UTC date.",
"title": "Last Interaction After"
},
"last_interaction_before": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Only contacts whose last touch is on or before this UTC date (inclusive); never-touched contacts are excluded.",
"title": "Last Interaction Before"
},
"never_interacted": {
"default": false,
"description": "Only contacts with no recorded touch of any kind.",
"title": "Never Interacted",
"type": "boolean"
},
"exclude_suppressed": {
"default": false,
"description": "Drop contacts with an active workspace-wide suppression (contact, email or domain).",
"title": "Exclude Suppressed",
"type": "boolean"
},
"exclude_in_active_campaign": {
"default": false,
"description": "Drop contacts currently enrolled in a live Hiveloop.",
"title": "Exclude In Active Campaign",
"type": "boolean"
}
},
"title": "McpContactsSearchInputV2",
"type": "object"
}
Output schema inside the result envelope
{
"$defs": {
"ContactSummaryV1": {
"additionalProperties": false,
"properties": {
"contact_id": {
"format": "uuid",
"title": "Contact Id",
"type": "string"
},
"account_id": {
"format": "uuid",
"title": "Account Id",
"type": "string"
},
"account_name": {
"maxLength": 255,
"minLength": 1,
"title": "Account Name",
"type": "string"
},
"display_name": {
"maxLength": 255,
"minLength": 1,
"title": "Display Name",
"type": "string"
},
"title": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Title"
},
"buyer_role": {
"anyOf": [
{
"maxLength": 160,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Buyer Role"
},
"icp_score": {
"anyOf": [
{
"maximum": 100,
"minimum": 0,
"type": "number"
},
{
"pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Icp Score"
},
"icp_grade": {
"anyOf": [
{
"maxLength": 32,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Icp Grade"
},
"has_email": {
"title": "Has Email",
"type": "boolean"
},
"has_linkedin": {
"title": "Has Linkedin",
"type": "boolean"
},
"linkedin_url": {
"anyOf": [
{
"maxLength": 1024,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Linkedin Url"
},
"relationship_status": {
"anyOf": [
{
"enum": [
"connected",
"invite_sent",
"none"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Relationship Status"
},
"connected_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Connected At"
},
"relationship_owner_user_id": {
"anyOf": [
{
"format": "uuid",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Relationship Owner User Id"
},
"relationship_owner_name": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Relationship Owner Name"
},
"last_interaction_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Last Interaction At"
},
"source": {
"anyOf": [
{
"enum": [
"linkedin_sync",
"event_roster",
"apollo",
"hubspot"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Source"
},
"updated_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "When the contact record last changed (UTC).",
"title": "Updated At"
},
"web_url": {
"anyOf": [
{
"maxLength": 2048,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Browser link to this contact in the Hivekind app. Use it verbatim whenever you link the record for a person, including inside note bodies; never build a link by hand or use a hivekind:// URI, which is an MCP resource handle, not a page. Null when the server has no app URL configured.",
"title": "Web Url"
},
"account_web_url": {
"anyOf": [
{
"maxLength": 2048,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Browser link to this contact's account in the Hivekind app. Use it verbatim whenever you link the record for a person, including inside note bodies; never build a link by hand or use a hivekind:// URI, which is an MCP resource handle, not a page. Null when the server has no app URL configured.",
"title": "Account Web Url"
}
},
"required": [
"contact_id",
"account_id",
"account_name",
"display_name",
"has_email",
"has_linkedin"
],
"title": "ContactSummaryV1",
"type": "object"
}
},
"additionalProperties": false,
"properties": {
"contacts": {
"default": [],
"items": {
"$ref": "#/$defs/ContactSummaryV1"
},
"maxItems": 50,
"title": "Contacts",
"type": "array"
},
"account_ids": {
"default": [],
"description": "Distinct account IDs of this page's contacts, in page order; pass to campaigns.launch.v2 / campaigns.audience.add.v2.",
"items": {
"format": "uuid",
"type": "string"
},
"maxItems": 50,
"title": "Account Ids",
"type": "array"
},
"unmatched_linkedin_urls": {
"default": [],
"description": "Requested LinkedIn URLs that match no active contact in the workspace (independent of the other filters).",
"items": {
"type": "string"
},
"maxItems": 50,
"title": "Unmatched Linkedin Urls",
"type": "array"
},
"offset": {
"default": 0,
"title": "Offset",
"type": "integer"
},
"has_more": {
"default": false,
"title": "Has More",
"type": "boolean"
}
},
"title": "ContactsSearchResultV2",
"type": "object"
}
Entity timeline
contacts.timeline.get.v2
Use when: Recorded interactions and notes for one contact, or for a whole account with entity_type=account, newest first. Paginate with before=next_cursor.
Avoid when: Do not infer inactivity from a truncated page, hidden content, or missing records; content is permission-gated.
Effects: Read only.
Cost: No gateway credit charge; reads saved workspace data without starting paid provider work. Gateway rate code: none; downstream billing may apply.
Access: accounts:read. Approval: operation authorization. Reads do not need an operation UUID.
Keep the same operation and operation_id when retrying identical work. Reconcile an uncertain result before new work; never replay an old V1 write under a new V2 ID.
Check status, execution_state, error_code, output and evidence/resource references. Queued work is not complete: poll jobs.status.get.v2 in domain.workspace.v2. For read-back verification require read_back_verified=true where returned; reconcile failures without creating another object.
Invocation example using fictional fixtures
{
"tool": "domain.accounts.v2",
"arguments": {
"params": {
"action": "invoke",
"operation": "contacts.timeline.get.v2",
"arguments": {
"contact_id": "00000000-0000-4000-8000-000000000001"
},
"operation_id": "00000000-0000-4000-8000-000000000003"
}
},
"notice": "Fictional fixture IDs and example text. Resolve real IDs, use returned preview tokens and approve exact side effects before execution. Input validation is not proof of provider readiness or a successful business outcome."
}
Input schema: fields, defaults and constraints
{
"additionalProperties": false,
"properties": {
"contact_id": {
"anyOf": [
{
"format": "uuid",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Exact contact UUID (shorthand for entity_type=contact).",
"title": "Contact Id"
},
"entity_type": {
"default": "contact",
"description": "Whose feed: a contact or a whole account.",
"enum": [
"contact",
"account"
],
"title": "Entity Type",
"type": "string"
},
"entity_id": {
"anyOf": [
{
"format": "uuid",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Exact contact_id or account_id; resolve it before invoking.",
"title": "Entity Id"
},
"before": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Page backwards with the previous next_cursor.",
"title": "Before"
},
"channel": {
"anyOf": [
{
"maxLength": 32,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "email, linkedin, data, note, ...",
"title": "Channel"
},
"limit": {
"default": 50,
"description": "Maximum number of records to return in this page.",
"maximum": 100,
"minimum": 1,
"title": "Limit",
"type": "integer"
},
"include_notes": {
"default": true,
"description": "Mix human and agent notes into the feed.",
"title": "Include Notes",
"type": "boolean"
},
"author_type": {
"anyOf": [
{
"enum": [
"user",
"agent"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Only notes by people (user) or by agents (agent).",
"title": "Author Type"
}
},
"title": "McpPublicContactsTimelineGetInputV2",
"type": "object"
}
Use when: Record what was learned about an account or a person — a meeting debrief, a call summary, a fact the user told you. Resolve the exact account_id or contact_id first. To link another record in the body, paste its web_url from a search result. To correct or extend a note a person wrote, reply to it with in_reply_to_note_id; you cannot edit it.
Avoid when: Do not use this for outreach copy (drafts and playbooks), for signals, or to restate data already on the record.
Effects: Creates a workspace-visible note authored as an agent on the user's behalf. Idempotent on operation_id; an identical recent note by the same principal is returned instead of duplicated. Agents have a daily ceiling per user.
Cost: No gateway rate is configured. Check the Core workflow preview/quote for downstream charges and final settlement. Gateway rate code: none; downstream billing may apply.
Access: actions:execute. Approval: exact_scope_single_action. A stable operation UUID is required.
Keep the same operation and operation_id when retrying identical work. Reconcile an uncertain result before new work; never replay an old V1 write under a new V2 ID.
Check status, execution_state, error_code, output and evidence/resource references. Queued work is not complete: poll jobs.status.get.v2 in domain.workspace.v2. For read-back verification require read_back_verified=true where returned; reconcile failures without creating another object.
Invocation example using fictional fixtures
{
"tool": "domain.accounts.v2",
"arguments": {
"params": {
"action": "invoke",
"operation": "notes.create.v2",
"arguments": {
"body": "Example body",
"entity_id": "00000000-0000-4000-8000-000000000001",
"entity_type": "account"
},
"operation_id": "00000000-0000-4000-8000-000000000003"
}
},
"notice": "Fictional fixture IDs and example text. Resolve real IDs, use returned preview tokens and approve exact side effects before execution. Input validation is not proof of provider readiness or a successful business outcome."
}
Input schema: fields, defaults and constraints
{
"additionalProperties": false,
"properties": {
"action_proposal_id": {
"anyOf": [
{
"format": "uuid",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional. Hivekind fills this from the MCP consent grant.",
"title": "Action Proposal Id"
},
"entity_type": {
"description": "What the note is on: account or contact.",
"enum": [
"account",
"contact"
],
"title": "Entity Type",
"type": "string"
},
"entity_id": {
"description": "Exact existing account_id or contact_id; resolve it with accounts.search.v2 or contacts.search.v2 first.",
"format": "uuid",
"title": "Entity Id",
"type": "string"
},
"body": {
"description": "Markdown. Say what was learned, not what the model guessed; attribute anything a person told you. To link another account or contact, use the web_url from accounts.search.v2 / contacts.search.v2 verbatim (https://.../accounts/{id} or /contacts/{id}); never hand-build a hivekind:// link.",
"maxLength": 1048576,
"minLength": 1,
"title": "Body",
"type": "string"
},
"occurred_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "When the thing being recorded happened (a meeting, a call). Defaults to now.",
"title": "Occurred At"
},
"in_reply_to_note_id": {
"anyOf": [
{
"format": "uuid",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Append to an existing note on the same entity. This is how an agent corrects or extends a person's note, which it may not edit.",
"title": "In Reply To Note Id"
},
"mentions": {
"default": [],
"description": "Workspace member user ids the note is for.",
"items": {
"format": "uuid",
"type": "string"
},
"maxItems": 50,
"title": "Mentions",
"type": "array"
},
"operation_id": {
"anyOf": [
{
"maxLength": 128,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Your own idempotency key. Retrying with the same id returns the same note instead of a duplicate.",
"title": "Operation Id"
}
},
"required": [
"entity_type",
"entity_id",
"body"
],
"title": "McpMcpPublicNotesCreateInputV2",
"type": "object"
}
Output schema inside the result envelope
{
"$defs": {
"NoteAuthorV1": {
"additionalProperties": false,
"properties": {
"author_type": {
"enum": [
"user",
"agent"
],
"title": "Author Type",
"type": "string"
},
"author_id": {
"description": "The user for a person; the agent run for an agent.",
"maxLength": 64,
"title": "Author Id",
"type": "string"
},
"display_name": {
"maxLength": 255,
"title": "Display Name",
"type": "string"
},
"on_behalf_of_user_id": {
"anyOf": [
{
"maxLength": 64,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "On Behalf Of User Id"
},
"on_behalf_of_name": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "On Behalf Of Name"
},
"source": {
"maxLength": 32,
"title": "Source",
"type": "string"
}
},
"required": [
"author_type",
"author_id",
"display_name",
"source"
],
"title": "NoteAuthorV1",
"type": "object"
},
"NoteV1": {
"additionalProperties": false,
"properties": {
"note_id": {
"maxLength": 64,
"title": "Note Id",
"type": "string"
},
"entity_type": {
"enum": [
"account",
"contact"
],
"title": "Entity Type",
"type": "string"
},
"entity_id": {
"maxLength": 64,
"title": "Entity Id",
"type": "string"
},
"account_id": {
"maxLength": 64,
"title": "Account Id",
"type": "string"
},
"body": {
"maxLength": 1048576,
"title": "Body",
"type": "string"
},
"author": {
"$ref": "#/$defs/NoteAuthorV1"
},
"occurred_at": {
"format": "date-time",
"title": "Occurred At",
"type": "string"
},
"created_at": {
"format": "date-time",
"title": "Created At",
"type": "string"
},
"updated_at": {
"format": "date-time",
"title": "Updated At",
"type": "string"
},
"revision": {
"minimum": 1,
"title": "Revision",
"type": "integer"
},
"in_reply_to_note_id": {
"anyOf": [
{
"maxLength": 64,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "In Reply To Note Id"
},
"mentions": {
"default": [],
"items": {
"type": "string"
},
"maxItems": 50,
"title": "Mentions",
"type": "array"
},
"last_edited_by_type": {
"anyOf": [
{
"enum": [
"user",
"agent"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Last Edited By Type"
},
"can_modify": {
"default": false,
"description": "Whether the calling principal may edit or delete this note. False on a person's note for an agent.",
"title": "Can Modify",
"type": "boolean"
},
"related_entity_type": {
"anyOf": [
{
"enum": [
"account",
"contact"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Set when the note is on the parent account (contact feed) or on a contact (account feed).",
"title": "Related Entity Type"
},
"related_entity_id": {
"anyOf": [
{
"maxLength": 64,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Related Entity Id"
},
"related_entity_name": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Related Entity Name"
},
"web_url": {
"anyOf": [
{
"maxLength": 2048,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Browser link to this note's account or contact (entity_type / entity_id) in the Hivekind app. Use it verbatim whenever you link the record for a person, including inside note bodies; never build a link by hand or use a hivekind:// URI, which is an MCP resource handle, not a page. Null when the server has no app URL configured.",
"title": "Web Url"
}
},
"required": [
"note_id",
"entity_type",
"entity_id",
"account_id",
"body",
"author",
"occurred_at",
"created_at",
"updated_at",
"revision"
],
"title": "NoteV1",
"type": "object"
}
},
"additionalProperties": false,
"description": "V2 result for notes.create.v2; preserves the established validators.",
"properties": {
"note": {
"$ref": "#/$defs/NoteV1"
},
"created": {
"default": true,
"title": "Created",
"type": "boolean"
},
"deduplicated": {
"default": false,
"description": "True when an identical recent note was returned instead of a new one.",
"title": "Deduplicated",
"type": "boolean"
},
"message": {
"anyOf": [
{
"maxLength": 500,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Message"
}
},
"required": [
"note"
],
"title": "PublicNotesCreateResultV2",
"type": "object"
}
Delete a note
notes.delete.v2
Use when: Remove a note an agent wrote, for example after it was superseded.
Avoid when: Never on a person's note; it is refused. Do not delete to "edit" — use notes.update.v2.
Effects: Soft-deletes the note; it leaves every feed but stays in the audit trail.
Cost: No gateway rate is configured. Check the Core workflow preview/quote for downstream charges and final settlement. Gateway rate code: none; downstream billing may apply.
Access: actions:execute. Approval: exact_scope_single_action. A stable operation UUID is required.
Keep the same operation and operation_id when retrying identical work. Reconcile an uncertain result before new work; never replay an old V1 write under a new V2 ID.
Check status, execution_state, error_code, output and evidence/resource references. Queued work is not complete: poll jobs.status.get.v2 in domain.workspace.v2. For read-back verification require read_back_verified=true where returned; reconcile failures without creating another object.
Invocation example using fictional fixtures
{
"tool": "domain.accounts.v2",
"arguments": {
"params": {
"action": "invoke",
"operation": "notes.delete.v2",
"arguments": {
"note_id": "00000000-0000-4000-8000-000000000001"
},
"operation_id": "00000000-0000-4000-8000-000000000003"
}
},
"notice": "Fictional fixture IDs and example text. Resolve real IDs, use returned preview tokens and approve exact side effects before execution. Input validation is not proof of provider readiness or a successful business outcome."
}
Use when: Read what people and agents have recorded on an entity, with full bodies and the revision you need to edit. Filter author_type=user to see only what people wrote.
Avoid when: You need the mixed feed of sends, replies and notes together — that is contacts.timeline.get.v2.
Effects: Read only.
Cost: No gateway credit charge; reads saved workspace data without starting paid provider work. Gateway rate code: none; downstream billing may apply.
Access: accounts:read. Approval: operation authorization. Reads do not need an operation UUID.
Keep the same operation and operation_id when retrying identical work. Reconcile an uncertain result before new work; never replay an old V1 write under a new V2 ID.
Check status, execution_state, error_code, output and evidence/resource references. Queued work is not complete: poll jobs.status.get.v2 in domain.workspace.v2. For read-back verification require read_back_verified=true where returned; reconcile failures without creating another object.
Invocation example using fictional fixtures
{
"tool": "domain.accounts.v2",
"arguments": {
"params": {
"action": "invoke",
"operation": "notes.list.v2",
"arguments": {
"entity_id": "00000000-0000-4000-8000-000000000001",
"entity_type": "account"
},
"operation_id": "00000000-0000-4000-8000-000000000003"
}
},
"notice": "Fictional fixture IDs and example text. Resolve real IDs, use returned preview tokens and approve exact side effects before execution. Input validation is not proof of provider readiness or a successful business outcome."
}
Input schema: fields, defaults and constraints
{
"additionalProperties": false,
"properties": {
"entity_type": {
"description": "What the note is on: account or contact.",
"enum": [
"account",
"contact"
],
"title": "Entity Type",
"type": "string"
},
"entity_id": {
"description": "Exact existing account_id or contact_id; resolve it with accounts.search.v2 or contacts.search.v2 first.",
"format": "uuid",
"title": "Entity Id",
"type": "string"
},
"limit": {
"default": 50,
"description": "Maximum number of records to return in this page.",
"maximum": 100,
"minimum": 1,
"title": "Limit",
"type": "integer"
},
"before": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Page backwards: notes that occurred before this time. Use next_cursor.",
"title": "Before"
},
"author_type": {
"anyOf": [
{
"enum": [
"user",
"agent"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Only notes by people (user) or by agents (agent).",
"title": "Author Type"
},
"include_related": {
"default": true,
"description": "Also return the account's notes on a contact feed, and contacts' notes on an account feed.",
"title": "Include Related",
"type": "boolean"
}
},
"required": [
"entity_type",
"entity_id"
],
"title": "McpPublicNotesListInputV2",
"type": "object"
}
Output schema inside the result envelope
{
"$defs": {
"NoteAuthorV1": {
"additionalProperties": false,
"properties": {
"author_type": {
"enum": [
"user",
"agent"
],
"title": "Author Type",
"type": "string"
},
"author_id": {
"description": "The user for a person; the agent run for an agent.",
"maxLength": 64,
"title": "Author Id",
"type": "string"
},
"display_name": {
"maxLength": 255,
"title": "Display Name",
"type": "string"
},
"on_behalf_of_user_id": {
"anyOf": [
{
"maxLength": 64,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "On Behalf Of User Id"
},
"on_behalf_of_name": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "On Behalf Of Name"
},
"source": {
"maxLength": 32,
"title": "Source",
"type": "string"
}
},
"required": [
"author_type",
"author_id",
"display_name",
"source"
],
"title": "NoteAuthorV1",
"type": "object"
},
"NoteV1": {
"additionalProperties": false,
"properties": {
"note_id": {
"maxLength": 64,
"title": "Note Id",
"type": "string"
},
"entity_type": {
"enum": [
"account",
"contact"
],
"title": "Entity Type",
"type": "string"
},
"entity_id": {
"maxLength": 64,
"title": "Entity Id",
"type": "string"
},
"account_id": {
"maxLength": 64,
"title": "Account Id",
"type": "string"
},
"body": {
"maxLength": 1048576,
"title": "Body",
"type": "string"
},
"author": {
"$ref": "#/$defs/NoteAuthorV1"
},
"occurred_at": {
"format": "date-time",
"title": "Occurred At",
"type": "string"
},
"created_at": {
"format": "date-time",
"title": "Created At",
"type": "string"
},
"updated_at": {
"format": "date-time",
"title": "Updated At",
"type": "string"
},
"revision": {
"minimum": 1,
"title": "Revision",
"type": "integer"
},
"in_reply_to_note_id": {
"anyOf": [
{
"maxLength": 64,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "In Reply To Note Id"
},
"mentions": {
"default": [],
"items": {
"type": "string"
},
"maxItems": 50,
"title": "Mentions",
"type": "array"
},
"last_edited_by_type": {
"anyOf": [
{
"enum": [
"user",
"agent"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Last Edited By Type"
},
"can_modify": {
"default": false,
"description": "Whether the calling principal may edit or delete this note. False on a person's note for an agent.",
"title": "Can Modify",
"type": "boolean"
},
"related_entity_type": {
"anyOf": [
{
"enum": [
"account",
"contact"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Set when the note is on the parent account (contact feed) or on a contact (account feed).",
"title": "Related Entity Type"
},
"related_entity_id": {
"anyOf": [
{
"maxLength": 64,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Related Entity Id"
},
"related_entity_name": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Related Entity Name"
},
"web_url": {
"anyOf": [
{
"maxLength": 2048,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Browser link to this note's account or contact (entity_type / entity_id) in the Hivekind app. Use it verbatim whenever you link the record for a person, including inside note bodies; never build a link by hand or use a hivekind:// URI, which is an MCP resource handle, not a page. Null when the server has no app URL configured.",
"title": "Web Url"
}
},
"required": [
"note_id",
"entity_type",
"entity_id",
"account_id",
"body",
"author",
"occurred_at",
"created_at",
"updated_at",
"revision"
],
"title": "NoteV1",
"type": "object"
}
},
"additionalProperties": false,
"description": "V2 result for notes.list.v2; preserves the established validators.",
"properties": {
"entity_type": {
"enum": [
"account",
"contact"
],
"title": "Entity Type",
"type": "string"
},
"entity_id": {
"maxLength": 64,
"title": "Entity Id",
"type": "string"
},
"notes": {
"default": [],
"items": {
"$ref": "#/$defs/NoteV1"
},
"maxItems": 100,
"title": "Notes",
"type": "array"
},
"next_cursor": {
"anyOf": [
{
"maxLength": 64,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Next Cursor"
},
"total": {
"default": 0,
"minimum": 0,
"title": "Total",
"type": "integer"
}
},
"required": [
"entity_type",
"entity_id"
],
"title": "PublicNotesListResultV2",
"type": "object"
}
Edit a note
notes.update.v2
Use when: Replace the body of a note an agent wrote. Read it with notes.list.v2 first and pass its revision as if_revision.
Avoid when: Never on a person's note — that is refused with agent_cannot_edit_user_note; reply with notes.create.v2 instead. Do not retry a revision_conflict without re-reading.
Effects: Bumps the note's revision and banks the previous body. Reversible by editing again.
Cost: No gateway rate is configured. Check the Core workflow preview/quote for downstream charges and final settlement. Gateway rate code: none; downstream billing may apply.
Access: actions:execute. Approval: exact_scope_single_action. A stable operation UUID is required.
Keep the same operation and operation_id when retrying identical work. Reconcile an uncertain result before new work; never replay an old V1 write under a new V2 ID.
Check status, execution_state, error_code, output and evidence/resource references. Queued work is not complete: poll jobs.status.get.v2 in domain.workspace.v2. For read-back verification require read_back_verified=true where returned; reconcile failures without creating another object.
Invocation example using fictional fixtures
{
"tool": "domain.accounts.v2",
"arguments": {
"params": {
"action": "invoke",
"operation": "notes.update.v2",
"arguments": {
"body": "Example body",
"if_revision": 1,
"note_id": "00000000-0000-4000-8000-000000000001"
},
"operation_id": "00000000-0000-4000-8000-000000000003"
}
},
"notice": "Fictional fixture IDs and example text. Resolve real IDs, use returned preview tokens and approve exact side effects before execution. Input validation is not proof of provider readiness or a successful business outcome."
}
Input schema: fields, defaults and constraints
{
"additionalProperties": false,
"properties": {
"action_proposal_id": {
"anyOf": [
{
"format": "uuid",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional. Hivekind fills this from the MCP consent grant.",
"title": "Action Proposal Id"
},
"note_id": {
"description": "Exact note id from notes.list.v2 or a prior create.",
"format": "uuid",
"title": "Note Id",
"type": "string"
},
"body": {
"description": "The full replacement body.",
"maxLength": 1048576,
"minLength": 1,
"title": "Body",
"type": "string"
},
"if_revision": {
"description": "The revision you read. A mismatch is refused with the current revision; re-read and retry.",
"minimum": 1,
"title": "If Revision",
"type": "integer"
}
},
"required": [
"note_id",
"body",
"if_revision"
],
"title": "McpMcpPublicNotesUpdateInputV2",
"type": "object"
}
Output schema inside the result envelope
{
"$defs": {
"NoteAuthorV1": {
"additionalProperties": false,
"properties": {
"author_type": {
"enum": [
"user",
"agent"
],
"title": "Author Type",
"type": "string"
},
"author_id": {
"description": "The user for a person; the agent run for an agent.",
"maxLength": 64,
"title": "Author Id",
"type": "string"
},
"display_name": {
"maxLength": 255,
"title": "Display Name",
"type": "string"
},
"on_behalf_of_user_id": {
"anyOf": [
{
"maxLength": 64,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "On Behalf Of User Id"
},
"on_behalf_of_name": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "On Behalf Of Name"
},
"source": {
"maxLength": 32,
"title": "Source",
"type": "string"
}
},
"required": [
"author_type",
"author_id",
"display_name",
"source"
],
"title": "NoteAuthorV1",
"type": "object"
},
"NoteV1": {
"additionalProperties": false,
"properties": {
"note_id": {
"maxLength": 64,
"title": "Note Id",
"type": "string"
},
"entity_type": {
"enum": [
"account",
"contact"
],
"title": "Entity Type",
"type": "string"
},
"entity_id": {
"maxLength": 64,
"title": "Entity Id",
"type": "string"
},
"account_id": {
"maxLength": 64,
"title": "Account Id",
"type": "string"
},
"body": {
"maxLength": 1048576,
"title": "Body",
"type": "string"
},
"author": {
"$ref": "#/$defs/NoteAuthorV1"
},
"occurred_at": {
"format": "date-time",
"title": "Occurred At",
"type": "string"
},
"created_at": {
"format": "date-time",
"title": "Created At",
"type": "string"
},
"updated_at": {
"format": "date-time",
"title": "Updated At",
"type": "string"
},
"revision": {
"minimum": 1,
"title": "Revision",
"type": "integer"
},
"in_reply_to_note_id": {
"anyOf": [
{
"maxLength": 64,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "In Reply To Note Id"
},
"mentions": {
"default": [],
"items": {
"type": "string"
},
"maxItems": 50,
"title": "Mentions",
"type": "array"
},
"last_edited_by_type": {
"anyOf": [
{
"enum": [
"user",
"agent"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Last Edited By Type"
},
"can_modify": {
"default": false,
"description": "Whether the calling principal may edit or delete this note. False on a person's note for an agent.",
"title": "Can Modify",
"type": "boolean"
},
"related_entity_type": {
"anyOf": [
{
"enum": [
"account",
"contact"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Set when the note is on the parent account (contact feed) or on a contact (account feed).",
"title": "Related Entity Type"
},
"related_entity_id": {
"anyOf": [
{
"maxLength": 64,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Related Entity Id"
},
"related_entity_name": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Related Entity Name"
},
"web_url": {
"anyOf": [
{
"maxLength": 2048,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Browser link to this note's account or contact (entity_type / entity_id) in the Hivekind app. Use it verbatim whenever you link the record for a person, including inside note bodies; never build a link by hand or use a hivekind:// URI, which is an MCP resource handle, not a page. Null when the server has no app URL configured.",
"title": "Web Url"
}
},
"required": [
"note_id",
"entity_type",
"entity_id",
"account_id",
"body",
"author",
"occurred_at",
"created_at",
"updated_at",
"revision"
],
"title": "NoteV1",
"type": "object"
}
},
"additionalProperties": false,
"description": "V2 result for notes.update.v2; preserves the established validators.",
"properties": {
"note": {
"$ref": "#/$defs/NoteV1"
},
"created": {
"default": true,
"title": "Created",
"type": "boolean"
},
"deduplicated": {
"default": false,
"description": "True when an identical recent note was returned instead of a new one.",
"title": "Deduplicated",
"type": "boolean"
},
"message": {
"anyOf": [
{
"maxLength": 500,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Message"
}
},
"required": [
"note"
],
"title": "PublicNotesUpdateResultV2",
"type": "object"
}
Preview a prospect import
prospects.import.preview.v2
Use when: Show what a list of people would land as in Hive Base, including which accounts already exist and which would be created. Send the file whole; the response's column_policy names any columns that look like source-system noise.
Avoid when: Do not use this for an event guest list — stage that with events.import.preview.v2.
Effects: Writes nothing. Returns an import_token that prospects.import.start.v2 can commit.
Cost: No gateway rate is configured. Check the Core workflow preview/quote for downstream charges and final settlement. Gateway rate code: none; downstream billing may apply.
Access: runs:create. Approval: operation authorization. A stable operation UUID is required.
Keep the same operation and operation_id when retrying identical work. Reconcile an uncertain result before new work; never replay an old V1 write under a new V2 ID.
Check status, execution_state, error_code, output and evidence/resource references. Queued work is not complete: poll jobs.status.get.v2 in domain.workspace.v2. For read-back verification require read_back_verified=true where returned; reconcile failures without creating another object.
Invocation example using fictional fixtures
{
"tool": "domain.accounts.v2",
"arguments": {
"params": {
"action": "invoke",
"operation": "prospects.import.preview.v2",
"arguments": {
"contacts": [
{
"company_domain": "example.com",
"company_name": "Example company",
"email": "person@example.com",
"first_name": "Example",
"last_name": "Person"
}
]
},
"operation_id": "00000000-0000-4000-8000-000000000003"
}
},
"notice": "Fictional fixture IDs and example text. Resolve real IDs, use returned preview tokens and approve exact side effects before execution. Input validation is not proof of provider readiness or a successful business outcome."
}
Input schema: fields, defaults and constraints
{
"$defs": {
"ProspectContactInputV1": {
"additionalProperties": false,
"properties": {
"first_name": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "First Name"
},
"last_name": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Last Name"
},
"email": {
"anyOf": [
{
"maxLength": 320,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Email"
},
"title": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Title"
},
"linkedin_url": {
"anyOf": [
{
"maxLength": 500,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Linkedin Url"
},
"phone": {
"anyOf": [
{
"maxLength": 64,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Phone"
},
"company_name": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Company Name"
},
"company_domain": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Company Domain"
},
"owner_email": {
"anyOf": [
{
"maxLength": 320,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Workspace member who should own the contact's account.",
"title": "Owner Email"
}
},
"title": "ProspectContactInputV1",
"type": "object"
}
},
"additionalProperties": false,
"properties": {
"csv_text": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Verbatim contents of a CSV the caller holds. Send the file exactly as it is: never retype values, reorder or drop rows, summarise, or leave columns out. The server maps arbitrary column layouts itself, and the preview reports which columns it reads as source-system noise, and why, in column_policy. Decide there with the user -- not here.",
"title": "Csv Text"
},
"exclude_columns": {
"default": [],
"description": "Source columns to leave out, after the user agreed to it. Leave empty on a first preview. Naming a column the server protects, or one that is mapped to a canonical field, fails the whole call.",
"items": {
"type": "string"
},
"maxItems": 200,
"title": "Exclude Columns",
"type": "array"
},
"keep_columns": {
"default": [],
"description": "Source columns to retain whatever the server makes of them. Use it when the user says a column matters. Outranks exclude_columns.",
"items": {
"type": "string"
},
"maxItems": 200,
"title": "Keep Columns",
"type": "array"
},
"tags": {
"anyOf": [
{
"items": {
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"maxItems": 10,
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Account tags (1-64 characters each, at most 10) added to every account this import creates or matches -- existing accounts get the tag and nothing else on them changes. Matched case-insensitively against existing tags; resolve them with accounts.tags.list.v2 first. The preview's import_token locks these in: omit tags on the commit to reuse them, and a different list is refused. Separate from the source badge.",
"title": "Tags"
},
"contacts": {
"default": [],
"description": "Contacts used by the public prospects import preview input v2 operation.",
"items": {
"$ref": "#/$defs/ProspectContactInputV1"
},
"maxItems": 2000,
"title": "Contacts",
"type": "array"
},
"assign_to_user_id": {
"anyOf": [
{
"format": "uuid",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Fallback owner for rows that carry no owner of their own.",
"title": "Assign To User Id"
},
"overwrite_conflicting_owners": {
"default": false,
"description": "Overwrite conflicting owners used by the public prospects import preview input v2 operation.",
"title": "Overwrite Conflicting Owners",
"type": "boolean"
}
},
"title": "McpPublicProspectsImportPreviewInputV2",
"type": "object"
}
Output schema inside the result envelope
{
"$defs": {
"ExcludedColumnV1": {
"additionalProperties": false,
"description": "One source column the server left out, or proposes leaving out.",
"properties": {
"column": {
"maxLength": 255,
"title": "Column",
"type": "string"
},
"reason": {
"enum": [
"empty_column",
"opaque_source_id",
"payment_metadata",
"source_system_link",
"caller_selected"
],
"title": "Reason",
"type": "string"
},
"detail": {
"default": "",
"maxLength": 500,
"title": "Detail",
"type": "string"
}
},
"required": [
"column",
"reason"
],
"title": "ExcludedColumnV1",
"type": "object"
},
"ImportColumnPolicyV1": {
"additionalProperties": false,
"description": "What the server made of the file's columns.\n\n``applied`` is the field that matters. False -- the default for any preview\nthat was not given a selection -- means ``excluded_columns`` is a proposal\nand every column was still imported. Show it to the user, take their answer,\nand send it back as ``exclude_columns`` if they agree. Never act on it alone.",
"properties": {
"version": {
"default": 1,
"title": "Version",
"type": "integer"
},
"applied": {
"default": false,
"title": "Applied",
"type": "boolean"
},
"retained_columns": {
"default": [],
"items": {
"type": "string"
},
"title": "Retained Columns",
"type": "array"
},
"excluded_columns": {
"default": [],
"items": {
"$ref": "#/$defs/ExcludedColumnV1"
},
"title": "Excluded Columns",
"type": "array"
}
},
"title": "ImportColumnPolicyV1",
"type": "object"
},
"ImportRowErrorV1": {
"additionalProperties": false,
"description": "One row the parser could not use. Row numbers are 1-based and header-aware.",
"properties": {
"row": {
"minimum": 1,
"title": "Row",
"type": "integer"
},
"reason": {
"maxLength": 500,
"minLength": 1,
"title": "Reason",
"type": "string"
}
},
"required": [
"row",
"reason"
],
"title": "ImportRowErrorV1",
"type": "object"
},
"JsonValue": {}
},
"additionalProperties": false,
"description": "V2 result for prospects.import.preview.v2; preserves the established validators.",
"properties": {
"column_policy": {
"anyOf": [
{
"$ref": "#/$defs/ImportColumnPolicyV1"
},
{
"type": "null"
}
],
"default": null,
"description": "What the server made of the file's columns. When applied is false this is a proposal only and nothing was left out."
},
"import_token": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Pass to the matching commit tool to reuse exactly these rows. Null when no cache backend was reachable -- resend the data instead.",
"title": "Import Token"
},
"rows_parsed": {
"default": 0,
"minimum": 0,
"title": "Rows Parsed",
"type": "integer"
},
"rows_skipped": {
"default": 0,
"minimum": 0,
"title": "Rows Skipped",
"type": "integer"
},
"rows_without_person": {
"default": 0,
"description": "Company-only rows. They are skipped here -- import them with accounts.import.preview.v2 instead.",
"minimum": 0,
"title": "Rows Without Person",
"type": "integer"
},
"column_mapping": {
"additionalProperties": {
"type": "string"
},
"title": "Column Mapping",
"type": "object"
},
"parse_errors": {
"default": [],
"items": {
"$ref": "#/$defs/ImportRowErrorV1"
},
"maxItems": 50,
"title": "Parse Errors",
"type": "array"
},
"matches_existing_accounts": {
"default": 0,
"minimum": 0,
"title": "Matches Existing Accounts",
"type": "integer"
},
"matches_existing_contacts": {
"default": 0,
"minimum": 0,
"title": "Matches Existing Contacts",
"type": "integer"
},
"new_companies": {
"default": 0,
"minimum": 0,
"title": "New Companies",
"type": "integer"
},
"owners_to_assign": {
"default": 0,
"minimum": 0,
"title": "Owners To Assign",
"type": "integer"
},
"owner_conflicts": {
"default": 0,
"minimum": 0,
"title": "Owner Conflicts",
"type": "integer"
},
"sample_rows": {
"default": [],
"items": {
"additionalProperties": {
"$ref": "#/$defs/JsonValue"
},
"type": "object"
},
"maxItems": 5,
"title": "Sample Rows",
"type": "array"
},
"tags": {
"default": [],
"description": "Account tags the import_token is locked to.",
"items": {
"type": "string"
},
"title": "Tags",
"type": "array"
},
"accounts_to_tag": {
"default": 0,
"description": "Accounts the commit would tag: matches_existing_accounts plus new_companies. Zero when no tags were given.",
"minimum": 0,
"title": "Accounts To Tag",
"type": "integer"
}
},
"title": "PublicProspectsImportPreviewResultV2",
"type": "object"
}
Import prospects
prospects.import.start.v2
Use when: Create contacts in Hive Base, auto-creating their accounts. For loose prospects that belong to no event. To commit a preview, send only import_token (with action_proposal_id): a commit with import_token takes no contacts and no csv_text, because the token already carries the previewed rows. Without a token, send contacts or csv_text directly.
Avoid when: Do not use this for a company-only list with no people — that is accounts.import.start.v2.
Effects: Creates contacts and accounts, badged with the import source when you pass source (name, kind workshop/event/webinar/list/other; the id comes back as source_id). Sends nothing. Returns created_contact_ids, updated_contact_ids, matched_account_ids (every account the contacts sit on, existing included) and account_ids (only the new accounts).
Cost: No gateway rate is configured. Check the Core workflow preview/quote for downstream charges and final settlement. Gateway rate code: none; downstream billing may apply.
Access: actions:execute. Approval: exact_scope_single_action. A stable operation UUID is required.
Keep the same operation and operation_id when retrying identical work. Reconcile an uncertain result before new work; never replay an old V1 write under a new V2 ID.
Check status, execution_state, error_code, output and evidence/resource references. Queued work is not complete: poll jobs.status.get.v2 in domain.workspace.v2. For read-back verification require read_back_verified=true where returned; reconcile failures without creating another object.
Invocation example using fictional fixtures
{
"tool": "domain.accounts.v2",
"arguments": {
"params": {
"action": "invoke",
"operation": "prospects.import.start.v2",
"arguments": {
"import_token": "use-the-exact-token-from-the-approved-preview"
},
"operation_id": "00000000-0000-4000-8000-000000000003"
}
},
"notice": "Fictional fixture IDs and example text. Resolve real IDs, use returned preview tokens and approve exact side effects before execution. Input validation is not proof of provider readiness or a successful business outcome."
}
Input schema: fields, defaults and constraints
{
"$defs": {
"ImportSourceInputV1": {
"additionalProperties": false,
"description": "Where this list came from. Every record the import creates or matches is badged with it.",
"properties": {
"source_id": {
"anyOf": [
{
"format": "uuid",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Add to an existing source instead of creating one.",
"title": "Source Id"
},
"name": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "New source name, e.g. 'AI for CFOs workshop'. Omit to name it after the file.",
"title": "Name"
},
"kind": {
"default": "list",
"enum": [
"workshop",
"event",
"webinar",
"list",
"other"
],
"title": "Kind",
"type": "string"
},
"occurred_on": {
"anyOf": [
{
"format": "date",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Occurred On"
},
"details": {
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"type": "null"
}
]
},
"description": "Location, host, link, notes. Flat: at most 20 keys (each up to 64 characters), values are text up to 1000 characters, numbers, booleans or null. No nested objects or lists.",
"title": "Details",
"type": "object"
}
},
"title": "ImportSourceInputV1",
"type": "object"
},
"ProspectContactInputV1": {
"additionalProperties": false,
"properties": {
"first_name": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "First Name"
},
"last_name": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Last Name"
},
"email": {
"anyOf": [
{
"maxLength": 320,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Email"
},
"title": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Title"
},
"linkedin_url": {
"anyOf": [
{
"maxLength": 500,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Linkedin Url"
},
"phone": {
"anyOf": [
{
"maxLength": 64,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Phone"
},
"company_name": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Company Name"
},
"company_domain": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Company Domain"
},
"owner_email": {
"anyOf": [
{
"maxLength": 320,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Workspace member who should own the contact's account.",
"title": "Owner Email"
}
},
"title": "ProspectContactInputV1",
"type": "object"
}
},
"additionalProperties": false,
"properties": {
"csv_text": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Verbatim contents of a CSV the caller holds. Send the file exactly as it is: never retype values, reorder or drop rows, summarise, or leave columns out. The server maps arbitrary column layouts itself, and the preview reports which columns it reads as source-system noise, and why, in column_policy. Decide there with the user -- not here.",
"title": "Csv Text"
},
"exclude_columns": {
"default": [],
"description": "Source columns to leave out, after the user agreed to it. Leave empty on a first preview. Naming a column the server protects, or one that is mapped to a canonical field, fails the whole call.",
"items": {
"type": "string"
},
"maxItems": 200,
"title": "Exclude Columns",
"type": "array"
},
"keep_columns": {
"default": [],
"description": "Source columns to retain whatever the server makes of them. Use it when the user says a column matters. Outranks exclude_columns.",
"items": {
"type": "string"
},
"maxItems": 200,
"title": "Keep Columns",
"type": "array"
},
"tags": {
"anyOf": [
{
"items": {
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"maxItems": 10,
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Account tags (1-64 characters each, at most 10) added to every account this import creates or matches -- existing accounts get the tag and nothing else on them changes. Matched case-insensitively against existing tags; resolve them with accounts.tags.list.v2 first. The preview's import_token locks these in: omit tags on the commit to reuse them, and a different list is refused. Separate from the source badge.",
"title": "Tags"
},
"contacts": {
"default": [],
"description": "Contacts used by the public prospects import start input v2 operation.",
"items": {
"$ref": "#/$defs/ProspectContactInputV1"
},
"maxItems": 2000,
"title": "Contacts",
"type": "array"
},
"assign_to_user_id": {
"anyOf": [
{
"format": "uuid",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Fallback owner for rows that carry no owner of their own.",
"title": "Assign To User Id"
},
"overwrite_conflicting_owners": {
"default": false,
"description": "Overwrite conflicting owners used by the public prospects import start input v2 operation.",
"title": "Overwrite Conflicting Owners",
"type": "boolean"
},
"source": {
"anyOf": [
{
"$ref": "#/$defs/ImportSourceInputV1"
},
{
"type": "null"
}
],
"default": null,
"description": "Label this list so every account and contact it creates or matches is badged with where it came from (workshop, event, webinar, list). The id comes back as source_id on the result."
},
"action_proposal_id": {
"anyOf": [
{
"format": "uuid",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional. Hivekind fills this from the MCP consent grant.",
"title": "Action Proposal Id"
},
"import_token": {
"anyOf": [
{
"maxLength": 255,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Import token used by the public prospects import start input v2 operation.",
"title": "Import Token"
}
},
"title": "McpMcpPublicProspectsImportStartInputV2",
"type": "object"
}
Output schema inside the result envelope
{
"additionalProperties": false,
"description": "V2 result for prospects.import.start.v2; preserves the established validators.",
"properties": {
"source_id": {
"anyOf": [
{
"format": "uuid",
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Source the imported records were badged with.",
"title": "Source Id"
},
"contacts_created": {
"default": 0,
"minimum": 0,
"title": "Contacts Created",
"type": "integer"
},
"contacts_updated": {
"default": 0,
"minimum": 0,
"title": "Contacts Updated",
"type": "integer"
},
"contacts_skipped": {
"default": 0,
"minimum": 0,
"title": "Contacts Skipped",
"type": "integer"
},
"accounts_created": {
"default": 0,
"minimum": 0,
"title": "Accounts Created",
"type": "integer"
},
"account_ids": {
"default": [],
"description": "Accounts this import created. Pass them to icp.grading.start.v2 as account_ids to grade exactly what was just added, rather than approximating with only_unscored.",
"items": {
"format": "uuid",
"type": "string"
},
"maxItems": 500,
"title": "Account Ids",
"type": "array"
},
"created_contact_ids": {
"default": [],
"description": "Contacts this import created, in row order.",
"items": {
"format": "uuid",
"type": "string"
},
"maxItems": 200,
"title": "Created Contact Ids",
"type": "array"
},
"updated_contact_ids": {
"default": [],
"description": "Existing contacts this import updated in place, in row order. A contact matched by email stays on its own account.",
"items": {
"format": "uuid",
"type": "string"
},
"maxItems": 200,
"title": "Updated Contact Ids",
"type": "array"
},
"matched_account_ids": {
"default": [],
"description": "Every account an imported contact now sits on, existing or newly created. account_ids is only the new ones.",
"items": {
"format": "uuid",
"type": "string"
},
"maxItems": 200,
"title": "Matched Account Ids",
"type": "array"
},
"ids_truncated": {
"default": false,
"description": "True when a list above was cut at 200; page the rest with contacts.search.v2.",
"title": "Ids Truncated",
"type": "boolean"
},
"total_processed": {
"default": 0,
"minimum": 0,
"title": "Total Processed",
"type": "integer"
},
"errors": {
"default": [],
"items": {
"type": "string"
},
"maxItems": 50,
"title": "Errors",
"type": "array"
},
"tags": {
"default": [],
"description": "Account tags added to every account this import created or matched.",
"items": {
"type": "string"
},
"title": "Tags",
"type": "array"
}
},
"title": "PublicProspectsImportStartResultV2",
"type": "object"
}