Skip to main content
Glama

Merge two candidates

merge_candidates
Destructive

[Candidates] Merge merge_id into keep_id after preview_candidate_merge (send its preview_token; field_choices picks keep or merge per field). Owners and admins only. IRREVERSIBLE: there is no unmerge. The candidate is not told. It is for two records of the same person.

Every argument in full, with examples: get_tool_reference.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "keep_id": "<keep_id>",
      "merge_id": "<merge_id>",
      "preview_token": "<preview_token>"
    },
    "name": "merge_candidates"
  }
}

Input Schema

NameRequiredDescriptionDefault
keep_idYesCandidate id (the `id` of a list_candidates row) of the record that stays.
merge_idYesCandidate id (the `id` of a list_candidates row) of the record merged into it; it is archived and points to the kept record afterwards.
llm_modelNoYour model id, e.g. "claude-opus-4-8"; "unknown" if unsure. For analytics.
duplicate_idNoDuplicate pair id (a duplicate pair `id` from get_candidate include=duplicates) this merge resolves; found from the pair when left out.
field_choicesNoPer field, 'keep' (the default) keeps the kept record's value and 'merge' takes the merged record's.
preview_tokenYesThe preview_token of preview_candidate_merge for the same pair. When the records changed since the preview, the merge is refused with 409 and needs a new preview.
conversation_idNoThe conversation_id this server returned earlier in this conversation, unchanged, including after later user messages. Omit it if you have none. Recorded for the server developer's analytics.

Output Schema

NameRequiredDescriptionDefault
movedYes
keep_idYes
merge_idYes
repeatedYes
not_movedYes
merge_record_idYes
_mcp_instructionsNoServer-issued metadata for this conversation.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / preview_token / description
      Previous value: -"The preview_token of preview_candidate_merge for the same pair. When the records changed since the preview, the merge is refused with 409: preview it again."New value: +"The preview_token of preview_candidate_merge for the same pair. When the records changed since the preview, the merge is refused with 409 and needs a new preview."
  2. Changed5 schema fields changed
    • changedInput schema / properties / duplicate_id / description
      Previous value: -"Duplicate pair id (profile_interview_duplicate.id) this merge resolves; found from the pair when left out."New value: +"Duplicate pair id (a duplicate pair `id` from get_candidate include=duplicates) this merge resolves; found from the pair when left out."
    • changedInput schema / properties / keep_id / description
      Previous value: -"Candidate id (profile_interview.id) of the record that stays."New value: +"Candidate id (the `id` of a list_candidates row) of the record that stays."
    • changedInput schema / properties / merge_id / description
      Previous value: -"Candidate id (profile_interview.id) of the record merged into it; it is archived and points to the kept record afterwards."New value: +"Candidate id (the `id` of a list_candidates row) of the record merged into it; it is archived and points to the kept record afterwards."
    • changedInput schema / properties / preview_token / description
      Previous value: -"Required: the preview_token of merchant-candidate-merge-preview for the same pair. Missing, or no longer matching the records, answers 409: preview the merge again."New value: +"The preview_token of preview_candidate_merge for the same pair. When the records changed since the preview, the merge is refused with 409: preview it again."
    • changedInput schema / required
      Previous value: -[
      -  "keep_id",
      -  "merge_id"
      -]New value: +[
      +  "keep_id",
      +  "merge_id",
      +  "preview_token"
      +]
  3. Changed20 schema fields changed
    • changedInput schema / properties / field_choices / description
      Previous value: -"Per field, 'keep' (the default) keeps the kept record's value and 'merge' takes the merged record's. date_of_birth applies when both records have identity data."New value: +"Per field, 'keep' (the default) keeps the kept record's value and 'merge' takes the merged record's."
    • removedInput schema / properties / field_choices / example
      Removed value: -{
      -  "phone_number": "merge"
      -}
    • removedInput schema / properties / field_choices / properties / avatar_local_path / description
      Removed value: -"Which record's avatar_local_path the kept record ends with."
    • removedInput schema / properties / field_choices / properties / avatar_url / description
      Removed value: -"Which record's avatar_url the kept record ends with."
    • removedInput schema / properties / field_choices / properties / date_of_birth / description
      Removed value: -"Which record's date_of_birth the kept record ends with."
    • removedInput schema / properties / field_choices / properties / email / description
      Removed value: -"Which record's email the kept record ends with."
    • removedInput schema / properties / field_choices / properties / external_id / description
      Removed value: -"Which record's external_id the kept record ends with."
    • removedInput schema / properties / field_choices / properties / linked_in / description
      Removed value: -"Which record's linked_in the kept record ends with."
    • removedInput schema / properties / field_choices / properties / mojito_language_code / description
      Removed value: -"Which record's mojito_language_code the kept record ends with."
    • removedInput schema / properties / field_choices / properties / name / description
      Removed value: -"Which record's name the kept record ends with."
    • removedInput schema / properties / field_choices / properties / phone_number / description
      Removed value: -"Which record's phone_number the kept record ends with."
    • removedInput schema / properties / field_choices / properties / physical_address / description
      Removed value: -"Which record's physical_address the kept record ends with."
    • addedInput schema / properties / llm_model
      Added value: +{
      +  "description": "Your model id, e.g. \"claude-opus-4-8\"; \"unknown\" if unsure. For analytics.",
      +  "type": "string"
      +}
    • removedOutput schema / properties / keep_id / description
      Removed value: -"Candidate id (profile_interview.id) of the record that stayed."
    • removedOutput schema / properties / merge_id / description
      Removed value: -"Candidate id (profile_interview.id) of the merged, now archived, record."
    • removedOutput schema / properties / merge_record_id / description
      Removed value: -"Id of the merge record (profile_interview_merge.id)."
    • removedOutput schema / properties / moved / description
      Removed value: -"Records moved to the kept candidate, by kind (table name: count)."
    • removedOutput schema / properties / moved / example
      Removed value: -{
      -  "position_result": 1
      -}
    • removedOutput schema / properties / not_moved / description
      Removed value: -"Records that stayed with the merged record because the kept one already had one in that place (table name: count). Usually empty."
    • removedOutput schema / properties / repeated / description
      Removed value: -"True when this pair was already merged the same way; nothing changed again."
  4. Added

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes beyond the destructiveHint=true annotation by spelling out the concrete consequence: IRREVERSIBLE, no unmerge, and the merged person is not notified. Also discloses the 409 refusal when records changed since preview. Does not describe side effects on related records (interviews, notes) beyond archiving the merge_id record.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the action and direction, then the prerequisite, then the hazard; every clause carries operational weight. The trailing pointer to get_tool_reference is a deliberate offload rather than filler, though it slightly dilutes the otherwise dense sentence structure.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, permission-gated, token-validated merge, the description covers prerequisites, authorization, irreversibility and stale-token failure, and an output schema exists so return values need not be explained. What remains unstated is the fate of non-field data attached to the merged record.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so keep_id, merge_id, preview_token, duplicate_id and field_choices are already documented in the schema. The description restates that field_choices picks keep or merge per field without adding format, default or edge-case detail beyond the schema, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (merge) with explicit direction (merge_id into keep_id) and names the enabling prerequisite tool preview_candidate_merge. The qualification 'for two records of the same person' plus 'the candidate is not told' distinguishes it clearly from dismiss_candidate_duplicate and from the preview sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit precondition: must follow preview_candidate_merge and send its preview_token. States the authorization requirement ('Owners and admins only') and the scope ('two records of the same person'). It does not explicitly name dismiss_candidate_duplicate as the non-merge alternative for false positives, so the routing guidance is clear but not exhaustive.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.