Tool reference

Hyperdex exposes 20 MCP tools, 2 resources and 3 prompts. This page is generated from the live server, so it always matches what your agent sees.

Your agent chooses tools by itself; you rarely need to name them. Every tool returns JSON. Errors are returned as { "error": { "code", "message", "hint" } }; see errors.

Read: whoami, search, get_briefing, get_history, query_pipeline
Write: upsert_entity, update_entity, link_entities, log_activity
Tasks: create_task, list_tasks, claim_task, complete_task
Approvals: propose_action, list_proposals, resolve_proposal
Clean-up: archive_entity, merge_entities
Admin: manage_agents, configure_workspace
Resources and prompts

Read

Find and understand records. All need crm:read.

whoami

Who am I

crm:readread-only

Returns your workspace, agent identity, scopes, the workspace's pipeline stages and record counts. Call once at the start of a session.

No parameters.

search

Search the CRM

crm:readread-only

Find people, organizations, deals and logged activities by name, email, domain, keywords or meaning. Tolerates typos and partial names. Returns ids with one-line summaries; follow up with get_briefing for detail. Search before creating records to avoid duplicates.

Parameter	Type	Description
`query`required	string	Natural-language or keyword query, e.g. 'jane acme', 'jane@acme.com', 'who raised pricing concerns'up to 500 characters
`types`	"person" \| "organization" \| "deal" \| "activity"[]	Restrict result types. Default: all
`include_archived`	boolean	default false
`limit`	integer	1 to 25, default 10

get_briefing

Get briefing

crm:readread-only

Everything you need to act on one person, organization or deal, condensed to fit a token budget: core fields, summary, relationships, open deals, open tasks and the most recent activity. Includes `version`, which update_entity requires. Use get_history for older activity.

Parameter	Type	Description
`id`required	id	Record id exactly as returned by another tool
`max_tokens`	integer	Approximate size budget for the response300 to 8000, default 1500
`include_provenance`	boolean	Include who/what set each field, with confidencedefault false

get_history

Get activity history

crm:readread-only

Paginated timeline of activity for one entity, newest first. Use after get_briefing when you need older or full-length activity.

Parameter	Type	Description
`entity_id`required	id	Record id exactly as returned by another tool
`kinds`	"email" \| "call" \| "meeting" \| "note" \| "message" \| "status_change" \| "field_change" \| "task" \| "system"[]
`since`	date-time	Only activity at or after this time
`include_content`	boolean	Full content; false returns titles and excerpts onlydefault true
`limit`	integer	1 to 50, default 20
`cursor`	string	next_cursor from a previous call

query_pipeline

Query the deal pipeline

crm:readread-only

Filter and summarize deals: totals per stage plus matching deals. Use stalled_days to find deals with no logged interaction recently. Open deals only unless include_closed is true.

Parameter	Type	Description
`stages`	string[]	Only these stages (see whoami for valid stages)
`include_closed`	boolean	default false
`organization_id`	id	Record id exactly as returned by another tool
`min_amount`	number	at least 0
`max_amount`	number	at least 0
`currency`	string
`close_after`	date
`close_before`	date
`stalled_days`	integer	No email/call/meeting/note/message logged in this many days1 to 3650
`sort`	"amount" \| "close_date" \| "last_activity" \| "updated"	default "close_date"
`limit`	integer	1 to 100, default 25
`offset`	integer	0 to 9007199254740991, default 0

Write

Add and change records and log what happened. All need crm:write.

upsert_entity

Create or match a person, organization or deal

crm:writesafe to retry

Creates a record, or matches an existing one instead of duplicating it. People are matched by email, organizations by domain, deals by exact name.

Without an email/domain, similar names are returned as status "possible_duplicates" and nothing is written: then call again with match_id (to update that record) or create_anyway: true.

On a match, on_match decides what happens: "fill_empty" (default) only fills blank fields and reports conflicting values in skipped_fields; "overwrite" replaces them.

