MCP tools reference | Ocean Help Center

This page lists every tool that your AI assistant can use once it is connected to ocean.io. To connect an assistant, read Using ocean.io with AI Assistants (MCP). You never call these tools yourself. You ask in plain words and the assistant picks the right one. The names help when you want to ask for a specific tool or understand what the assistant did.

How to read the costs

The prices on this page are for current plans on unified credits. Older plans price searches at 1 credit per result or 1 credit per block of 50 results. Lookalike searches on the oldest plan cost 3 credits per result. Ask your assistant to run account_context and it tells you the exact rates for your plan.
All tools use the same credit pool as the rest of ocean.io. Lookups, counts, field lists and reads of your segmentations, committees and CRM are free.
Searches and signals do not ask first. The search, signal, recommendation and committee tools spend credits but they are marked as read only, so most AI tools will not stop to ask. Before a big search, ask for a count first. You can also tell your assistant a maximum, such as "spend no more than 20 credits on this". Search tools and the signal tools then return only as many results as fit in that budget. It does not apply to recommendations, committee people or exports.
Asks you first means that ocean.io marks the tool as one that changes something or spends credits. Most AI tools show a Confirm or Cancel prompt for those. Whether you see one depends on your AI tool.

Account and cost

Tool	What it does	Cost	Asks you first
`account_context`	Shows your credit balance, plan and pricing, connected CRM, active segmentation, webhooks and a few closed-won customer domains to use as lookalike examples. Good to run at the start of a session.	Free	No
`count_companies`	Counts the companies that match your filters and tells you the exact cost to fetch a number of them that you choose. The default is 100.	Free	No
`count_people`	Counts the people that match your filters and tells you the exact cost to fetch a number of them that you choose. The default is 100.	Free	No

Search

Tool	What it does	Cost	Asks you first
`search_companies`	Finds companies by filters. Supports lookalike search and the segment filter. Up to 10,000 results per call. The segment filter needs the Segmentation add-on. Job posting and buying signal filters need the Advanced filtering add-on.	0.2 credits per result	No
`search_people`	Finds people by title, seniority, department, location and skills. Supports lookalike search. Up to 10,000 results per call. Job posting and buying signal company filters need the Advanced filtering add-on.	0.2 credits per result	No

Nothing is free on a search through the connector. You pay from the first result. A search that returns nothing costs nothing.

Signals and account research

Tool	What it does	Cost	Asks you first
`role_changes`	Lists senior people who recently started a role at one company and whether each was hired from outside or promoted. Up to 25 people.	0.2 credits per person found	No
`why_now`	Checks 1 to 40 companies for three timing signals: a new leader, a growing team and a recent funding round. Returns the ones that fired.	0.2 credits per company found and 0.2 credits per person found. It runs one company search plus one people search for each company, so a long list adds up. Use a maximum to cap it. Companies with no signal are charged too.	No
`similar_customers`	Finds your closed-won customers that look like a given company. Needs a connected CRM with won deals. Up to 25 results.	0.2 credits per result	No
`account_brief`	Pulls together a pre-call brief for one company: profile, timing signals, similar customers, decision makers and its status in your CRM.	The profile and CRM lookup are free. With the default sizes the searches cost up to about 8 credits.	No

Contacts

Tool	What it does	Cost	Asks you first
`reveal_contacts`	Reveals verified emails and phone numbers for 1 to 25 people you already found.	1 credit per email found and 10 credits per phone found. Nothing is charged for contacts that are not found or that your organization already revealed.	Usually

Export

