Find related ads
find_similar_adsFind ads related to one source ad by an explicit overlap basis: fanpage (same Facebook page_id) or domain (same exact landing_domain). This is entity overlap, NOT visual similarity of the material; use find_similar_creatives for that. The source ad is excluded from data, but pagination.total remains the upstream overlap-candidate count before that exclusion; source_excluded and total_semantics make this explicit instead of fabricating an adjusted exact total. Metadata only, cursor-paginated. QUOTA: 1 MCP credit per delivered row (default page 20). PRICING: on paid plans ×1 after 500 MCP credits/month; one-time consent via accept_pricing_terms; before calling, get the maximum debit from estimate_cost (free) and tell the user.
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": {
"ad_id": "<ad_id>",
"basis": "<basis>"
},
"name": "find_similar_ads"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ad_id | Yes | source ad UUID from search_ads | |
| basis | Yes | overlap basis: fanpage (same Facebook page_id) or domain (same exact landing_domain) | |
| limit | No | maximum metadata rows (default 20, maximum 200; 1 MCP credit per delivered row) | |
| cursor | No | pagination cursor returned by the previous call |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | ||
| error | No | Present only when isError is true: machine-readable failure. The human explanation stays in content. | |
| params | No | Request parameter echo: applied = parameters that shaped this result; normalized = parameters rewritten before applying (alias, type coercion, resolved id); ignored = parameters that were accepted but NOT applied, with the reason. | |
| pagination | No | ||
| addon_hints | No | Add-on modules that have additional data for objects of this result (no prices, no paid values). subscription_status=active: the account has the module — use its normal path. Do not push a purchase the user did not ask about. | |
| basis_value | No | ||
| source_ad_id | No | ||
| source_excluded | No | ||
| total_semantics | No | ||
| similarity_basis | No |