Meltwater

Use this tool when the user wants to see engagement details or analytics per recipient for a specific outreach distribution. Typical user requests: "show me the analytics per recipient", "who opened my outreach", "show me the recipient breakdown for this outreach". This is a read-only operation scoped to the authenticated user's company. Returns a paginated result using the page (default 0) and pageSize (default 100) parameters. The response contains: a contacts array (individual recipients with emailAddress, status — one of: opened, unopened, bounced, replied, untracked — bounce type, unsubscribe flag, and profile data), a sources array (journalist/source contacts with the same fields plus name and location), and a count with the total number of recipients. Do NOT use this tool for campaign-level metrics — use mediarelations_get_outreach_count_analytics instead. Do NOT use this tool for delivery counters and rates — use mediarelations_get_outreach_count_analytics instead.

mediarelations_get_outreach_recipients_aggregations

Use this tool when the user wants to see a list of their outreach campaigns. Typical user requests: "show me all my outreaches", "list my campaigns", "what outreaches do I have?". Returns a paginated result — use page and pageSize to navigate results, and sortField / sortOrder to control ordering. This is a read-only operation scoped to the authenticated user's company. Returns an object with a total count and a hits array of outreach items, each containing subject, status, sender address, creation date, and associated media lists. Do NOT use this tool to get the full details of a specific outreach (like full body) — use mediarelations_get_outreach_content instead.

mediarelations_get_outreaches

Use this tool when the user wants to inspect the full configuration of a specific saved search by its ID. This is a read-only operation scoped to the authenticated user's company. Returns the full saved search object including searchConfiguration, relevantConfiguration, searchType, keywordType, and metadata (creator, dates). Use the optional 'fields' parameter to limit the response for better performance. Use the returned searchConfiguration to execute the saved search with mediarelations_search_contacts or mediarelations_search_sources. Do NOT use this tool to list all saved searches — use mediarelations_get_saved_searches instead.

mediarelations_get_saved_search

Use this tool when the user wants to list or browse their saved searches. This is a read-only operation scoped to the authenticated user's current workspace. Returns a paginated response with: hits (array of saved search metadata including name, type, creator, dates), count, page, size, and totalPages. Supports pagination (size default 12, page 0-indexed), partial name filtering (search parameter, case-insensitive), sorting (sortBy: searchName/createdAt/updatedAt/executedAt, sortOrder: asc/desc), and field selection (fields parameter, comma-separated). Do NOT use this tool to retrieve full details of a specific saved search — use mediarelations_get_saved_search with the saved search ID instead.

mediarelations_get_saved_searches

Returns the details of a single standard (or Explore) search by its ID, including its name, query type, query configuration, and metadata.

listening_get_search

Use when adding documents to an edition to get the full Newsletters-compatible documents. Retrieves full document content for use in an edition of one or more documents by their IDs. Returns complete documents including body text, metadata, and consumer attributes. When saving these documents in other tools do not modify, trim or truncate them in any way.

newsletters_get_documents

Get a draft edition along with its newsletter, template, and article content for each section. Returns an object containing the edition, newsletter, template, and articles per section.

newsletters_getDraftEditionContent

Use this tool when the user wants to see all available labels for their company. Typical user requests: "show me all labels", "what labels do I have?", "list all tags I can use for my media lists". This is a read-only operation scoped to the authenticated user's company. Returns an array of label objects, each with an id and name. Do NOT use this tool to assign or remove labels from a media list — use mediarelations_update_medialist_labels instead.

mediarelations_get_labels_by_company

Returns all saved filter sets in the user's account. Filter sets are reusable combinations of filters (source, language, country, etc.) applicable to searches and analytics. Each result includes the filter set ID and configuration.

listening_list_filter_sets

Returns optimised searches in the user's Explore+ account, which are distinct from standard (Explore) searches returned by listening_list_searches. Optimised searches define what content is collected into the Explore+ private index. Requires workspace_id; use 'none' for account-level access. Supports optional folder filtering, pagination, and show_hidden (set to true to include searches within hidden folders).