Tool	What it does	Cost	Asks you first
`export_companies`	Makes a CSV of up to 10,000 companies and returns a download link.	0.2 credits per company exported	Usually
`export_people`	Makes a CSV of up to 10,000 people. You pass the person ids that a people search returns.	0.2 credits per person exported	Usually
`export_companies_to_crm`	Creates or updates companies in your connected HubSpot, Pipedrive or Salesforce. Can also create deals. Up to 1,000 per call.	0.2 credits per company created or updated. Unchanged companies are free.	Usually
`export_people_to_crm`	Creates or updates people in your CRM. Up to 1,000 per call from a search result.	0.2 credits per person created. People who are only updated are free.	Usually
`export_companies_to_webhook`	Sends companies to a webhook you set up. Up to 1,000 per call. Needs webhook exports turned on for your organization.	0.2 credits per company sent	Usually
`export_people_to_webhook`	Sends people, together with their company, to a webhook. Up to 1,000 per call. Needs webhook exports turned on for your organization.	0.2 credits per person sent	Usually
`list_crm_pipelines`	Lists your CRM pipelines and stages so the assistant can pick the right one.	Free	No
`list_crm_owners`	Lists your CRM users so the assistant can set an owner.	Free	No
`list_webhooks`	Lists the webhooks set up for your organization. Needs webhook exports turned on for your organization.	Free	No

If an export does not have enough credits, nothing is exported.

Lookups and reference

All of these are free and never ask first.

Tool	What it does
`lookup_company`	Shows the full ocean.io profile of one company by domain.
`lookup_person`	Shows one person's profile by ocean.io id or LinkedIn URL or by name and company domain. It shows an email or phone only if your organization already revealed it.
`get_deals`	Reads your CRM deals by stage (won, open, lost or all), grouped by company. Up to 500 companies per call.
`list_company_fields` and `list_people_fields`	List the fields a search can return.
`list_industries` and `list_linkedin_industries`	List every industry value.
`find_industries` and `find_linkedin_industries`	Turn plain words such as "fintech" into the exact industry values for a filter.
`find_technologies`	Turn a product name such as "Salesforce" into the exact technology value for a filter.
`search_support_articles`	Searches this help center and returns up to 3 articles.

Segmentations

Tool	What it does	Cost	Asks you first
`create_segmentation`	Builds a new segmentation from 50 to 1,000 company domains. It builds in the background.	Free	Usually
`get_segmentation`	Checks a segmentation by id. Once it is ready it lists its segments with up to 100 member domains each.	Free	No
`list_segmentations`	Lists all your segmentations with their status and which one is active.	Free	No
`get_active_segmentation`	Shows your active segmentation with each segment's size, win rate, average deal value and time to close.	Free	No
`get_segment`	Shows one segment the way Discovery does, with its CRM numbers, tier counts and an optional page of its companies.	Free	No
`score_companies`	Scores up to 100 companies you name against a segmentation. Returns a score from 0 to 100, the tier and the best matching segment for each.	Free	No

A few things to know about creating a segmentation:

Only company domains are used. Other details such as owners, deal stage or revenue are ignored.
A new segmentation becomes your active segmentation only if you do not have one yet. To make a different one active, open Context studio and choose Make active in the segmentation's menu. Discovery follows the active segmentation. So does a Segment fit workflow step that has no segmentation chosen. A Recommendations workflow step uses the segmentation chosen in that step.
Your organization has a maximum number of segmentations, 10 by default. Failed and archived ones count toward it.
By default you can create 2 segmentations per minute and 20 per day.
Unlike the setup in the app, there is no preview step. The segmentation goes straight to a full build. Ask the assistant to check on it with get_segmentation until it is ready.
Searching by segment needs a scoring model on the segmentation. Without one, scoring companies returns only each company's segment and segment score. See Score definitions.

Recommendations

Tool	What it does	Cost	Asks you first
`get_recommendations`	Returns up to 100 recommended companies from your segmentation, ranked by score. You can leave out tiers or filter by CRM status.	0.2 credits per result	No
`exclude_from_recommendations`	Keeps 1 to 1,000 companies out of all later `get_recommendations` results.	Free	Usually

get_recommendations already leaves out companies that you exported or that are in a lead list. A company with a live deal in your CRM is never recommended.

The exclusion list that exclude_from_recommendations uses is separate from the exclusions in Settings. It affects only get_recommendations. Companies you exclude this way can still show up in Discovery and in the Recommendations workflow step. The assistant cannot take a company off the list again.

