Tools reference

The Homie MCP server exposes fifteen lookup tools to every token: thirteen are read-only, while search_warm_paths and list_person_network can automatically queue background warmness updates for user tokens. Tokens with the mcp:write scope also receive six explicit write tools, for twenty-one in total. Those six tools are not registered for a token with only mcp:read.

• Organization-scoped tools search the whole network of the organization that owns the token. They work with user MCP tokens and organization API keys.
• User-scoped tools act on the authenticated user personally: their own connections, prioritized list, target lists, and re-score runs. They need a user MCP token, and organization API keys are rejected.
• Directory company tools query Homie's shared company directory. They read existing company records.

Every tool returns structured content. The result carries a typed structuredContent payload, validated against the tool's declared outputSchema, alongside a JSON text fallback. MCP clients that support structured output get typed results instead of parsing JSON out of a text blob.

Start with get_icp when prospecting. Warmness ranks reachability, not fit, so results ordered by warmness alone put colleagues ahead of prospects.

Already-requested people. Candidate lists (company-mode search_warm_paths, list_person_network) exclude anyone the organization has already requested an intro to, reporting the count as excludedIntroRequested; includeIntroRequested: true brings them back. Lookup tools (person-mode search_warm_paths, search_people, get_person) never filter, but annotate results with introRequested, introStatus, introRequestedBy, and introRequestedAt. Every status counts as already asked, including LOST — the status travels with the annotation so you can judge whether a stale request is worth retrying.

get_icp

Read the organization's Ideal Customer Profile. Takes no arguments.

Returns { configured, icp? }. When configured is false the organization has not set one up; ask the user who they are targeting rather than guessing. Otherwise icp carries name, description, positions, industries, locations, companySize, companyType, additionalContext, skipWarmConnections, isAutoGenerated, sourceWebsite, and updatedAt.

The ICP is stored text, not a scorer: read it and filter the people other tools return against it yourself. Nothing is scored server-side, so there is no added latency or model cost per query.

list_person_network

List the people a given person is connected to, warmest first. This answers "who does Kalle know", "warm paths from Kalle's network", and "who could Kalle introduce us to".

Use this directly to explore a person's network. search_sales_opportunities matches prospects, not connectors, and is only relevant when looking for existing sales recommendations.

Returns { person, connections, totalCount, returnedCount, limit, offset, nextOffset, hasMore, excludedIntroRequested, coverage }. Each connection carries position, currentCompany, city, country, warmness, and warmnessSignals, which is what you need to qualify them against the ICP.

Check coverage before describing the result

coverage says how complete the network is, which is a different question from how big it is. Most people in the graph are derived or none, so an empty list is usually not evidence that someone has no connections.

The subject must be in the organization's network: either an org member, or someone an org member is directly connected to. Anyone else returns a scope error rather than turning this into a directory lookup over every person in Homie.

Do not reach for alternatives that look similar. Enumerating list_sales_opportunities and filtering for a connector is slow and misses anyone the agent has not surfaced. search_network's asUserId only accepts org members who hold a Homie account, so it cannot express "as this person in our network".

Background warmness updates

With a user token, this lookup can automatically queue AI re-scoring for up to ten low-score connections. The background worker persists updated warmness scores and breakdowns; the lookup returns current evidence without waiting. This also works with mcp:read alone. Low or missing warmness is unverified relationship evidence, not proof of a warm introduction.

search_warm_paths

Find warm intro paths from anyone in the organization to a target person OR to anyone at a target company.

Returns { outcome, message, fallbackConnections, prospect, company, paths[], totalCount, returnedCount, limit, offset, nextOffset, hasMore, excludedIntroRequested, coverage }. For person mode company is null; for company mode prospect is null and each path entry has a target field with the employee being reached.

Compact connector responses

Both the structured result and JSON text fallback contain the same compact page, limited to 12,000 UTF-8 bytes per payload. Raw scoring-factor breakdowns and image URLs are omitted. Person identities, positions, companies, ordered hops, scores, signal labels and intro-request annotations remain available. An unscored hop stays null; it is not evidence of a warm relationship.

limit is an upper bound, not a guaranteed page length. If the page is shortened, returnedCount reflects the paths actually included, hasMore is true, and nextOffset points to the first undisplayed path. Keep the same filters and pass that value as offset; do not add limit yourself. totalCount and graph coverage retain their original meaning. Use get_person for additional profile details instead of requesting larger path pages.

Read outcome before calling anything a warm intro

A list of paths alone is not proof of a warm route, so gate on outcome === "found" or on a path's own warmness. On no_paths and target_not_found the result carries a human-readable message. When the organization has any warm contacts, it also carries fallbackConnections: the organization's warmest reachable people, warmest first. Relay the message and offer those people as the closest existing contacts. Never present them as a path to the requested target, and never report an empty result as "they know no one".