Pass organization_id to link a person (works_at) or deal (deal_for) to an organization.

Parameter	Type	Description
`name`required	string	up to 500 characters
`email`	string	person onlyup to 320 characters
`phone`	string	person onlyup to 50 characters
`title`	string	person only: job titleup to 200 characters
`domain`	string	organization only: bare domain, e.g. acme.comup to 253 characters
`stage`	string	deal only: one of the workspace pipeline stagesup to 50 characters
`amount`	number	deal onlyat least 0
`currency`	string	deal only: ISO 4217, e.g. USD
`close_date`	date	deal only: expected close date YYYY-MM-DD
`summary`	string	A short paragraph describing this record; keep it currentup to 4000 characters
`kind`required	"person" \| "organization" \| "deal"
`tags`	string[]	up to 50 items
`attributes`	object	Free-form fields that have no typed column, e.g. {linkedin_url, industry, employee_count}
`organization_id`	id	person/deal: the organization they belong to
`match_id`	id	Update this specific existing record instead of matching automatically
`create_anyway`	boolean	Create even if similar names existdefault false
`on_match`	"fill_empty" \| "overwrite"	default "fill_empty"
`source`	object	Provenance of the information. Always provide it when the data came from somewhere specific.
`source.type`required	string	Where the information came from, e.g. email, call_transcript, website, linkedin, user, inferenceup to 50 characters
`source.ref`	string	Identifier in the source system, e.g. a message idup to 500 characters
`source.url`	string	up to 2000 characters
`confidence`	number	How sure you are, 0..1. Use < 0.5 for guesses and inferences.0 to 1, default 0.8
`idempotency_key`	string	Optional. Retrying with the same key returns the original result instead of writing twice.up to 200 characters

update_entity

Update a record

crm:write

Changes fields on an existing record. Requires expected_version (from get_briefing or a previous write); if another agent changed the record first you get VERSION_CONFLICT and should re-read before retrying. Set a field to null to clear it. Stage changes are logged as status_change events.

Parameter	Type	Description
`id`required	id	Record id exactly as returned by another tool
`expected_version`required	integer	1 to 9007199254740991
`set`	object	Fields to change; null clears a fielddefault {}
`set.name`	string	up to 500 characters
`set.email`	string \| null
`set.phone`	string \| null
`set.title`	string \| null
`set.domain`	string \| null
`set.stage`	string	up to 50 characters
`set.amount`	number \| null
`set.currency`	string \| null
`set.close_date`	date \| null
`set.summary`	string \| null
`attributes`	object	Keys to set; a null value deletes the key
`add_tags`	string[]	up to 50 items
`remove_tags`	string[]	up to 50 items
`verified`	boolean	true if you confirmed these values from an authoritative source
`source`	object	Provenance of the information. Always provide it when the data came from somewhere specific.
`source.type`required	string	Where the information came from, e.g. email, call_transcript, website, linkedin, user, inferenceup to 50 characters
`source.ref`	string	Identifier in the source system, e.g. a message idup to 500 characters
`source.url`	string	up to 2000 characters
`confidence`	number	How sure you are, 0..1. Use < 0.5 for guesses and inferences.0 to 1, default 0.8

link_entities

Link or unlink two records

crm:writesafe to retry

Creates (or with remove: true deletes) a directed relationship. Use snake_case relations, e.g. works_at (person→org), reports_to (person→person), introduced_by, deal_for (deal→org), contact_on (person→deal), partner_of, competitor_of, subsidiary_of.

Parameter	Type	Description
`from_id`required	id	Record id exactly as returned by another tool
`to_id`required	id	Record id exactly as returned by another tool
`relation`required	string
`attributes`	object	e.g. {role: 'economic buyer'}
`remove`	boolean	default false
`source`	object	Provenance of the information. Always provide it when the data came from somewhere specific.
`source.type`required	string	Where the information came from, e.g. email, call_transcript, website, linkedin, user, inferenceup to 50 characters
`source.ref`	string	Identifier in the source system, e.g. a message idup to 500 characters
`source.url`	string	up to 2000 characters

