Loading ToolBench
Model Context Protocol (MCP) server for the DataMerge Company API. Provides company enrichment, hierarchy lookup, contact search, and list management capabilities.
DataMerge MCP demonstrates solid definition quality overall. All 17 tools have clear, action-verb names and non-trivial descriptions (194-340 char range, well within the 10-1024 baseline). Input schemas are uniformly present with typed parameters and descriptions. However, there are systematic gaps: (1) Output schemas are not documented in the tool definitions, the descriptions mention what's returned (e.g., 'job_id', 'record_ids', 'full company records') but no formal output schema is visible in the code. (2) Some parameters lack clarity on constraints, e.g., 'country_code' in start_company_enrichment has no description of the ISO 2-letter format, forcing LLMs to guess. (3) Three async/polling tool pairs (start_*_enrichment / get_*_enrichment_result) exist alongside agent-friendly equivalents (run_*_enrichment), this is intentional composition but adds cognitive load. (4) The 'run_*' tools have complex internal logic (continuation tokens, polling) that is not reflected in parameter validation examples. (5) Tool descriptions are generally good (avg 250 chars) but a few lack dependency hints, e.g., contact_enrich does not mention that domains must match enriched contact records. Per-tool analysis shows consistent naming conventions (all start with action verbs), solid parameter type coverage, and descriptions that explain WHAT (e.g., 'POST /v1/company/enrich') and WHY (e.g., 'Returns a job_id (async)'). Error handling is mentioned only for the 'configure_datamerge' tool; other tools lack explicit error recovery guidance.
Configure DataMerge API authentication (required before using other tools if DATAMERGE_API_KEY is not set).
POST /v1/contact/enrich. Enrich contacts with additional fields (emails, phone numbers, social profiles, etc.). Returns a job_id (async).
POST /v1/contact/search. Search for contacts by domain(s) and/or job title. Returns a job_id (async). Requires at least one of: domains, job_title. Optional: enrich_fields (e.g. ['contact.emails', 'contact.phone_numbers']).
POST /v1/list/create. Create a new list to organize enriched companies.
GET /v1/company/get. Get a single company record by datamerge_id (charges 1 credit) or record_id (free). Optional: add_to_list (list slug, only with datamerge_id).
Output schemas not documented in tool definitions. Descriptions mention returned fields (job_id, record_ids, company records) but no formal output schema is visible. LLMs cannot plan downstream tool calls without knowing the response structure.
Parameter constraint clarity: 'country_code' in start_company_enrichment, get_company_hierarchy is described as 'ISO 2-letter country code' but the description does not include this constraint text. Descriptions should state the format explicitly (e.g., 'ISO 2-letter country code (e.g., US, UK)') to prevent LLM hallucination.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | A | 81 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 49 | 2024-11-05+ | v1 |
GET /v1/company/enrich/{job_id}/status. Poll until status is "completed" or "failed". Response includes record_ids. Status values: queued · processing · completed · failed.
GET /v1/company/hierarchy. Get the corporate hierarchy for a company. Get all entities in the same global ultimate hierarchy. Optional: include_names (bool, charges 1 credit), include_branches, only_subsidiaries, max_level (int), country_code (array), page (int).
GET /v1/contact/get/{record_id}. Get a single contact record by ID.
GET /v1/contact/enrich/{job_id}/status. Poll contact enrichment job status until "completed" or "failed". Response includes record_ids of enriched contacts.
GET /v1/contact/search/{job_id}/status. Poll contact search job status until "completed" or "failed". Response includes record_ids of matched contacts.
GET /v1/account/credits. Get the current credits balance for this account.
GET /v1/list/{list_slug}/items. Get items in a list with pagination.
Agent-friendly company enrichment. On the first call provide enrichment params (domain, domains, company_name, country_code, etc.); the server starts the job and polls internally for up to ~25s. If the job is still running when that window expires, the response will be {status:"pending", continuation_token, attempt, elapsed_seconds}. When you see status "pending" you MUST immediately call run_company_enrichment again with only continuation_token set — do not ask the user, do not call any other tool first. Typical jobs finish within 5 attempts (~125s). On completion the response contains record_ids and full company records.
Agent-friendly contact enrichment. On the first call provide contacts and enrich_fields; the server starts the job and polls internally for up to ~25s. If the job is still running, return {status:"pending", continuation_token, attempt, elapsed_seconds}. Immediately call run_contact_enrich again with only continuation_token. Typical jobs finish within 5 attempts. On completion, response contains record_ids and enriched contact records.
Agent-friendly contact search. On the first call provide search params (domains, job_title, enrich_fields); the server starts the job and polls internally for up to ~25s. If the job is still running when that window expires, return {status:"pending", continuation_token, attempt, elapsed_seconds}. Immediately call run_contact_search again with only continuation_token — do not ask the user. Typical jobs finish within 5 attempts. On completion, response contains record_ids and contact records.
POST /v1/company/enrich. Enrich one or more companies by domain. Returns a job_id (async). Single: domain. Batch: domains, country_code, global_ultimate, list, skip_if_exists.
POST /v1/company/enrich then poll GET /v1/company/enrich/{job_id}/status until status is "completed" or "failed" or timeout. Same params as start_company_enrichment plus poll_interval_seconds and timeout_seconds.
Three async/polling tool pairs (start/get_*_enrichment, start/get_*_contact_search, start/get_*_contact_enrich) coexist with agent-friendly equivalents (run_*). While composition is sound, tool selection cognitive load is high. Descriptions do not explain WHEN to use the polling vs. agent-friendly variants, LLMs may pick incorrectly.
Error handling guidance is minimal. Only 'configure_datamerge' shows explicit error paths in code (missing sessionId, missing API key). Other tools have no documented error recovery or actionable error messages visible in tool definitions. Agents cannot know: is a job failure retryable? Should they call another tool?
Continuation token and polling logic in 'run_*' tools is complex (max_wait_seconds, attempt tracking, elapsed_seconds) but parameter descriptions do not explain the polling model clearly enough. An LLM may misunderstand the 'continuation_token' contract ('set only continuation_token on retry') and call other parameters simultaneously.