Buying committees

Buying committees need the Segmentation add-on. Ranking people also needs contact data in your plan. See Buying committees.

Tool	What it does	Cost	Asks you first
`get_buying_committee`	Shows a committee and its roles. Without an id it shows your primary committee.	Free	No
`buying_committee_people`	Ranks the people at 1 to 25 companies against your committee, the same way the Buying committee column in Discovery does. Returns up to 5 people per company.	0.2 credits per person returned	No
`create_buying_committee`	Creates a committee from roles you give. If you give none it starts from six standard roles. It can also build roles from your won deals if a CRM is connected.	Free	Usually
`update_buying_committee`	Renames a committee or replaces its roles or the titles it leaves out.	Free	Usually
`set_primary_buying_committee`	Makes a committee the primary one.	Free	Usually
`delete_buying_committee`	Deletes a committee. This cannot be undone.	Free	Usually

Some details:

A committee has at most 8 roles. Each role has at most 5 example titles.
Roles built from won deals need at least 20 won deals that have a contact with a job title. With fewer you get the six standard roles. The build runs in the background.
The first committee you create becomes the primary one. You cannot delete the primary committee. Make another one primary first.
A Find buying committee workflow step that names a deleted committee finds nobody. Steps that follow the primary committee are not affected.

Workflows

Tool	What it does	Cost	Asks you first
`list_workflows`	Lists your workflows with their status. Shows up to the 200 newest.	Free	No
`describe_workflow`	Explains in plain words what a published workflow does.	Free	No
`get_workflow_graph`	Reads a workflow's steps and settings. Shows the draft if there is one.	Free	No
`list_workflow_node_types` and `get_workflow_node_docs`	List the trigger and step types and the settings of each. The assistant uses them to edit workflows correctly.	Free	No
`create_workflow`	Creates an empty draft from your goal and gives you a link that opens it in the workflow builder. Your organization can have at most 200 workflows that were never published.	Free	Usually
`edit_workflow`	Changes the draft of an existing workflow: the trigger, steps and connections. Nothing is saved if a change is not valid.	Free	Usually
`publish_workflow`	Replaces the live version with the draft.	Free to publish. The runs afterwards spend credits.	Usually
`list_startable_workflows`	Lists the workflows your assistant is allowed to start and what each one needs.	Free	No
`run_workflow`	Starts a workflow in the background.	Free to start. The steps spend credits as in any run.	Usually
`get_workflow_run`	Shows the status and results of a run, with a download link when it made a file.	Free	No

Some details:

Editing never changes what is live. edit_workflow only changes the draft. The live version keeps running until you publish.
Publishing puts the workflow live at once. A scheduled workflow starts its runs and each run uses credits until you pause it. The workflow builder shows a credits warning before it publishes a scheduled workflow. The connector does not, so ask your assistant to publish only when you are ready.
Only some workflows can be started by the assistant. Open the workflow, go to Settings, switch on Let the assistant start this workflow and select Save settings. The workflow must be published first. Runs started this way show as Assistant in Runs. See Activate, pause, and run limits.
A run can only start if the workflow is live and under its run limit. If you are out of credits the run stops and get_workflow_run says why.

Help and feedback

Tool	What it does	Cost	Asks you first
`submit_data_feedback`	Lets the assistant report a bad lookalike, wrong data, a missing company or anything else, with a note of up to 2,000 characters. It saves your note with the company or person. It does not change your results.	Free	Usually

Limits you may meet

Search tools, count tools, get_recommendations and the signal tools share a limit per organization. By default it is 60 per minute and 1,000 per day. Your plan can have different limits. When you hit it the assistant sees "Too many requests".
If your credits run out a search says how many credits it needs and how many you have. A smaller number of results costs proportionally less.
Reveals can be refused when contact reveals are turned off for your organization or while an invoice is unpaid.
Anything your plan or setup does not include comes back as a plain message, for example when buying committees are not in your plan.