coverage reports capped, candidatePeople, candidatePeopleCap, secondDegreeEdgesCapped, and thirdDegreeEdgesCapped. capped is true when the employee candidate cap or a second- or third-degree edge cap was reached. Check it before implying the list is complete.

Scoping the search

By default this searches from every member of the organization, which answers "can we reach them". Narrowing the source answers the everyday variants:

scope: "me" needs a user-scoped MCP token; an organization API key has no personal network and gets a scope error telling it to use fromUserIds instead. fromUserIds accepts either id kind because warm paths return fromUserId while every other tool returns person ids. People in the network who have no Homie account cannot be a source at all — use list_person_network for them.

excludedIntroRequested counts employees withheld in company mode because an intro was already requested. It is always 0 in person mode, which annotates the prospect with introRequested instead of filtering: you named one person, so answering "no paths" because an intro is already in flight would hide more than it helps.

Each path includes:

• fromUserId / fromUserName: the org member whose perspective enables the path.
• connector: the intermediary person.
• viaAdvocate: for an advocate_second_degree path, the accepted advocate the org member can ask first. In that path type, connector is the advocate's connection to the target.
• connectionType: one of:
  • direct: the org member knows the target.
  • second_degree: the org member knows someone who knows the target.
  • third_degree: a three-hop route, returned only when maxHops is 3.
  • advocate: an advocate of the org member knows the target.
  • advocate_second_degree: an advocate of the org member knows someone who knows the target.
• hops: the route as an ordered list of edges. Each hop has from, to, warmness, and signals.
• warmness: overall score for ranking (0-100).
• userToConnectorWarmness + userToConnectorSignals: score and human-readable signal labels for the source-side relationship. For a route via an advocate, use the ordered hops to identify each relationship precisely.
• connectorToProspectWarmness + connectorToProspectSignals: score and labels for the connector to target hop (set for non-direct paths).

The *Signals arrays and each hop's signals contain human-readable evidence (e.g. "Working together at Acme", "3 mutual connections", "Both reacted to each other's posts"). Raw *Breakdown objects remain optional in the output schema for compatibility, but compact MCP responses omit them. REST responses and native Homie cards are unaffected.

Results are ranked in this order: direct, advocate, 2nd-degree, advocate 2nd-degree, 3rd-degree. Within each tier, warmer paths appear first. When the target is found but has no paths, the matched prospect or company is still returned, with outcome: "no_paths".

Background warmness updates

With a user token, this lookup can automatically queue AI re-scoring for up to ten low-score connections. The background worker persists updated warmness scores and breakdowns; the lookup returns current evidence without waiting. This also works with mcp:read alone. Low or missing warmness is unverified relationship evidence, not proof of a warm introduction.

check_warmness_rescore

Read the current status and persisted results of an AI warmness run queued by search_warm_paths or list_person_network. This status check returns immediately without waiting, queuing work or changing scores. User-scoped: organization API keys have no re-score runs, so they always get status: "none".

Answer the initial lookup with its current results. Call this tool only when the user later asks for an update; do not poll. Without runId, it only considers runs started in the last 15 minutes.

Returns { status, completed, failed, total, results }.

completed and total count re-scored pairs. Each entry in results has name, previousScore (the formula score before re-scoring), newScore (the AI-refined score, now saved on the connection), and a short summary. It lists up to 20 successfully re-scored people, highest newScore first.

list_first_degree_connections

List the authenticated user's own first-degree LinkedIn connections. Unlike the search tools, this one is scoped to the token's user personally — organization API keys are rejected.

Returns { connections, totalCount, returnedCount, limit, offset, nextOffset, hasMore }. Each connection has person fields only: id, name, linkedinId, position, currentCompany. Ordered by name. Connections whose warmness hasn't been computed yet are included — warmness is enrichment, not a membership filter.

list_second_degree_connections

People connected to one of your own first-degree contacts, but whom you don't know directly. Each entry names the bridging connector, so you can see who could introduce you. User-scoped: organization API keys are rejected.

Returns { connections, totalCount, returnedCount, limit, offset, nextOffset, hasMore, scannedBridges, capped }, ordered warmest first. Each connection carries viaConnector (the bridging contact) and warmness for the connector→person edge.

Coverage is bounded. Second-degree networks can be very large, so results cover a bounded number of warm edges per connector. Without viaConnectorId, the bridge set is bounded too. totalCount counts people within that window, scannedBridges says how many contacts were considered, and capped: true means a bridge or per-connector edge cap was reached. This signal applies with or without viaConnectorId.

add_prioritized_connection

Add one of your own first-degree connections to your prioritized list, meaning the people you consider key relationships. This tool writes. User-scoped: organization API keys are rejected.

