Skip to main content
Glama
langmail-mcp

langmail-mcp

Official
by langmail

Merge contacts

merge_contacts
Destructive

Combine duplicate contacts into one kept record, delete the rest, and consolidate emails, phones, addresses, notes, and interaction history; conflicting values are listed for review.

Instructions

Merge duplicate contacts — the same person or organization collected under several addresses — into the one to keep, and delete the others. The kept contact gains every email address, phone number, postal address and note of the merged ones and their interaction history; its name, organization, birthday and preferred address stay unless it has none, and every value that does not fit is listed as a conflict. Later mail from any merged address updates the kept contact. Returns the merged contact in the detailed search_contacts format plus the full details of the removed contacts, which is what undoing it by hand needs. Find the ids with search_contacts; to move a single address between two contacts that are different people, use update_contact instead, and to drop a contact without keeping anything, delete_contact.

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": {
      "contactId": "<contactId>",
      "mergeContactIds": "<mergeContactIds>"
    },
    "name": "merge_contacts"
  }
}

Input Schema

NameRequiredDescriptionDefault
contactIdYesThe contact to keep, as printed by search_contacts under `contact_id`. Its name, organization and birthday win.
preferredEmailNoThe address mail to this contact should go to, from any of the merged contacts. Omit it to keep the preferred address the kept contact has now.
mergeContactIdsYesThe contacts to fold into it and then delete, as printed by search_contacts under `contact_id`. Up to 10.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already flag destructiveHint=true and idempotentHint=false, but the description goes well beyond them: it says which fields win, that all emails/phones/addresses/notes and interaction history transfer, that non-fitting values surface as conflicts, that later mail from merged addresses reroutes to the kept contact, and implicitly that there is no automated undo ('what undoing it by hand needs'). This is exactly the mutation risk context an agent needs.

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?

The purpose is front-loaded in the first clause and every following sentence carries new information (field precedence, conflict handling, rerouting, return contents, alternatives). It is dense and long for one paragraph, but nothing is filler.

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

Completeness5/5

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

There is no output schema, yet the description explains the return value (merged contact in detailed search_contacts format plus full details of removed contacts and why). Combined with the destructive-mutation disclosure and conflict semantics, an agent has everything needed to call it and interpret the result.

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 the schema already documents contactId, mergeContactIds and preferredEmail thoroughly, including the 10-item cap and the precedence rule. The description reinforces the kept-contact precedence but adds no syntax, format or edge-case detail beyond what the schema states, 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 and resource ('Merge duplicate contacts ... into the one to keep, and delete the others') and qualifies what counts as a duplicate (same person or organization under several addresses). This is unmistakably distinct from search_contacts, update_contact and delete_contact.

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

Usage Guidelines5/5

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

Explicitly routes the agent: use search_contacts to find ids, update_contact to move a single address between two different people, delete_contact to drop a contact without keeping anything. Both when-to-use and when-not-to-use are covered with named alternatives.

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