log_activity

Log an interaction

crm:writesafe to retry

Records an email, call, meeting, note or message against one or more records (e.g. the person, their organization and the deal). This is the CRM's memory: log every meaningful interaction, with the source. Optionally creates follow-up tasks in the same call. Use an idempotency_key such as the email message id so retries never double-log.

Parameter	Type	Description
`kind`required	"email" \| "call" \| "meeting" \| "note" \| "message"
`entity_ids`required	id[]	up to 20 items
`content`required	string	What happened: the email body, call notes, transcript excerpt or summaryup to 100000 characters
`title`	string	One line, e.g. the email subject or 'Discovery call'up to 500 characters
`direction`	"inbound" \| "outbound" \| "internal"
`occurred_at`	date-time	When it happened. Default: now
`data`	object	Structured extras, e.g. {participants: [...], duration_minutes: 30, sentiment: 'positive'}
`source`	object	Provenance of the information. Always provide it when the data came from somewhere specific.
`source.type`required	string	Where the information came from, e.g. email, call_transcript, website, linkedin, user, inferenceup to 50 characters
`source.ref`	string	Identifier in the source system, e.g. a message idup to 500 characters
`source.url`	string	up to 2000 characters
`follow_ups`	object[]	up to 10 items
`follow_ups[].title`required	string	up to 500 characters
`follow_ups[].description`	string	up to 10000 characters
`follow_ups[].due_at`	date-time
`follow_ups[].priority`	integer	1 = most urgent1 to 5, default 3
`follow_ups[].entity_id`	id	Defaults to the first entity of the activity
`idempotency_key`	string	Optional. Retrying with the same key returns the original result instead of writing twice.up to 200 characters

Tasks

A shared work queue with leases.

create_task

Create a task

crm:writesafe to retry

Adds work to the shared queue, optionally about a record and optionally assigned to a named agent (only that agent can then claim it).

Parameter	Type	Description
`title`required	string	up to 500 characters
`description`	string	up to 10000 characters
`due_at`	date-time
`priority`	integer	1 = most urgent1 to 5, default 3
`entity_id`	id	Defaults to the first entity of the activity
`assign_to`	string	Agent nameup to 100 characters
`idempotency_key`	string	Optional. Retrying with the same key returns the original result instead of writing twice.up to 200 characters

list_tasks

List tasks

crm:readread-only

Lists tasks, most urgent first. A claimed task whose lease expired is reported as open.

Parameter	Type	Description
`status`	"open" \| "claimed" \| "done" \| "cancelled"[]	default ["open","claimed"]
`entity_id`	id	Record id exactly as returned by another tool
`mine`	boolean	Only tasks assigned to or claimed by youdefault false
`due_before`	date-time
`limit`	integer	1 to 50, default 20
`cursor`	string

claim_task

Claim a task

crm:write

Takes a lease on a task so no other agent works on it. Pass task_id, or omit it to claim the most urgent available task (optionally for one entity). Re-claiming your own task extends the lease. Finish with complete_task before the lease expires, or it returns to the queue.

Parameter	Type	Description
`task_id`	id	Record id exactly as returned by another tool
`entity_id`	id	Record id exactly as returned by another tool
`lease_minutes`	integer	1 to 240, default 30

complete_task

Finish or release a task

crm:write

outcome done/cancelled closes the task (logged on the related record); released puts it back in the queue for another agent.

Parameter	Type	Description
`task_id`required	id	Record id exactly as returned by another tool
`outcome`required	"done" \| "cancelled" \| "released"
`result`	string	What was done, or why it was cancelled/releasedup to 10000 characters

Approvals

Outward-facing actions wait for a second agent.

propose_action

Propose a gated action

crm:writesafe to retry

