Ranking page and one pick for a person's conditions
share_rankingRead-onlyIdempotent
Use this when: the user wants the ranking of API plans for their conditions, or a link they can open or share, and you do not need every plan in the answer. Do not use this when: you need the plans and their sentences in the answer (use search with detail or format full) or the user named the plans (use check_conditions). Returns the one plan that leads the ranking for the conditions (a plan that meets every condition, or the closest when none does), a confidence (its score out of 99), how many other plans also meet every condition, and ranking_url: the permanent address of a page that ranks every plan for these conditions with the official sentence for each. Confidence is the plan's score out of 99, the same as in the search answer; it is not a probability. The conditions are those of search. Example: 50,000 SERP searches a month with an official MCP server; the person gets one pick and a page ranking every plan.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "share_ranking"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| detail | No | summary returns one source sentence per fact; full returns every recorded fact and sentence. | summary |
| mcp_auth | No | Ways to authenticate to the provider's hosted MCP endpoint, any one of which will do: api_key, oauth. Met when the endpoint accepts at least one of them; implies a hosted endpoint. | |
| question | No | The user's words, if available. Read only for words that suggest a condition the request does not carry. | |
| needs_dpa | No | The vendor must offer a data processing agreement (DPA) to the buyer. | |
| needs_sla | No | The plan must come with a service level agreement (SLA). | |
| needs_zdr | No | Zero data retention must be usable on this plan. A provider that offers it only on a custom enterprise agreement does not meet it on its listed plans. | |
| preferred | No | Nice-to-have conditions; they do not filter, they break ties. Put a condition the person calls nice to have ("would be good", "if possible", "되면 좋겠다") here, not as a required field. | |
| providers | No | Judge only the plans of these providers (candidates you already have, for example from a web search). Give provider ids or names as listed, such as "tavily", "Brave Search API" or "You.com"; case does not matter. Names that are not providers here are listed under unknown_providers in the result. | |
| needs_soc2 | No | The provider must hold a SOC 2 report: true for Type I or Type II, "II" for Type II. | |
| needs_batch | No | The plan must transcribe recorded audio (a file or a stored recording), for speech-to-text. A plan priced for live audio only is not met. | |
| data_regions | No | Regions where data must be stored or processed, e.g. ["EU"]. Different from exit-IP countries. | |
| needs_korean | No | The service must voice Korean text (text-to-speech) or transcribe Korean speech (speech-to-text). | |
| billing_types | No | Acceptable billing: monthly_subscription (A plan with a fixed fee (or minimum commitment) billed every month.) annual_subscription (A plan paid for a year at a time.) pay_as_you_go (No plan fee; a price per unit of use, billed after use or drawn from a balance topped up with any amount.) prepaid_credits (Money paid before use: a credit pack, a balance topped up first, or a plan amount charged in advance for the period.) Free plans always qualify. | |
| monthly_pages | No | Pages per month by type: plain_html (static pages), javascript (needs rendering), premium_proxy (blocked sites that need residential/premium proxies), javascript_premium_proxy (both). | |
| needs_inbound | No | The service must receive email for the buyer and hand it on (inbound parsing, routes), for transactional email. | |
| product_types | No | Limit to these product types. Default: every type that can serve the workload. | |
| monthly_emails | No | Emails sent per month, for transactional email APIs (SendGrid, Mailgun, Postmark, Resend, Amazon SES, Brevo, Mailtrap, Loops). It is the whole workload: give it instead of monthly_pages, monthly_searches and monthly_browser_hours, not with them. Only email products can serve it; other products are out of scope. | |
| search_engines | No | Search engines whose results the plan must return, each at the plan's search price: google, bing, yahoo, yandex, baidu, duckduckgo, naver, brave (brave is Brave's own index). monthly_searches is the total over all of them. | |
| captcha_solving | No | The plan must solve CAPTCHAs for the browser sessions (the vendor does it, not the buyer own service). | |
| min_concurrency | No | Minimum number of concurrent requests (or browsers) the plan must allow. | |
| needs_streaming | No | The service must return audio in real time as it is made (streaming or a WebSocket), for text-to-speech; for speech-to-text, it must transcribe live audio as it arrives. A speech-to-text price line is per mode, so a plan priced for recorded audio only is not met. | |
| monthly_searches | No | Search requests per month (one results page each). | |
| needs_remote_mcp | No | The provider must host a remote MCP endpoint (a URL an MCP client connects to). An official server that can only be run on the buyer own machine does not meet it. | |
| proxies_included | No | The plan must include proxy traffic of the vendor (some gigabytes in the plan fee). Proxy traffic sold only per gigabyte on top of the fee, or only on another plan, does not count. | |
| search_countries | No | ISO 3166-1 alpha-2 codes of the countries whose search results the searches must return (the search engine's country setting, e.g. Google gl), e.g. ["GB","CA"]. Different from exit_ip_countries. | |
| exit_ip_countries | No | ISO 3166-1 alpha-2 codes of countries the page requests must exit from, e.g. ["US","DE"]. For search results of a country use search_countries. | |
| min_pages_per_doc | No | Pages one document may have at the most the plan allows, for document parsing. Met when the stated limit is at least this many (or the pages say there is no page limit); a plan whose pages do not state a limit is unknown. The limit of the largest way of sending (batch or asynchronous) counts. | |
| needs_diarization | No | The plan must label who spoke (speaker diarization), for speech-to-text. Where the vendor charges extra for it, the extra price is added to the monthly cost; where the pages state no price or no inclusion the plan is unknown. | |
| needs_no_training | No | An official page must say the vendor does not use the buyer's text, audio or documents to train its models without the buyer opting in. A use that is on by default with an opt-out to ask for does not count. | |
| session_recording | No | The plan must record browser sessions (video or replay) that the buyer can watch afterwards. | |
| monthly_characters | No | Characters of text voiced per month, for text-to-speech APIs (ElevenLabs, Cartesia, Deepgram Aura, OpenAI, Google Cloud, Amazon Polly, Azure, Gradium, Rime, Inworld, MiniMax, Murf, Hume). It is the whole workload: give it instead of monthly_pages, monthly_searches, monthly_browser_hours and monthly_emails, not with them. Only text-to-speech products can serve it; other products are out of scope. | |
| needs_dedicated_ip | No | The plan must come with a dedicated sending IP address, for transactional email. A dedicated IP sold only as an add-on on top of the plan, or only on another plan, does not count. | |
| needs_official_mcp | No | The provider must publish its own MCP server (hosted by it or run by the buyer), stated in its official documentation. A server only a third party published does not count. | |
| ai_extraction_pages | No | How many of the pages need their fields extracted by an AI model (from a prompt or a schema, or automatically) without writing selectors. Each page counts in one of the two extraction fields. | |
| min_pages_per_crawl | No | Pages one crawl job (from one start URL, following links) must be able to reach. A plan whose crawl has no page cap meets any number; give the size of the largest site to crawl. Different from the monthly page total. | |
| min_sending_domains | No | Sending domains the plan must let one account authenticate, for transactional email. Met when the stated limit is at least this many (or the pages say it is unlimited); a plan whose pages do not state a limit is unknown. | |
| min_session_minutes | No | Minutes one browser session must be able to run on this plan, for hosted browsers. Met when the stated longest session of the plan is at least this long; a plan whose pages do not state a session limit is unknown, and a limit the page gives only for another plan is not met. | |
| monthly_audio_hours | No | Hours of audio transcribed per month, for speech-to-text APIs (Deepgram, AssemblyAI, Speechmatics, Amazon Transcribe, Google Cloud, OpenAI). A price given per minute is multiplied by 60. It is the whole workload: give it instead of monthly_pages, monthly_searches, monthly_browser_hours, monthly_emails and monthly_characters, not with them. Only speech-to-text products can serve it; other products are out of scope. | |
| monthly_pages_total | No | Total pages per month when the split by type is not known yet. Costs and verdicts then cover every share of JavaScript-rendered pages from 0% to 100% of the total (no premium proxies), and the result lists monthly_pages under needs_input. | |
| needs_voice_cloning | No | The plan must let the account clone a voice from its own recording, for text-to-speech. Cloning limited to eligible customers, a request form or an enterprise plan does not count for a plan that is not that plan. | |
| persistent_profiles | No | The plan must keep browser profiles (login state, cookies) between sessions. | |
| search_result_types | No | Result types the parsed search response must contain: organic, ads, local_pack, knowledge_graph, people_also_ask, related_searches, shopping, news, images, videos, ai_overview. | |
| max_monthly_cost_usd | No | Monthly budget in USD before tax. Compared with listed prices; annual plans use their per-month equivalent. | |
| needs_batch_discount | No | An official page must say a batch or asynchronous way of sending documents costs less than the list price on the plan, for document parsing. The budget and the cost are judged at the list price, not at the batch price. | |
| needs_commercial_use | No | The plan must allow commercial use of the generated audio, for text-to-speech. A free plan limited to non-commercial use does not count; a plan whose pages do not say is unknown. | |
| needs_no_min_billing | No | An official page must say audio is billed by the second (or an increment of seconds) with no minimum billed duration per request, for speech-to-text. A page that says nothing about rounding is unknown. | |
| needs_webhook_events | No | The plan must send webhook events to the buyer's server (the vendor calls an address of the buyer when something happens). | |
| monthly_browser_hours | No | Browser time per month in hours, for hosted browsers (Browserbase, Browserless) billed by browser time. It is the whole workload: give it instead of monthly_pages, monthly_searches and browser_seconds_per_page, not with them. Only browser products can serve it; other products are out of scope. | |
| needs_signed_webhooks | No | The plan must deliver webhooks that the buyer can verify by a signature (a signing secret or a signed endpoint). | |
| max_overage_usd_per_1k | No | The most the plan may charge for each 1,000 emails beyond its included volume, in USD, for transactional email. A plan whose extra price is not published as a per-1,000 figure is unknown. | |
| min_log_retention_days | No | Days the plan must keep the logs or events of sent email where the account can read them, for transactional email. Longer retention sold as an add-on does not count. | |
| monthly_document_pages | No | Pages of documents parsed per month, for document-parsing APIs (LlamaParse, Reducto, Unstructured, Mistral OCR, LandingAI, Amazon Textract, Google Document AI, Azure Document Intelligence, Datalab, Mathpix, Mindee, Nanonets, Upstage). A price given per credit is multiplied by the credits one page costs. It is the whole workload: give it instead of monthly_pages, monthly_searches, monthly_browser_hours, monthly_emails, monthly_characters and monthly_audio_hours, not with them. Only document-parsing products can serve it; other products are out of scope. | |
| needs_table_extraction | No | The service must return the tables of a page as structure (rows and cells), not only the text, for document parsing. | |
| search_returns_content | No | The search response itself must carry the text of the result pages (extracted content), not only titles, links and snippets. | |
| min_requests_per_minute | No | Minimum request rate the plan must allow, per minute. | |
| browser_seconds_per_page | No | Browser time per page in seconds, for headless-browser products billed by time. Every plan must then serve pages that take this long: a hosted browser does, a request-based API only when one request may run that long. | |
| realtime_search_required | No | Search results must be returned in real time (not through a queue). | |
| target_errors_not_billed | No | Error responses from the target site (e.g. 404) must not be billed. | |
| needs_recurring_free_tier | No | The plan must be usable every month without paying (a free plan with a monthly allowance or a monthly free credit). | |
| failed_requests_not_billed | No | Requests that fail on the provider side (timeouts, blocks, 5xx) must not be billed. A flat monthly price for unlimited requests meets it, since no request is billed on its own; when only success-based billing will do, use only_successful_requests_billed. | |
| structured_extraction_pages | No | How many of the pages must come back as JSON fields rather than HTML or text, by any method the plan offers (CSS or XPath selectors, a schema, or AI). When the fields must be found without writing selectors, use ai_extraction_pages instead; each page counts in one of the two. | |
| only_successful_requests_billed | No | Billing must count successful requests only: each successful request is charged (or draws credits) and failed ones cost nothing. A flat monthly price for unlimited requests does not meet it, since the price is the same whatever succeeds. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| best | No | The one plan the answer names: the best plan for the conditions, or the closest when none meets every condition. | |
| as_of | Yes | ||
| answer | Yes | ||
| counts | No | ||
| needs_input | Yes | ||
| ranking_url | No | The permanent address of the page for a person that ranks every plan for these conditions with the official sentences. Give it to the user. It opens after a server restart and holds no personal data. | |
| zero_result | No | ||
| engine_version | No | ||
| unknown_providers | No | ||
| others_meeting_all | No | How many other plans also meet every condition. |