explore_plus_list_searches

Returns all standard (Explore) searches in the user's account. Does not include Explore+ optimised searches (the custom-index collection definitions) — those come from explore_plus_list_searches. Each result includes the search ID, name, and query. Optional filters: query_type (boolean, keyword, combined) and expand_combined.

listening_list_searches

Get all draft editions for a given newsletter. Returns a JSON array of edition objects filtered to only those with status "draft".

newsletters_getDraftEditions

Get all newsletters for the authenticated company. Returns a JSON array of newsletter objects including id, name, status, and configuration.

newsletters_getCompanyNewsletters

⚠️ DEPRECATED — Do not use this tool. It duplicates the functionality of mediarelations_get_outreach_detail. Use the following tools instead: - Delivery status and open rate: mediarelations_get_outreach_detail - Specific delivery counters and rates: mediarelations_get_outreach_count_analytics - Full email body and metadata: mediarelations_get_outreach_content - Per-recipient engagement breakdown: mediarelations_get_outreach_recipients_aggregations

mediarelations_get_outreach_analytics

Use this tool when the user wants to save an outreach as a draft without sending it. Typical user requests: "save this as a draft", "create a draft outreach", "I want to prepare this email but not send it yet". All fields are optional — an empty draft can be created with no parameters. Returns a confirmation message on success. Do NOT use this tool to send or schedule an outreach — use mediarelations_schedule_outreach instead.

mediarelations_create_outreach_draft

Use this tool when the user wants to permanently delete an outreach. Typical user requests: "delete this outreach", "remove this campaign", "I want to delete distribution X". Requires the distribution ID. This action is irreversible. Returns a confirmation message on success. Do NOT use this tool to modify a scheduled outreach — use mediarelations_update_outreach instead.

mediarelations_delete_outreach_distribution

⚠️ DEPRECATED — Do not use this tool. It uses the /searchEmails endpoint internally which is not designed to fetch a single outreach by ID and may expose unintended data. Use the following tools instead: - Full email body and metadata: mediarelations_get_outreach_content - Delivery counters and rates: mediarelations_get_outreach_count_analytics - Per-recipient engagement breakdown: mediarelations_get_outreach_recipients_aggregations

mediarelations_get_outreach_detail

⚠️ DEPRECATED — Do not use this tool. It triggers an async export job and delivers results via a user notification, which is not compatible with the MCP request/response model. Use mediarelations_get_outreach_recipients_aggregations instead, which returns recipient and source engagement data synchronously.

mediarelations_get_outreach_recipient_analytics

Use this tool when the user wants to generate a personalized AI pitch for a specific journalist or contact. Typical user requests: "generate a pitch for this journalist", "write a personalized message for John Smith", "create a tailored pitch for this contact". Requires the journalist's ID; optionally accepts a draft email (userDraftContent) or a key message to guide the pitch. Returns the generated pitch text that can be used or refined in an outreach email. Do NOT use this tool to send the pitch — use mediarelations_schedule_outreach or mediarelations_create_outreach_draft instead.

mediarelations_generate_outreach_pitch

Use this tool when the user wants to send or schedule an outreach email to one or more recipients or media lists. Typical user requests: "send this outreach now", "schedule my campaign for next Monday", "send this email to my media list". Requires a sender identity (either approvedSenderId or emailGrantId) plus subject, bodyHtml, fromAddress, and userLanguage. Use sendImmediately: true to send at once, or provide a scheduledDate (must be in the future) to queue for later delivery. Returns a confirmation message on success. Do NOT use this tool to save a draft without sending — use mediarelations_create_outreach_draft instead. Do NOT use this tool to modify an already-scheduled outreach — use mediarelations_update_outreach instead.

mediarelations_schedule_outreach

