Skip to main content
Glama
langmail-mcp

langmail-mcp

Official
by langmail

Search contacts

search_contacts
Read-onlyIdempotent

Resolve names, partial names, email addresses, organizations, or roles like “my lawyer” to known contacts, ranked by role and interaction recency, before drafting mail or creating events.

Instructions

Resolve a person's name, partial name, email address, organization, or what they are to the user ("my lawyer", "my landlord") to known contacts. People holding that role come first, the rest are ranked by interaction recency and frequency. Sources include the collected address book maintained from mail headers (both directions, including Sent) and calendar attendees and organizers, plus the user's personal address books, and contacts written with create_contact. Use this before creating events or drafting mail when only a name is known, and before create_contact or update_contact to get the contact_id. Returns for each contact its roles, one or more addresses with a confidence level, the birthday when one is stored, and recent interactions; the detailed format adds phone numbers, postal addresses and the note. Do not use it to enumerate all contacts; a query is required, and for "whose birthday is coming up" use list_upcoming_birthdays instead. If several plausible people match, present the candidates to the user rather than guessing; when two of them are the same person or organization, merge_contacts folds them into one.

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": {
      "query": "<query>"
    },
    "name": "search_contacts"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum number of matching people.
queryYesName, partial name, email address, organization, or what the person is to the user ("lawyer", "my landlord"). Matched against display names, organizations, addresses, address domains, and the roles stored on contacts.
contextNoBiases address ranking when a person has addresses in several contexts. `work` prefers organization-domain addresses; `private` prefers personal-domain addresses. Never filters a person out entirely.any
response_formatNo`concise` returns name, contact id, roles, best address, confidence, relationship, the birthday when stored, and the last interactions. `detailed` adds all known addresses with their own confidence, phone numbers, postal addresses, the note, where the record came from, and interaction record ids (for chaining into get_email or list_calendar_events), plus excluded relay addresses.concise

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?

Goes well beyond the read-only/idempotent annotations: it discloses the ranking algorithm (role matches first, then interaction recency and frequency), the data sources (mail headers in both directions including Sent, calendar attendees/organizers, personal address books, records written by create_contact), and the per-contact return payload. It also gives operational guidance for ambiguous matches — surface candidates rather than guess.

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-loaded with the core purpose and ranking, then sources, then when-to-use and anti-patterns — the ordering is sensible and dense with signal. It is long, though, and the return-contents sentence duplicates material already present in the response_format schema description, which is the only real waste.

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?

With no output schema, the description carries the return-shape burden and does so: roles, addresses with confidence, birthday when stored, recent interactions, and what detailed adds. Combined with the fully covered input schema and safety annotations, nothing an agent needs to call this correctly is missing.

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 coverage is 100% and each parameter already documents itself, so the baseline is 3. The description restates query's accepted forms and the detailed-format additions in prose, but adds little syntax or constraint detail the schema lacks (no limit, context, or response_format behavior beyond what is already written).

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 ('resolve ... to known contacts') and enumerates the input kinds it accepts, including role phrases like "my lawyer". It explicitly distinguishes itself from list_upcoming_birthdays and from enumeration-style listing, so an agent can place it among siblings without opening a schema.

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?

Gives concrete trigger conditions ('before creating events or drafting mail when only a name is known', 'before create_contact or update_contact to get the contact_id') and explicit exclusions ('do not use it to enumerate all contacts; a query is required'), plus routing to merge_contacts when duplicates appear. Ambiguity about alternatives is essentially removed.

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