Signl exposes five MCP tools. Three are free on every plan, one charges only when it delivers a verified contact, and one is a paid refresh available on Unlimited. Your agent calls them by name; you do not, but knowing what each does is the fastest way to phrase a request it can answer.
The five tools at a glance
| Tool | Cost | What it does |
|---|---|---|
search_signals | Free | Search companies and buying signals, ranked by ICP score |
get_weekly_drop | Free | The hottest signals from the last 7 days |
get_credit_balance | Free | Remaining credits and current plan |
enrich_lead | 1 credit on a verified result | Turn a signal into a verified decision-maker contact |
refresh_person_signals | Paid, Unlimited only | Check for fresh person-level activity on one contact |
search_signals
Searches the Signl feed of in-market companies. Free, no credits, available on every plan, and unlimited in volume.
Some filters read previously ingested signals. Others trigger a live market-wide company search: industry, technology, employeeCountMin, employeeCountMax, departmentHeadcount, hasOpenRole, openRoleTitleContains, fundingStage and fundedWithinDays. You do not need to know which is which; passing them is enough.
Parameters
| Parameter | Type | Notes |
|---|---|---|
query | string | Free text over company name, domain or detected technology |
signalType | enum | funding, hiring, tech_adoption, company_match, job_change, promotion, tenure_milestone, person_content |
minIcpScore | 0-100 | Only signals scoring at least this |
isHot | boolean | Restrict to hot (high-ICP) signals |
fundingStage | string | seed, series_a, series_b, growth, private_equity |
fundedWithinDays | 1-365 | Combine with fundingStage; both are answered in one search |
country | string | ISO-3166 alpha-2, exactly two letters |
sinceDays | 1-365 | Event happened within N days |
technology | string | A named tool, e.g. HubSpot |
industry | string | One of 35 categories, or a recognised alias |
employeeCountMin / employeeCountMax | integer | Total headcount range |
departmentHeadcount | object | { department, min, max }. Unlimited plan only |
hasOpenRole | boolean | At least one active job posting |
openRoleTitleContains | string | Open role matching this, for example marketing |
personTitleContains | string | Person signals only. Reads cache, never charges |
maxMonthsInRole | integer | Person signals only. Use 6 for "recently changed jobs" |
contentTopic | string | Person signals only. Reads cache, never charges |
limit | 1-100 | Defaults to 20 |
Returns { ok, count, signals[] }. Each signal carries signal_id, company (name and domain), signal_type, icp_score, is_hot, observed_at, detected_at and highlights.
observed_at is when the event happened and detected_at is when Signl first saw it. Current-state matches have observed_at: null, because nothing happened; they matched your criteria. See buying signals for why that distinction matters when you rank results.
Limits. Every filter is available on every plan. departmentHeadcount does not run a live search; it narrows companies already in the feed. Keep limit modest: MCP clients cap how much a single tool result can carry, so asking for 100 rows can mean your agent silently sees fewer.
get_weekly_drop
The hottest signals from the last seven days, ten by default. Free on every plan and takes no parameters. Returns the same { ok, count, signals[] } shape as search_signals.
Use it as a standing Monday read. For anything targeted, search_signals is the better tool.
get_credit_balance
Returns { ok, credit_balance, plan }. Free, no parameters. plan is free, growth or unlimited.
enrich_lead
Resolves a signal to a verified decision-maker contact. This is the only tool in normal use that spends credits, and it charges only on success.
Parameters
| Parameter | Type | Notes |
|---|---|---|
signal_id | string | From search_signals or get_weekly_drop |
title_contains | string | Optional. Target a role, for example VP of Sales |
Returns { ok, contact, credits_remaining, cached, charged, credits_charged }. The contact record contains person_name, title, email, email_verified, linkedin_url, phone and source_provider, plus an enrichment object carrying location, seniority and employment history on the deep path.
Cost. 1 credit when the signal already lists keyPeople in its highlights, which is the cheap path, and 1 credit when a deep decision-maker search has to run. Nothing is charged when no verified email is found, when your balance is insufficient, or when a repeat request for the same signal is served from cache.
Limits. Passing title_contains always searches fresh and is never served from cache, so a role-targeted request costs a credit each time it succeeds. Attempts are metered separately from credits: see how credits work and the fair use policy.
refresh_person_signals
Explicitly checks for fresh person-level activity on one contact you have already enriched. Unlike everything above, it is paid and it is never called automatically. Only ask for it when you want an up-to-date read on one specific person.
Parameters
| Parameter | Type | Notes |
|---|---|---|
signal_id | string | A signal you have already run enrich_lead on |
include_content | boolean | Also check recent public posts. Costs more; off by default |
Returns { ok, employment_signals, content_signals, message }.
Limits. Unlimited plan only. It needs a cached contact with a LinkedIn URL, and returns an error telling you to enrich first if there is not one. It is rate-limited by a monthly cap shared across all accounts, so it can return person_signals_unavailable even on Unlimited. include_content covers public content analysis, which is a separate and heavier data category, and is only available where the deployment has enabled it.
Job change, promotion and tenure signals are also derived for free at enrichment time and readable through search_signals. Reach for this tool only when free and cached is not fresh enough.
Errors your agent may report
Every failure returns a machine-readable code your agent can act on:
| Code | What it means |
|---|---|
upgrade_required | The filter or tool needs a higher plan |
zero_balance | Not enough credits. Nothing was charged |
enrichment_miss | No verified contact found. Nothing was charged |
signal_not_found | That signal_id does not exist |
discovery_cap_reached | Person-signal refresh budget exhausted for this billing cycle |
attempt_cap_reached | Enrichment attempt cap hit |
unknown_industry | The industry value was not recognised. No search ran |
person_signals_unavailable | Person refresh is not available or is capped out |
unknown_industry is worth understanding: it means no search ran at all, so it is a filter problem rather than an empty market. The error lists the industries we do accept. Full descriptions are in error messages and what they mean.
Related
Connect your agent for setup, search companies and buying signals for how to phrase requests, and what Signl covers for the honest coverage picture.