Documentation / MCP / news_brand_link_gap
news_brand_link_gap
POSThttps://mcp.oppalerts.com/mcptool: news_brand_link_gap
Lists News Index pages that link to your competitors, on sites that link to none of your own sites.
What it does
The tool finds the link gap on the News Index. A result is a page that
links to at least one competitor of the campaign, on a site that links to
none of your own sites. Each result has competitors_linked: the
first host of each competitor organization that the page links to. The Rules section below gives 3 facts about the
test of which sites already link to your sites.
Use sections and link_types to choose which page
sections and which link types count as a link.
All news_ and prospects_ tools of one account
share one daily count of index searches. Only one index search runs at a
time. account_calls_left shows
the searches that are left today.
Connect
claude mcp add --transport http oppalerts https://mcp.oppalerts.com/mcp
The first call opens a browser window for the OppAlerts login. Connect an AI Agent has the details.
Parameters
The tool has 45 parameters, with each part of an object counted one by one. Send them as the arguments of the tool call.
campaignint, required, 1 to 4294967295- Required. The campaign id, a whole number from 1 to 4294967295, from
campaigns_list. The campaign must be in this account. A result whose site is an organization of the campaign has an org key that tells what the site is to the campaign. published_daysint, optional, 1 to 90- Optional. Keep the pages published in the last N days, a whole number from 1 to 90. Not sent: any time. Refused together with
published_from,published_to,indexed_from, orindexed_to. sectionslist of strings, optional- Optional. The page sections where a qualifying link can be: article, nav, comments. Not sent: all 3. An unknown value is refused.
link_typeslist of strings, optional- Optional. The link types that qualify: follow, nofollow, sponsored, ugc. Not sent: all 4. An unknown value is refused.
similarity_targetnone | campaign | similarity_text | saved_opportunity, required- Required. The vector: what the pages must be semantically similar to.
none: no vector, and the other fields alone find the pages.campaign: the market description of the campaign.similarity_text: the text insimilarity_text.saved_opportunity: the similarity text of the saved opportunity insimilarity_target_opportunity. A target that has no text yet is refused. With a vector, each result has asimilarity_scorefrom 0 to 100. similarity_target_opportunityint, required in some cases, 1 to 4294967295- Required when
similarity_targetissaved_opportunity, and refused with any othersimilarity_target. The id of a saved opportunity of the campaign, a whole number from 1 to 4294967295, fromcampaigns_saved_opportunities. The saved opportunity must have a similarity text. An id that is not in the campaign answers HTTP 404,opportunity_not_found. similarity_textstring, required in some cases, at most 20000 characters- Required when
similarity_targetissimilarity_text, and refused with any othersimilarity_target. The text the pages must be semantically similar to, at most 20,000 characters. A text of only spaces is refused. similarity_score_minint, optional, 1 to 100- Optional, and refused when
similarity_targetisnone. The leastsimilarity_scorea result must have, a whole number from 1 to 100. Not sent: no minimum. title_querystring, optional, at most 500 characters- Optional. Words the title must have, at most 500 characters. It takes these search operators: AND, OR, MAYBE, NEAR/N, and NOTNEAR/N in capitals, the Negation operator (-), the Phrase search operator, the Proximity search operator (~N), the Exact form modifier (=), the IDF boost modifier (^N), the Wildcard operator (* at the end of a word), and Grouping with parentheses (one level). A wrong use is refused with a sentence that names the field. The full list is in Advanced Search Operators. At most 20 words or phrases: a text with more is refused, and nothing is cut. A text with no word or phrase, such as only OR or only spaces, is refused. Not sent: no title words.
body_querystring, optional, at most 500 characters- Optional. Words the body must have, at most 500 characters, with the same rules as
title_query. Not sent: no body words. title_body_joinand | or, required in some cases- Required when you send both
title_queryandbody_query, and refused when you send one of them or none.and: a page must match both.or: a page must match one of them. published_fromstring, optional, at most 10 characters- Optional. The first published day, inclusive, as YYYY-MM-DD in UTC: a day that exists, 1990-01-01 or later. Refused: a text in another form, and a
published_fromafterpublished_to. Refused together withpublished_days. Not sent: no first day. published_tostring, optional, at most 10 characters- Optional. The last published day, inclusive, as YYYY-MM-DD in UTC: a day that exists, 1990-01-01 or later. Refused together with
published_days. Not sent: no last day. indexed_fromstring, optional, at most 10 characters- Optional. The first day a page was added to the index, inclusive, as YYYY-MM-DD in UTC: a day that exists, 1990-01-01 or later. Refused: a text in another form, and an
indexed_fromafterindexed_to. Refused together withpublished_days. Not sent: no first day. indexed_tostring, optional, at most 10 characters- Optional. The last day a page was added to the index, inclusive, as YYYY-MM-DD in UTC: a day that exists, 1990-01-01 or later. Refused together with
published_days. Not sent: no last day. pr_domain_minint, optional, 0 to 100- Optional. Keep the pages whose domain PageRank is at least this value, a whole number from 0 to 100. 0 applies no minimum. Not sent: no minimum. Refused when it is above
pr_domain_max. pr_domain_maxint, optional, 1 to 100- Optional. Keep the pages whose domain PageRank is at most this value, a whole number from 1 to 100. 100 applies no maximum, the same as not sent: a page with no domain PageRank stays in the results. 0 is refused. Not sent: no maximum.
pr_host_minint, optional, 0 to 100- Optional. Keep the pages whose host PageRank is at least this value, a whole number from 0 to 100. 0 applies no minimum. Not sent: no minimum. Refused when it is above
pr_host_max. pr_host_maxint, optional, 1 to 100- Optional. Keep the pages whose host PageRank is at most this value, a whole number from 1 to 100. 100 applies no maximum, the same as not sent: a page with no host PageRank stays in the results. 0 is refused. Not sent: no maximum.
prot_domain_minint, optional, 0 to 1000000- Optional. Keep the pages whose domain PRoT is at least this value, a whole number from 0 to 1000000. PRoT (PageRank over Time) is the sum of the monthly PageRank values of the domain. 0 applies no minimum. Not sent: no minimum. Refused when it is above
prot_domain_max. prot_domain_maxint, optional, 1 to 1000000- Optional. Keep the pages whose domain PRoT is at most this value, a whole number from 1 to 1000000. PRoT (PageRank over Time) is the sum of the monthly PageRank values of the domain. 0 is refused. Not sent: no maximum.
prot_host_minint, optional, 0 to 1000000- Optional. Keep the pages whose host PRoT is at least this value, a whole number from 0 to 1000000. PRoT (PageRank over Time) is the sum of the monthly PageRank values of the host. 0 applies no minimum. Not sent: no minimum. Refused when it is above
prot_host_max. prot_host_maxint, optional, 1 to 1000000- Optional. Keep the pages whose host PRoT is at most this value, a whole number from 1 to 1000000. PRoT (PageRank over Time) is the sum of the monthly PageRank values of the host. 0 is refused. Not sent: no maximum.
link_counts_minobject, optional- Optional. The least number of outbound links of each link type in each page section: {"article"|"nav"|"comments": {"follow"|"nofollow"|"sponsored"|"ugc": n}}. A result must have at least n links of that type in that section. Send only the sections and the link types that you want. Not sent: no minimum.
link_counts_min.articleobject, optional- Optional. The article section of the page.
link_counts_min.article.followint, optional, 0 to 4294967295- Optional. The least number of follow links in that section, a whole number of 0 or more. 0 applies no minimum.
link_counts_min.article.nofollowint, optional, 0 to 4294967295- Optional. The least number of nofollow links in that section, a whole number of 0 or more. 0 applies no minimum.
link_counts_min.article.sponsoredint, optional, 0 to 4294967295- Optional. The least number of rel=sponsored links in that section, a whole number of 0 or more. 0 applies no minimum.
link_counts_min.article.ugcint, optional, 0 to 4294967295- Optional. The least number of rel=ugc links in that section, a whole number of 0 or more. 0 applies no minimum.
link_counts_min.navobject, optional- Optional. The navigation section of the page.
link_counts_min.nav.followint, optional, 0 to 4294967295- Optional. The least number of follow links in that section, a whole number of 0 or more. 0 applies no minimum.
link_counts_min.nav.nofollowint, optional, 0 to 4294967295- Optional. The least number of nofollow links in that section, a whole number of 0 or more. 0 applies no minimum.
link_counts_min.nav.sponsoredint, optional, 0 to 4294967295- Optional. The least number of rel=sponsored links in that section, a whole number of 0 or more. 0 applies no minimum.
link_counts_min.nav.ugcint, optional, 0 to 4294967295- Optional. The least number of rel=ugc links in that section, a whole number of 0 or more. 0 applies no minimum.
link_counts_min.commentsobject, optional- Optional. The comments section of the page, where visitors add content.
link_counts_min.comments.followint, optional, 0 to 4294967295- Optional. The least number of follow links in that section, a whole number of 0 or more. 0 applies no minimum.
link_counts_min.comments.nofollowint, optional, 0 to 4294967295- Optional. The least number of nofollow links in that section, a whole number of 0 or more. 0 applies no minimum.
link_counts_min.comments.sponsoredint, optional, 0 to 4294967295- Optional. The least number of rel=sponsored links in that section, a whole number of 0 or more. 0 applies no minimum.
link_counts_min.comments.ugcint, optional, 0 to 4294967295- Optional. The least number of rel=ugc links in that section, a whole number of 0 or more. 0 applies no minimum.
type_scoreslist of objects, optional, 1 to 20 items- Optional. The types a result must score on, 1 to 20 items. Each item is an object with an
opportunity_typeor acontent_type, and itstype_score_min. A result must pass every item. A type named 2 times is refused. Not sent: no type filter. A result of this tool has notype_scoreskey: onlynews_searchandprospects_searchanswertype_scores, with the score of each type that the call sends. type_scores[].opportunity_typestring, optional- An opportunity type as <group>/<type>, for example advertising/newsletter-ads, from
types_opportunity_types. An item has anopportunity_typeor acontent_type, not both. A type that does not exist is refused. type_scores[].content_typestring, optional- A content type, for example blogs, from
types_content_types. An item has acontent_typeor anopportunity_type, not both. A type that does not exist is refused. type_scores[].type_score_minint, required, 1 to 100- Required. The least type score the page must have for this type, a whole number from 1 to 100. 0 is refused.
sortrelevance | similarity | indexed | published, required- Required. The order of the results.
relevance: the strongest match first, of the brand search and oftitle_queryandbody_querywhen you send them.similarity: the nearest in semantic similarity first; refused whensimilarity_targetisnone.indexed: the newest day added to the index first.published: the newest published day first. results_limitint, optional, 1 to 1000, not sent: 100- Optional. The maximum number of results to return, a whole number from 1 to 1000. Not sent: 100. A number above the maximum of your plan is refused, and the error gives that maximum.
Rules
- 3 facts about the test of which sites already link to your sites:
published_daysalso limits the pages that this test reads;results_limitapplies before the test, so fewer results thanresults_limitcan come back; and the test reads the News Index. similarity_targetis required: sendnonefor no vector.similarity_textis required withsimilarity_targetsimilarity_text, andsimilarity_target_opportunitywithsaved_opportunity; each one is refused with anothersimilarity_target.similarity_score_minandsortsimilarityare refused withsimilarity_targetnone.title_body_joinis required when you send bothtitle_queryandbody_query, and refused otherwise.sortrelevanceworks with notitle_queryand nobody_query: the brand search is a match of its own, and relevance orders by it.- A from date after its to date is refused, and so is a minimum above its maximum.
- When the search cannot run, because the campaign has no competitor with a website, the call is refused with
cannot_run(HTTP 409) and a sentence that says why. It uses no daily search. - A date field together with
published_daysis refused. partialis true when more than 15,000 pages match a search with a vector:resultsthen comes from only part of the matches.- With
similarity_targetnone,partialis always false. - When
partialis true, make the search more specific: use more exact words, a higher minimum PR, a higher minimum type score, or a shorter date range. - No field has a default value, except
results_limit: 100 when you do not send it. - A field that you do not send applies no condition.
Example
Call
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "news_brand_link_gap",
"arguments": {
"campaign": 3,
"published_days": 30,
"similarity_target": "none",
"pr_domain_min": 10,
"sort": "published"
}
}
}
Response
The full sample answer.
{
"organizations": [
{
"hosts": [
"grand-resorts.example"
]
},
{
"hosts": [
"cozyinns.example"
]
}
],
"partial": false,
"results": [
{
"id": "1152921504611003120",
"url": "https://cityguide-example.org/advertise/media-kit",
"host": "cityguide-example.org",
"document_type": "page",
"published_at": "2026-05-10T00:00:00Z",
"indexed_at": "2026-08-17T21:00:00Z",
"pr_host": 39,
"prot_host": 678,
"pr_domain": 61,
"prot_domain": 861,
"similarity_score": 46.8,
"relevance_weight": 1247.0,
"org": {
"relationship": "org_publisher"
},
"page": {
"title": "Advertise with City Guide: media kit",
"snippet": "Reach 400,000 monthly readers planning weekend trips. Sponsorship and hotel placements available.",
"link_counts": {
"article": {
"follow": 12,
"nofollow": 3,
"sponsored": 2,
"ugc": 0
},
"nav": {
"follow": 34,
"nofollow": 0,
"sponsored": 0,
"ugc": 0
},
"comments": {
"follow": 0,
"nofollow": 0,
"sponsored": 0,
"ugc": 0
}
},
"meta": {
"favicon": "https://cityguide-example.org/favicon-32.png",
"feeds": [
"https://cityguide-example.org/feed"
],
"contact": [
"https://cityguide-example.org/contact"
]
},
"sections": {
"article": {
"links": [
{
"url": "https://grand-resorts.example/awards",
"text": "Grand Resorts",
"title": "",
"rel": [
"nofollow"
],
"org": {
"relationship": "org_competitor"
}
}
],
"emails": [
"press@cityguide-example.org"
],
"phones": [
"+1 555 0100"
],
"service_accounts": [
{
"service": "linkedin",
"username": "cityguide",
"label": "City Guide",
"url": "https://linkedin.com/company/cityguide"
}
]
},
"nav": {
"links": [
{
"url": "https://partner-example.com/",
"text": "Our partner",
"title": "Partner",
"rel": [
"sponsored"
],
"org": {
"relationship": "org_partner"
}
}
],
"emails": [
"hello@cityguide-example.org"
],
"phones": [
"+1 555 0101"
],
"service_accounts": [
{
"service": "twitter",
"username": "cityguide",
"label": "",
"url": "https://x.com/cityguide"
}
]
},
"comments": {
"links": [
{
"url": "https://reader-blog-example.net/trip-notes",
"text": "my trip notes",
"title": "",
"rel": [
"ugc"
],
"org": {
"relationship": "org_partner"
}
}
],
"emails": [
"comments@cityguide-example.org"
],
"phones": [
"+1 555 0102"
],
"service_accounts": [
{
"service": "reddit",
"username": "cityguide",
"label": "",
"url": "https://reddit.com/u/cityguide"
}
]
}
}
},
"competitors_linked": [
"cozyinns.example",
"grand-resorts.example"
]
}
]
}
The example shows every key.
Fields of the response
organizationslist- The organizations of the campaign, each with its
hosts. resultslist- One item for each page.
results[].competitors_linkedlist of strings- The first host of each competitor organization that the page links to, the same text as
hosts[0]of that organization inorganizations.
Each item of results has these fields:
id,url,host,document_type- The document id (a string of digits), its URL, its host, and its document type: page, podcast, or video.
published_at,indexed_at- The time the page was published, and the time it was added to the index, as ISO 8601 text in UTC, for example 2026-05-10T00:00:00Z.
pr_host,prot_host,pr_domain,prot_domain- The PageRank and the PRoT of the host of the page and of its domain. PRoT (PageRank over Time) is the sum of the monthly PageRank values.
similarity_score- With a vector, how near the page is in semantic similarity to the vector, from 0 to 100.
type_scores- This tool answers no
type_scoreskey. Onlynews_searchandprospects_searchanswer it, when the call sendstype_scores. relevance_weight- The relevance weight of the page.
org- What the site of the page is to the campaign, in
org.relationship:org_owned_brand,org_competitor,org_partner, ororg_publisher. Left out when the site is not an organization of the campaign. page- The page
title, asnippet(the first 400 characters of the body),link_countsfor each section (article,nav, andcomments) and each link type (follow,nofollow,sponsored, andugc),meta(the favicon, the feeds, and the contact pages), andsections: the outboundlinks,emails,phones, andservice_accountsfound in each section. Each link hasurl,text,title,rel, andorgwhen the linked site is an organization of the campaign.
Errors
The tool is strict. It checks each call before it runs the search:
- An unknown field is refused, and the error names the field.
- A bad value is refused, and the error names the field: the wrong type, a value out of its range, a value that is not in its list of values, or an empty text, list, or object. To send no value, leave the field out.
- A
title_queryorbody_querywith no word or phrase, such as only OR or only spaces, is refused. - A
title_queryorbody_querywith a formatting error, a wrong use of one of the search operators, is refused with a sentence that names the field and the error. The query is not searched. - An error about the format of a call, such as a refused field, names the field. Its message ends with one sentence: "Read the documentation at https://oppalerts.com/docs for the correct format." Every other error has only its own sentence.
An error returns as a tool result with isError true. Its text starts with the error code. An example: a call that sends days, a field that this tool does not have.
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "bad_param: days is not a field of this tool. Read the documentation at https://oppalerts.com/docs for the correct format."
}
],
"isError": true
}
}
bad_param(HTTP 400 in the API): a field is unknown, missing, empty, of the wrong type, out of its range, or not one of its values, or the call breaks a rule above. Aresults_limitabove the maximum of your plan is refused too.no_campaign(HTTP 404 in the API): the campaign is not a campaign of your account.opportunity_not_found(HTTP 404 in the API): the saved opportunity is not in the campaign.search_stopped(HTTP 422 in the API): the search took more than 10 seconds and was stopped. The message says how to make the search more specific. A stopped search counts as 1 search.one_at_a_time(HTTP 429 in the API): another index search of the account is running. Wait a few seconds and send the call again.cannot_run(HTTP 409 in the API): the search cannot run now, for example the campaign has no organization of that relationship, or similarity_target is campaign and the campaign has no Campaign vector yet. The sentence says why. The call uses no daily search.daily_limit(HTTP 429 in the API): the account has used all of its index searches for today.backend_error(HTTP 502 in the API): the search server did not answer, or its answer could not be read. Send the call again later. The call counts as 1 search.
Limits
- The tool draws from the one daily count of index searches that every news_ and prospects_ tool of the account shares.
- Only one index search runs at a time per account: a call made while another one runs is refused (HTTP 429,
one_at_a_time), so wait a few seconds and try again. account_calls_leftshows the counts.- A search that takes more than 10 seconds is stopped and answers HTTP 422,
search_stopped, with a sentence that says how to make it more specific. - A stopped search counts as 1 search.
- A call that is refused uses no daily search.
Same data in the API
POST /v1/news/brand_link_gap HTTP/1.1
Host: api.oppalerts.com
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
"campaign": 3,
"published_days": 30,
"similarity_target": "none",
"pr_domain_min": 10,
"sort": "published"
}
The API page is POST /v1/news/brand_link_gap.