Prioritizing has four effects:

1. The person moves to the top of your priority list.
2. A strong priority signal enters that connection's warmness score, which is recalculated immediately.
3. If the person also has a Homie account, they are promoted to an accepted advocate, so they appear as an available connector.
4. Homie queues one LinkedIn sync of that person's network on your Homie extension. It uses your saved search filters, the same ones your automatic sync uses. It is skipped if a sync through them is already queued or running, or if their network was searched in the last 7 days. The sync needs the extension online and takes a few minutes. New warm paths through the person appear later in search_warm_paths.

Returns { id, connectionId, priority, alreadyPrioritized, person, warmness }. alreadyPrioritized is true when the person was already on the list. A retry after the person reaches the top is a no-op: it does not increment priority or rerun side effects. warmness is the score after the initial recalc, or the stored score on a no-op; it is omitted if scoring failed, which does not undo the write.

Only your own first-degree connections can be prioritized. Passing a second-degree person, or someone else's connection, returns a validation error.

remove_prioritized_connection

Remove one of your first-degree connections from your prioritized list. This tool writes. User-scoped: organization API keys are rejected.

Removing withdraws the priority signal from that connection's warmness score, which is recalculated immediately. It does not revoke advocate status that was granted when the person was prioritized.

Returns { connectionId, removed, person, warmness }. removed is false when the person was not on your list, in which case nothing changes and warmness is the stored score. Only call it when the user explicitly asks to unprioritize someone.

get_person

Fetch one person by their Homie person id (as returned by search_people, search_warm_paths, or list_first_degree_connections).

Returns { found, person? }. person includes profile fields, current company, network size, a degree field ("first" or "second"), and — on first-degree connections — the org's warmness, warmnessBreakdown, and human-readable warmnessSignals. found is false when the person isn't in the organization's network (1st or 2nd degree), so the tool never reveals that someone exists outside your graph.

list_sales_opportunities

List the organization's stored sales recommendations — prospects Homie discovered, each with an ICP evaluation, buying-intent signals, key insights, and the best warm intro path. Org-scoped: works with both user MCP tokens and organization API keys.

Returns { opportunities, totalCount, returnedCount, limit, offset, nextOffset, hasMore }. Prospects working at your own company are excluded. A path whose connector is one of your own org members is not surfaced as bestPath (it would just echo back what the org already knows); when every path for an opportunity is internal, the opportunity is still returned with bestPath omitted.

search_sales_opportunities

Search the sales prospects Homie has already recommended, by keyword. Use it for questions like "any opportunities at fintechs?" or "opportunities matching Acme", when the user wants existing sales recommendations. Org-scoped: works with both user MCP tokens and organization API keys.

It does not scan the network or create new opportunities. For open-ended prospecting use search_network, and for a route to one specific person or company use search_warm_paths.

Returns the same payload as list_sales_opportunities, with the same exclusions. The only differences are that query is required and results sort by relevancy by default.

search_network

Natural-language search across the organization's combined network. Best for queries like "VPs of Eng at Series C startups in NYC".

When query describes what the wanted companies do or run (for example "companies that run their own cloud or bare-metal infrastructure"), people whose current company's own description says so come first, followed by looser fits that match the other criteria only. The text note after the result says how many of each are on the page and lists any requirement Homie could not apply.

The response includes totalCount and returnedCount. Results come warmest-first, one page per call. A person's warmness is their best introduction route's strength; a route through a connector is as warm as its weaker hop. When the response has nextOffset, call again with the same arguments and offset set to it to get the next matches; no nextOffset means there are no further matches in the network.

Responses are compact: instead of raw warmness factor breakdowns, each connector in connectionSources carries readable connectorToProspectSignals (how the connector knows the person) and networkOwnerToConnectorSignals (how you or your teammate know the connector), and image URLs are omitted. When fewer than limit people on a page have an introduction route, the search reads further into the network to fill it. A page may still hold fewer results than limit to stay within the response size budget; always continue with nextOffset. A short text note after the result says in plain words whether more people match and how to fetch them.

The person, company, industry and position exclusions are applied while a page is chosen, so excluded people never use up a page. Connector exclusions remove routes after the page is chosen, so that page can hold fewer people.

The search uses the same semantic engine as the Homie app's own search page and falls back to a simpler keyword search when that is unavailable or returns nothing. The response carries a fallback object explaining any downgrade, so read it rather than assuming which search ran.

get_path_details

The numbers behind one introduction route from a search_network result: each hop's stored warmness score, readable signals and the full factor breakdown (mutual connections, time worked or studied together, emails, meetings, reactions and each factor's score). Fetch it for the routes you want to explain, not for every result.

Returns found and hops[], each with from, to, warmness, signals and breakdown. found: false (with a message) means the route can't be verified for your organization, for example when the route's owner isn't a member or no longer holds the first hop.