Before doing anything outward-facing or risky (sending an email, offering a discount, changing contract terms, bulk changes), record it here and wait for approval from an agent with crm:approve. Poll list_proposals for the decision; after you act, mark it executed with resolve_proposal.

Parameter	Type	Description
`action`required	string	snake_case verb, e.g. send_email, offer_discount
`entity_id`	id	Record id exactly as returned by another tool
`payload`required	object	Exactly what would be done, e.g. {to, subject, body}
`rationale`required	string	up to 4000 characters
`idempotency_key`	string	Optional. Retrying with the same key returns the original result instead of writing twice.up to 200 characters

list_proposals

List proposals

crm:readread-only

Proposals awaiting a decision (default), or with other statuses. Approvers use this as their review queue; proposers use it to check decisions.

Parameter	Type	Description
`status`	"pending" \| "approved" \| "rejected" \| "executed"[]	default ["pending"]
`mine`	boolean	Only proposals you madedefault false
`entity_id`	id	Record id exactly as returned by another tool
`limit`	integer	1 to 50, default 20

resolve_proposal

Approve, reject or mark a proposal executed

crm:write

approved/rejected: requires crm:approve, and you cannot decide your own proposal. executed: the proposer (or approver) records that the approved action was carried out.

Parameter	Type	Description
`proposal_id`required	id	Record id exactly as returned by another tool
`status`required	"approved" \| "rejected" \| "executed"
`note`	string	up to 4000 characters

Clean-up

Archive and merge. Nothing is ever hard-deleted.

archive_entity

Archive or restore a record

crm:deletecan archive or mergesafe to retry

Hides a record from search and pipelines without deleting it (nothing is ever hard-deleted). restore: true brings it back.

Parameter	Type	Description
`id`required	id	Record id exactly as returned by another tool
`reason`required	string	up to 1000 characters
`restore`	boolean	default false

merge_entities

Merge duplicate records

crm:deletecan archive or merge

Merges merge_id into keep_id (same kind). keep_id's values win; its blank fields are filled from merge_id. Links, activity, tasks and proposals move to keep_id. merge_id stays as a pointer, so old ids still resolve.

Parameter	Type	Description
`keep_id`required	id	Record id exactly as returned by another tool
`merge_id`required	id	Record id exactly as returned by another tool
`reason`required	string	up to 1000 characters

Admin

Keys, stages and the playbook.

manage_agents

Manage agent API keys

crm:admincan archive or merge

Workspace admin: list agents, create a key for a new agent (returned once; store it securely), or revoke one. Give each agent the fewest scopes it needs: crm:read, crm:write, crm:delete (archive/merge), crm:approve (decide proposals), crm:admin.

Parameter	Type	Description
`action`required	"list" \| "create" \| "revoke"
`name`	string	create: the new agent's name, e.g. 'research-agent'up to 100 characters
`scopes`	"crm:read" \| "crm:write" \| "crm:delete" \| "crm:approve" \| "crm:admin"[]	create: default [crm:read, crm:write]
`agent_id`	id	revoke: the agent to revoke

configure_workspace

Configure the workspace

crm:adminsafe to retry

Workspace admin: set the deal pipeline stages (ordered; closed_stages must be a subset) and the playbook, a markdown document of rules every agent should follow (served as the crm://playbook resource).

Parameter	Type	Description
`pipeline_stages`	string[]	up to 30 items
`closed_stages`	string[]
`playbook`	string	up to 50000 characters

Resources and prompts

Resources are documents agents can read. Prompts are ready-made workflows a client can offer you.

Resource	What it holds
`crm://guide`	How to use this CRM
`crm://playbook`	This workspace's playbook

Prompt	What it does	Arguments
`meeting_prep`	Brief yourself on a person, organization or deal before a meeting	who
`log_conversation`	Turn a transcript, email thread or notes into CRM updates	text, source
`pipeline_review`	Find stalled and at-risk deals and propose next steps	none