Use this tool when the user wants to find or filter media contacts (journalists, editors, bloggers) in the company's Media Relations database. This is a read-only operation scoped to the authenticated user's company. Returns count, hits (contact objects with name, email, outlets, beats), and aggregation data. Use pagination (from/size, max size 100) for large result sets. Supported filters: - Free text: { type: "freeTextContact", q: "name or keyword" } - Location: { type: "locations", values: [{ "country": "United States", "countryCode": "US" }] } - Media lists: { type: "mediaLists", mediaListIds: ["list-id"], operation: "any" } - Profile type: { type: "profileType", values: ["verified", "private", "automated"] } - Beats: { type: "beats", values: [{ "children": ["beat-id"], "parent": "parent-id" }] } - Languages: { type: "languages", values: ["en", "es"] } - Email origin: { type: "emailOrigin", values: ["direct", "indirect", "user-added"] } - Source reach tiers: { type: "sourcesReachTiers", values: ["tier_1", "tier_2", "tier_3"] } - Source geo focuses: { type: "sourcesGeoFocuses", values: ["International", "Local", "National", "Regional"] } - Source media channels: { type: "sourcesMediaChannels", values: ["channel-id"] } - Contacts publishing at a source: { type: "sourceNameLookup", sourceNameLookup: "The New York Times" } Available aggregations: countriesAndRegions, beats, roles, sourcesReachTiers, languages, sourcesMediaChannels, sourcesGeoFocuses, sourcesFrequencies, sources. Do NOT use this tool to search for media outlets/publications — use mediarelations_search_sources instead. Do NOT use this tool to browse contacts within a specific media list by name — use mediarelations_search_media_list_contacts instead.

mediarelations_search_contacts

Use this tool when the user wants to browse or find contacts within a specific media list by searching the media list name. This is a read-only operation scoped to the authenticated user's company. Returns count, hits (contact objects from matching media lists), and aggregation data. Use pagination (from/size) for large lists. How it works: provide a freeTextContact filter with the media list name as the query string. The search finds media lists matching that name and returns their contacts. Example: filters: [{ type: "freeTextContact", q: "Tech Journalists" }] Do NOT use this tool for general contact search — use mediarelations_search_contacts instead. Do NOT use this tool to modify media list membership — use mediarelations_update_media_list_contacts instead.

mediarelations_search_media_list_contacts

Use this tool when the user wants to search for media lists and the contacts within those media lists. Typical user requests: "find media lists named 'tech'", "search for contacts inside my media lists", "look up journalists within my lists". Supports filtering by name (q), label (labelId), specific IDs (ids), pagination (page/size), sorting (sortBy: NAME, JOURNALISTCOUNT, CREATED; sortOrder: ASC, DESC), and options to search within list names or creator names. Returns an object with count (total results), hits (matching media lists with their contacts), and isMatchingContactNames (whether the match was on contact names), scoped to the authenticated user's company. Do NOT use this tool to search contacts across the full database — use mediarelations_search_contacts instead.

mediarelations_search_media_lists_or_contacts

Generates Meltwater boolean search queries from a natural language topic description. Returns a boolean query string suitable for Meltwater saved searches. Supported operators: AND, OR, NOT, XNOT, NEAR/n, ONEAR/n, wildcards (*, ?), field scoping (title:, ingress:, content:), and caseSensitive:(term). Recognizes core subjects/entities, synonyms, abbreviations, rebrands, and spelling variations. Does not encode temporal ranges, platform filters, sorting intent, or content type—these belong in retrieval tool optional fields. Examples: - "Tesla electric vehicles" → ("Tesla" OR "TSLA") AND ("electric vehicle" OR "EV") - "Subway restaurant" → ("Subway") NOT ("station" OR "train" OR "metro") - "Jon Stewart" → includes "Jonathan Stewart" variations - "universit*" matches university, universities, etc.

unified_retrieval_query_gen_tool

