Semogram Docs
MCPTools reference

identity_correction_propose

Validate an exact merge, split, resolve, or reversal and create an expiring proposal for independent review. Merge, split and resolve require an explicit ontology targetId; IDs are never allocated automatically.

When to use it

Use identity_correction_propose to propose an identity correction. On the workspace endpoint, pass projectId from project_list. On a project-scoped endpoint, the project is already bound: omit that argument and use the schema discovered from that endpoint.

Arguments

NameTypeRequiredDefaultConstraints
operationKeystringYes—Minimum length: 1; Maximum length: 2000
kindstringYes—Allowed: "merge", "split", "reverse", "resolve"
expectedRevisionintegerYes—Minimum: 0; Maximum: 9007199254740991
entityIdsarrayYes—Maximum items: 100; Items: string
observationIdsarrayYes—Maximum items: 1000; Items: string
targetIdunionYes—Alternative shapes; see full schema
reversesDecisionIdunionYes—Alternative shapes; see full schema
rationalestringYes—Minimum length: 1; Maximum length: 2000
evidencearrayYes—Minimum items: 1; Maximum items: 100; Items: object
expiresAtstringYes—Format: date-time; Pattern constraint; see full schema
projectIdstringYes—Format: uuid; Pattern constraint; see full schema

View the complete input schema, including nested contracts and alternative shapes. The schema is extracted from the workspace server’s Zod definitions. Runtime validation also enforces custom checks that JSON Schema cannot express.

Response shape

The operation-specific payload is returned in data; its contents follow the operation described above.

MCP returns a text block containing the JSON operation result and a structuredContent copy. The envelope includes data, completeness, truncated, freshness, and warnings. Depending on the operation it can also include nextCursor, evidence, job, or receipt.

Check those fields before treating a conversational summary as the result. When a job is returned, inspect its status with the appropriate execution tool; a queued response is not confirmation that work finished. Follow evidence links when checking the underlying records.

Input methods

This request illustrates the argument structure. Replace every angle-bracket placeholder with a real value and supply any applicable optional fields from the schema. Nested business contracts must match your actual configuration. Send it through an authenticated, initialized MCP client; this JSON alone does not establish a session or sign you in.

Use Semogram’s identity_correction_propose tool to propose an identity correction. Inspect the required inputs and target first, then show me what will change before executing it.

Choose the project explicitly before making this request. Use real resource IDs returned by earlier reads; a resource name is not a UUID. Do not fill missing business inputs with invented values.

This is an MCP tools/call request, not a form to paste into Semogram. Send it through an authenticated, initialized MCP client.

MCP request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "identity_correction_propose",
    "arguments": {
      "operationKey": "<OPERATION_KEY>",
      "kind": "merge",
      "expectedRevision": 1,
      "entityIds": [
        "<ENTITY_IDS>"
      ],
      "observationIds": [
        "<OBSERVATION_IDS_UUID>"
      ],
      "targetId": "<TARGET_ID>",
      "reversesDecisionId": "<REVERSES_DECISION_ID_UUID>",
      "rationale": "<RATIONALE>",
      "evidence": [
        {
          "reference": "<REFERENCE>",
          "description": "<DESCRIPTION>"
        }
      ],
      "expiresAt": "<EXPIRES_AT>",
      "projectId": "<PROJECT_ID_UUID>"
    }
  }
}

FAQ

What access and approvals are required?

Required permission scopes: ontologies:write. OAuth uses current workspace membership; API keys use their assigned scopes and grants. Discovery can exclude tools the caller cannot use.

Read-only annotation: No. Destructive annotation: No. Follow the operation’s declared contract and any applicable server-side approval policy.

How should I handle retries?

Do not assume repeated calls are safe merely because the client offers Retry. Inspect the result or existing request before repeating work that changes state. For 429 responses, honor Retry-After rather than retrying immediately.

Why is this tool missing or returning an error?

Confirm the workspace, resource IDs, and permission scopes. Read the returned error before changing the request. See connection, authentication and troubleshooting for sign-in, scope, resource access, and rate-limit errors.

ontology_read_binding_update

Change a read binding. The merged binding is validated against the endpoint contract before it is saved.

identity_review_decide

Submit a merge, split, resolve, or reversal covering up to 1,000 observations. The decision remains a governed proposal until independently approved and applied.

On this page

When to use itArgumentsResponse shapeInput methodsFAQWhat access and approvals are required?How should I handle retries?Why is this tool missing or returning an error?