Documentation / MCP / news_similar_to_id
news_similar_to_id
POSThttps://mcp.oppalerts.com/mcptool: news_similar_to_id
Lists the News Index documents most semantically similar to a document identified by its document_id.
What it does
The tool takes the id of one News Index document in document_id, a string of digits. Take the id from a result of a News Index search. It returns that document as document, and the 100 documents nearest in semantic similarity as results, nearest first. Copies of the same text on other sites are not merged: each copy is a separate result. found is true when the index has the document and its vector. When found is false, document holds empty values, and results is an empty list.
Use it to go from one page that you found to more pages like it.
All news_ and prospects_ tools of one account share one daily count of index searches, and the OppAlerts website uses the same count. 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 2 parameters, with each part of an object counted one by one. Send them as the arguments of the tool call.
campaignint, optional, 1 to 4294967295- Optional. The campaign id, a whole number from 1 to 4294967295, from
campaigns_list. When you send it, the campaign must be in this account, and a result whose site is an organization of the campaign has an org key that tells what the site is to the campaign. When you do not send it, no result has an org key. document_idstring of digits, required- Required. The document id, from a search result: a decimal string of 1 to 20 digits. It is a string because the value exceeds the largest whole number that JavaScript can represent exactly.
Rules
- found is true when the index has the document and its vector.
- When found is false, document holds empty values, and results is an empty list.
- No field has a default value.
- A field that you do not send applies no condition.
Example
Call
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "news_similar_to_id",
"arguments": {
"campaign": 3,
"document_id": "1152921504611003120"
}
}
}
Response
The full sample answer.
{
"found": true,
"document": {
"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"
}
]
}
}
}
},
"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"
}
]
}
}
}
}
]
}
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.
- 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.no_campaign(HTTP 404 in the API): the campaign is not a campaign of your account.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.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/similar_to_id HTTP/1.1
Host: api.oppalerts.com
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json
{
"campaign": 3,
"document_id": "1152921504611003120"
}
Read the API page of news_similar_to_id.