Use this tool when the user wants to find or filter media sources (publications, outlets, editions) in the company's Media Relations database. This is a read-only operation scoped to the authenticated user's company. Returns count, hits (source objects with name, reach, media list associations), and aggregation data. Use pagination (from/size, max size 100) for large result sets. Supported filters: - Free text: { type: "freeTextContact", q: "outlet name" } - Location: { type: "locations", values: [{ "country": "United States", "countryCode": "US" }] } - Beats: { type: "beats", values: [{ "children": ["beat-id"], "parent": "parent-id" }] } - Languages: { type: "languages", values: ["en"] } - Reach tiers: { type: "reachTiers", values: ["tier_1", "tier_2", "tier_3"] } - Geo focuses: { type: "geoFocuses", values: ["International", "National", "Local", "Regional"] } - Media channels: { type: "mediaChannels", values: ["channel-id"] } - Frequencies: { type: "frequencies", values: ["1", "7", "30"] } Available aggregations: beats, countriesAndRegions, reachTiers, geoFocuses, mediaChannels, languages, frequencies. Do NOT use this tool to search for individual contacts/journalists — use mediarelations_search_contacts instead.

mediarelations_search_sources

Returns aggregated metrics and statistical breakdowns for a topic across news and social platforms. Supports totals, single-dimension breakdowns, temporal trends, and two-dimension cross-tabs. Optional filters: languages, countries, sentiment, hashtags, handles, platforms, startDate/endDate (YYYY-MM-DD), savedSearchIds, filterSetIds, optimizedSearchIds, sortBy, sortOrder, limit. Put platforms, dates, scope IDs, and filters in dedicated optional fields—not in query. Supported metrics (express in query): count (default), engagement, reach, views, shares. Supported dimensions (express in query): time (daily/weekly/monthly), platform, sentiment, emotion, country, language, city, hashtags, entities, keyphrases, users, sources, comparison. Maximum 3 dimensions per query. Examples: - { query: "Tesla document count by week", platforms: ["twitter"], startDate: "2026-03-01", endDate: "2026-04-09" } - { query: "iPhone 17 engagement and reach by platform", startDate: "2026-01-01", endDate: "2026-04-09", countries: ["US"] } - { query: "Tesla vs Ford vs GM mentions by week", startDate: "2026-01-01", endDate: "2026-04-09" } - { query: "volume trends", optimizedSearchIds: [42], startDate: "2026-01-01", endDate: "2026-04-09" } Limitations: returns aggregated metrics only (not individual document content), supports totals not averages/medians, and allows at most 3 dimensions per query.

unified_retrieval_statistics_retrieval_tool

Retrieves semantically relevant news articles and social posts for a natural language query. Returns structured document objects. Optional filters: languages (ISO codes), countries (ISO codes), sentiment (positive, negative, neutral, unknown), hashtags, handles, platforms, startDate/endDate (YYYY-MM-DD), savedSearchIds, filterSetIds, optimizedSearchIds, sortBy, sortOrder, limit. Query field: semantic topic text. Put platforms, dates, saved searches, filter sets, optimised searches, languages, countries, sentiment, hashtags, handles, and sorting in their dedicated optional fields—not in query. Filters without a dedicated field (subreddits, emotions) may be included in query naturally. For saved-search-only, filter-set-only, or optimised-search-only retrieval, pass query: "*" with the corresponding ID field(s). Supported sortBy values: relevance (default), engagement, reach, views, prominence, social-echo, newsguard-rating. Examples: - { query: "Microsoft AI announcements", platforms: ["twitter"], sortBy: "engagement", startDate: "2026-04-01", endDate: "2026-04-09" } - { query: "Tesla Cybertruck", sentiment: "negative", platforms: ["reddit"], startDate: "2026-03-09", endDate: "2026-04-09" } - { query: "*", optimizedSearchIds: [42] } - { query: "*", filterSetIds: [12345], savedSearchIds: [67890] } Limitations: boolean operators (AND, OR, NOT), field-specific searches (title:, body:), numeric comparisons, and URL-based search are not supported.

unified_retrieval_document_retrieval_tool

