Tools Guide - Morphic

The Tools Reference is generated from the live server and lists every tool’s parameters. This page is the hand-written companion: the conventions the reference doesn’t repeat 103 times.

Result shape

Every tool returns the standard MCP content envelope with a single text part containing pretty-printed JSON:

{ "content": [{ "type": "text", "text": "{ … }" }] }

A few tools return a bare string rather than JSON — ping is one. The memory tools (morphic_recall, morphic_attachment_recall, morphic_remember) return JSON on success; older integrations that parsed their bare-string output need updating.

Error envelope

Every tool converges on one machine-readable error shape. Branch on error_code; if your agent simply relays user_message verbatim, the wording is already correct and product-voiced.

Failures return isError: true and a JSON body:

{
  "success": false,
  "error_code": "not_found",
  "user_message": "I couldn't find that record.",
  "retryable": false
}

Field	Meaning
`success`	Always `false` on this envelope
`error_code`	Stable machine code — see below
`user_message`	Stable, product-voice wording. Safe to show an end user as-is
`retryable`	`true` when the same call may succeed if retried. Retries should never be narrated to the user
`detail`	Present only for validation failures (400/422), scrubbed. This is the one case where backend detail is actionable — e.g. “status slug `X` is not valid”

Error codes

`error_code`	Retryable	Typical cause
`invalid_input`	No	Schema or value the backend rejected
`not_found`	No	The id doesn’t exist, or isn’t visible to this key
`not_connected`	No	The connection expired, was revoked, or was never established — reconnect. Distinct from `permission_denied`: no permission change fixes it
`permission_denied`	No	Authenticated, but not allowed to reach that workspace data
`workspace_selection_required`	No	The grant covers several workspaces and none was named — retry with the `workspace` argument
`conflict`	Yes	Record changed underneath you — re-read and retry
`insufficient_credits`	No	Workspace is out of credits for that feature
`rate_limited`	Yes	Too many requests
`service_unavailable`	Yes	Backend didn’t respond successfully
`timeout`	Yes	Backend took too long
`addon_not_installed`	No	Paid add-on isn’t installed for this workspace
`addon_tool_failed`	Yes	Add-on provider errored
`research_failed`	Yes	An LLM-backed research/analysis tool couldn’t complete
`provider_not_configured`	No	That capability isn’t configured for this workspace

Backend prose never reaches the model: HTTP {status}: {detail} strings, component names, tenant ids and stack traces are sanitised at a single boundary. Full diagnostics still go to the server’s stderr for operators.

Wiki tools previously returned failures without isError, which made a failed write look like a success. They now use the envelope above. If you special-cased wiki responses, remove that code.

Choosing a workspace per call

Every tool takes an optional workspace argument: a workspace slug, on any call. It only matters when a connection was approved for more than one workspace. Then the server cannot guess which one a request means, and answers workspace_selection_required until one is named. Set workspace and the call proceeds:

{ "name": "list_entities", "arguments": { "object_type_slug": "deals", "workspace": "acme" } }

Call list_workspaces for the slugs this connection may use. Omit the argument to use whatever the connection already resolves to — a sole approved workspace, or the ?workspace= on the connect URL.

The argument is a request, not a decision. The server re-checks it against what you approved on the consent screen and your live membership on every call, so a workspace outside the grant is refused no matter what a client sends.

Object-type slugs are plural

Morphic’s default object types are people, companies, deals — not person/company/deal. Anywhere a tool takes object_type_slug or entity_type, use the plural form. Workspaces can define custom object types, so never hard-code the list. Call list_entity_types for the real slugs, then get_entity_type_schema for a type’s field slugs before writing to it.

Task statuses are workspace-configured

create_activity.status and update_activity.status take a workspace task-status slug, not a fixed enum. Call list_task_statuses to get this workspace’s exact slugs.

There is no pending status. Older documentation listed it; it was never valid. Common real slugs are not_started, in_progress, completed, cancelled — but confirm with list_task_statuses.

activity_type and priority are fixed enums, and are enforced at the schema level:

activity_type: task · email · call · meeting · note · stage_change
priority: low · medium · high

`create_activity` vs `create_note`

Both attach text to a record; they land in different places.

create_activity(activity_type="note", …) → a timeline note, ordered chronologically alongside calls, emails and meetings.
create_note(…) → a standalone, editable, pinnable note in the record’s notes panel.

Note bodies are stored exactly as sent. Pass real newlines — the server no longer rewrites literal \n sequences into line breaks, so an escaped string arrives escaped.

Bulk tools

Every bulk_* tool takes an array of up to 200 ids and applies the same change to all of them. For per-record different values, loop the single-record tool instead. Bulk calls return per-id success/failure, so one bad id does not abort the batch. Always inspect the per-id results rather than assuming a 200 means everything applied. Bulk tools available: bulk_update_entities, bulk_archive_entities, bulk_delete_entities, bulk_link_entities, bulk_unlink_entities, bulk_create_activities, bulk_update_activities, bulk_archive_activities, bulk_delete_activities, bulk_create_notes, bulk_delete_notes.

Linking and unlinking records

link_entities and unlink_entities take the same three arguments — the relation is addressed by attribute slug, not by a relation id:

{
  "entity_id": "<source uuid>",
  "attribute_slug": "company",
  "target_entity_id": "<target uuid>"
}

Older documentation said unlink_entities takes entity_id + relation_id. It does not, and never has in the shipped server — that call fails schema validation. There is no need to save a relation_id from link_entities.