search_people

Substring search across people in the network (1st-degree direct connections + 2nd-degree by default).

Returns { results: [...] }. Each result includes a degree field ("first" or "second"), a warmness score, and a warmnessBreakdown object with the factors behind the score.

search_companies

Search Homie's company directory by name, industry, or HQ location. This is a directory lookup, not a warm-path search.

get_company

Fetch one company from Homie's directory. This is a directory lookup, not a warm-path search; use search_warm_paths with prospectCompany to reach people there.

Returns { found, company? }. The company carries id, companyId, name, industry, headquartersLocation, minSize, maxSize, and logoUrl when available. Unknown ids return found: false rather than an error.

list_target_lists

List your own target lists, most recently updated first. User-scoped: organization API keys are rejected.

Takes no arguments. Returns { targetLists }; each summary contains id, name, companyCount, unmatchedCompanyCount, createdAt, and updatedAt. Use the list's id as targetListId with get_target_list or one of the target-list write tools.

companyCount counts companies linked to Homie's company directory. unmatchedCompanyCount counts imported company names that have not yet matched a directory record.

get_target_list

Read one of your own target lists and page through its matched companies. User-scoped: organization API keys are rejected.

Returns { found, targetList? }. The target list includes its summary fields plus companies, totalCount, returnedCount, limit, offset, nextOffset, and hasMore. Each company carries its Homie id, LinkedIn companyId, name, industry, and headquarters when available. Lists that do not belong to the authenticated user return found:false.

create_target_list

Create a new, empty target list that you own. This tool writes. User-scoped: organization API keys are rejected.

If you already own a list with exactly this name, no duplicate is created and that list is returned instead, so a retry is safe. Follow up with add_company_to_target_list to add companies. Only call it when the user asks for a new list, or asks to add companies to a list that list_target_lists shows does not exist.

Returns { created, targetList }. created is false when the existing list was returned.

rename_target_list

Rename one of your own target lists. Requires mcp:write; other users' lists and organization API keys are rejected. It does not create a list or change membership.

Returns { action: "rename", changed, targetList }. Repeating the existing name returns changed:false.

add_company_to_target_list

Add one company to one of your own target lists. Requires mcp:write; other users' lists and organization API keys are rejected. Resolve the list with list_target_lists and the company with search_companies before the requested write. It does not create a company or create, rename or empty a list.

Returns { action: "add_company", changed, targetList }. An existing membership returns changed:false.

add_companies_to_target_list

Add up to 20 companies to one of your own target lists and start LinkedIn discovery of warm paths to them. Requires mcp:write; other users' lists and organization API keys are rejected. Use it when you agree to it, typically after search_warm_paths found no warm path to a company.

Returns { createdList, targetList, companies: [{ input, status, companyId, company, candidates }], discovery }. Each company's status is added, already_in_list, not_found or ambiguous. A name is added only when one company clearly matches: the exact name with a verified LinkedIn ID and by far the most known employees. Otherwise it returns ambiguous with up to five candidates and adds nothing for that entry; choose one and pass its companyId. discovery.status is queued, nothing_to_sync, not_requested, unavailable or failed, with counts of companies queued, already searched for this list, and waiting for a verified LinkedIn company ID.

Discovery runs one LinkedIn people search for the added companies through your Homie extension: first with your saved filters, then once with only the company filter if nobody was found. It needs the extension online and takes minutes; new paths then appear in search_warm_paths. Companies already searched for the list are not searched again.

remove_company_from_target_list

Remove one company's membership from one of your own target lists. Requires mcp:write; other users' lists and organization API keys are rejected. Resolve the list and company before the requested write, using get_target_list when current membership is needed. It does not delete the company or list or remove other members.

Returns { action: "remove_company", changed, targetList }. An absent membership returns changed:false.

Resources

Every tool hands back ids. Rather than re-running a search to turn an id back into a record, read it directly:

All four return application/json. Person and opportunity resources outside your organization's reach return a found:false payload rather than erroring, so they do not confirm the existence of records you cannot access. Company lookup uses the shared company directory.

These are addressable lookups rather than enumerable collections, so the templates don't support listing. Enumerate with the paginated tools instead.

Prompts

warm-intro-brief

The workflow the server exists for. Give it a prospect (LinkedIn handle, full name, or company) and it drives search_warm_paths + get_person, then briefs you on:

• who to ask — the connector and the org member who owns that relationship,
• why the path works — quoting the warmness signal labels verbatim rather than paraphrasing them,
• how to ask — a short message grounded in the actual shared context,
• alternatives — the next-best path, when it's a genuinely different route.

It instructs the model never to invent a connector, signal, or score, and to say so plainly when no path exists.