Use this tool when the user wants to rename or update the description of an existing media list. Typical user requests: "rename my media list to 'Finance Contacts'", "update the description of this list", "change the name of my media list". Requires the mediaListKey (UUID v4) of the media list. Name and description are both optional — only the fields provided will be updated. Returns a confirmation message on success. Do NOT use this tool to create a new media list — use mediarelations_create_media_list instead. Do NOT use this tool to add or remove labels — use mediarelations_update_medialist_labels instead.

mediarelations_update_media_list

Use this tool when the user wants to add or remove contacts from one or more media lists. This is a write operation that modifies media list membership and affects all users in the company. Returns the updated media list membership result. Parameters: - contactIds: Array of contact IDs (required, max 500) - updateMediaListIds: Media list IDs to ADD the contacts to - deleteMediaListIds: Media list IDs to REMOVE the contacts from At least one of updateMediaListIds or deleteMediaListIds must be provided. Removals cannot be undone. Always confirm with the user before executing, especially when removing contacts. Do NOT use this tool to add/remove sources (editions) — use mediarelations_update_media_list_entries instead. Do NOT use this tool to delete an entire media list — use mediarelations_delete_media_list instead.

mediarelations_update_media_list_contacts

Use this tool when the user wants to add or remove both contacts and sources (editions) from media lists in a single operation. This is a write operation that modifies media list membership and affects all users in the company. Returns the updated media list membership result. Parameters: - contactIds: Array of contact IDs (optional) - editionIds: Array of source/edition IDs (optional) - updateMediaListIds: Media list IDs to ADD the entries to - deleteMediaListIds: Media list IDs to REMOVE the entries from Combined total of contactIds + editionIds must not exceed 1000. At least one of updateMediaListIds or deleteMediaListIds must be provided. Removals cannot be undone. Always confirm with the user before executing. Do NOT use this tool if only working with contacts (no sources) — use mediarelations_update_media_list_contacts instead for better clarity.

mediarelations_update_media_list_entries

Use this tool when the user wants to modify a scheduled outreach that has not been sent yet. Typical user requests: "update my scheduled outreach", "change the subject of this upcoming campaign", "edit this outreach before it sends". Requires the outreach ID. This is a full replacement — all fields (subject, bodyHtml, recipients, mediaLists, etc.) must be provided again, as any omitted field will be cleared. The sender identity (emailGrantId, approvedSenderId, fromAddress) is preserved and does not need to be re-submitted. Returns a confirmation message on success. Do NOT use this tool for outreaches that have already been sent. Do NOT use this tool to delete an outreach — use mediarelations_delete_outreach_distribution instead.

mediarelations_update_outreach

Updates an existing standard (or Explore) search by replacing its name and query together. Partial updates are not supported. Supports boolean, keyword, and combined query types.

listening_update_search

Update the documents for each section in a draft edition. Accepts an edition ID and an array of sections, where each section contains an array of document objects. Returns the updated section documents. We will need to fetch the full document details using the "newsletters_get_documents" tool before ading them with this tool. Always pass the complete, unmodified document objects returned by newsletters_get_documents directly into the sections array. Do not slim down, filter, or omit any fields from the document objects before passing them to this tool.

newsletters_updateEditionContent

Use this tool when the user wants to add or remove labels from a media list. Typical user requests: "add the 'Tech' label to my media list", "remove the 'Finance' tag from this list", "tag my media list with these labels". At least one of labelsToAdd or labelsToRemove must be provided. Use mediarelations_get_labels_by_company to retrieve valid label IDs if needed. Fetches the current labels of the media list and applies the requested changes without replacing the full label set. Returns a confirmation message on success. Do NOT use this tool to retrieve available labels — use mediarelations_get_labels_by_company instead.

mediarelations_update_medialist_labels

Returns all custom fields defined in the user's Explore+ account. Custom fields are user-defined categorisations (tag fields or multivalued fields) applied to documents in the Explore+ index. Requires a workspace_id — use account_get_workspaces to look up IDs, or pass none for account-level fields.