The attribute slug is resolved to its internal UUID for you. Resolution costs two extra backend calls and the cache is per-request, so a tight loop of links is noticeably slower than bulk_link_entities.

Answering a question: start with Context

For any question about this workspace — a named record of any object type, or what people have said or done (Slack, email, meetings, chat, “did anyone mention X”) — call ask_context before any search tool. Pass the user’s question verbatim; do not pre-extract names or look up an id first. You do have conversation history; it reaches you through this tool, not through Slack’s or Gmail’s own APIs. Never tell the user you cannot search past messages. If contexts is empty, semantic is still a complete answer — Slack-only workspaces do not auto-create CRM records. Empty semantic too means nothing is indexed yet. ask_context returns these keys:

Key	What it is
`resolved`	Which records the question turned out to be about. May be empty.
`primary_layer`	`gold`, `semantic`, or `empty` — which layer to treat as the answer.
`contexts`	Per record, a compacted brief of its current state, plus a relationship layer. Answer from here when a record resolved.
`semantic`	Recall over the workspace’s indexed history, scoped to the question. Populated even when `resolved` is empty. On Slack-only workspaces this is the answer.
`next_steps`	Which deeper tool to call, and when, if the layers above fall short. When Gold is empty, includes `narrower_question`: the slice is not the full thread.

It never errors on a question it cannot resolve — an unmatched question still returns semantic and next_steps. Only then reach for the deeper layers, and only for the reason next_steps gives:

get_entity / get_entity_with_relations — you need a record’s raw field values.
list_activities — you need the chronological timeline itself.
search_entities / list_entities — resolved was empty or wrong, or you want a ranked list rather than one record’s story.
morphic_recall — the question is about durable cross-session memory, not a record.

If you already hold a record id, get_context is the entity-scoped form of the same call. The same layers are available over REST: POST /api/gold/context/ask (body: question, optional max_entities, include_graph) and GET /api/gold/{entity_id}/context.

Finding records

search_entities is semantic (vector) search. When nothing matches it returns an explicitly empty result rather than an error:

{
  "items": [],
  "total": 0,
  "hint": "no_match",
  "note": "No CRM matches for this query. Try list_entities with a keyword or exact field filter, or ask the user for a name or email to narrow it down."
}

list_entities is the deterministic counterpart and does far more than paginate. Beyond object_type_slug, search, is_archived, page and page_size it accepts:

entity_ids — hydrate a specific set of records in one call.
sort_by — a sort expression, e.g. created_at:desc or deal_value:asc.
filters — field-level conditions keyed by attribute slug, e.g.
{ "deal_value": { "operator": "greater_than", "value": 10000 }, "stage": { "operator": "is", "value": "negotiation" } }
The 19 operators are is, equals, is_not, not_equals, contains, not_contains, starts_with, ends_with, greater_than, less_than, greater_than_or_equal, less_than_or_equal, after, before, between, is_empty, empty, not_empty, is_not_empty. Omit value for the emptiness operators; pass value2 with between.

Call get_entity_type_schema first so your slugs and operators match the attribute types.

Knowledge base list results are lossy

list_kb_documents deliberately shrinks its payload: each item’s content_markdown is truncated to a ~160-character excerpt and the BlockNote content field is removed entirely. Use it to discover what exists; call get_kb_document for a real body. fetch_all=true flattens every folder level. page / page_size are still sent alongside it and their interaction with fetch_all is backend-defined — prefer one or the other, not both.

Automations

author_workflow is the only way to build automation logic. No tool exposes raw React Flow graph JSON: authoring is delegated to the same LLM-backed builder the Morphic UI uses, from a natural-language description. Two current engine limits to plan around:

Linear only. Condition and branch nodes are not evaluated by the execution engine yet.
No retries. A failed step aborts the entire run.

Typical sequence: create_workflow (draft metadata) → author_workflow (trigger + steps) → publish_workflow (go live) → enqueue_workflow_manual_run (run it now, for real) → list_workflow_runs / get_workflow_run (inspect).

Optional request headers

Header	Purpose
`X-Idempotency-Key`	Opaque token forwarded unchanged to the backend for that single tool call. Scoped per request; the MCP server never inspects it
`X-Backend-URL`	Route this request’s tool calls at a different Morphic backend. The origin must be allowlisted server-side or the request is rejected with 400. Auth validation always uses the server’s own backend
`X-Morphic-Channel`, `X-Morphic-Actor-Assertion`	Agent-transport metadata forwarded to the backend, which is the only component that verifies the assertion

Where to go next

Tools Reference — every tool, generated from the server
Tool Groups — advertise only the tools you need
Common Workflows — end-to-end worked examples
Troubleshooting

​Result shape

​Error envelope

​Error codes

​Choosing a workspace per call

​Object-type slugs are plural

​Task statuses are workspace-configured

​create_activity vs create_note

​Bulk tools

​Linking and unlinking records

​Answering a question: start with Context

​Finding records

​Knowledge base list results are lossy

​Automations

​Optional request headers

​Where to go next

Result shape

Error envelope

Error codes

Choosing a workspace per call

Object-type slugs are plural

Task statuses are workspace-configured

`create_activity` vs `create_note`

Bulk tools

Linking and unlinking records

Answering a question: start with Context

Finding records

Knowledge base list results are lossy

Automations

Optional request headers

Where to go next