HeyLead

Overview Schema Source Related Servers Discussions Admin

contacts

Destructive

Search, browse, and manage your entire prospect base across campaigns, including LinkedIn search, enrichment, tagging, and lifecycle stages.

Instructions

Search, browse, and manage your global contact base.

One master record per person across all campaigns. View full interaction
history, add tags/notes, track lifecycle stages, and build reusable
prospect pools for future campaigns. Also search LinkedIn directly
for people without creating a campaign.

Args:
    action: What to do:
        "list"    — List contacts with optional filters (default)
        "search"  — Search contacts by name, company, or title
        "view"    — View full cross-campaign history for one contact
        "tag"     — Add a tag (or remove with '-tag_name')
        "note"    — Add a note to a contact
        "stage"   — Update lifecycle stage
        "stats"   — Contact base dashboard stats
        "export"  — Export contacts as table, CSV, or JSON
        "linkedin_search" — Search LinkedIn directly by name/company/title
        "link"    — Resolve a campaign's contact rows against the contact base
                    by name, so rows imported without a LinkedIn id pick one
                    up. Dry run unless dry_run=False.
        "enrich" — Enrich contacts with full LinkedIn profiles + posts
        "my_connections" — Search your 1st-degree LinkedIn connections (locally synced, guaranteed 1st degree)
    query: Search text for 'search', 'linkedin_search', and 'my_connections' actions.
        For 'enrich': search query to find contacts to enrich.
        For 'linkedin_search' the query is passed to LinkedIn as KEYWORDS,
        matched literally — a company name, a job title, a person's name, or a
        combination such as 'Acme Corp CTO' or 'Jane Doe'. A natural-language
        question ('who is the CTO of Acme?') is sent through unchanged and
        usually comes back empty, so prefer keywords. Nothing is filtered out
        locally. An empty result and a failed search are reported in different
        words, so a "no matches" line means LinkedIn really returned nobody
        rather than "the search broke".
        The profile and posts fetches this triggers are paced: they used to go
        out back to back and LinkedIn rate-limited them, so the call now spends
        up to a fixed wall-clock budget waiting between fetches and prints how
        much of it went on waiting. Expect tens of seconds.
    contact_id: Global contact ID for view/tag/note/stage actions.
    lifecycle_stage: Filter by stage (prospect/contacted/connected/engaged/customer/lost)
        or target stage for 'stage' action.
    tag: Tag to add/remove for 'tag' action, or filter for 'list'/'search'.
    note: Note text for 'note' action.
    min_fit_score: Minimum fit score filter (0.0-1.0).
    limit: Max results to return (default 25). For 'linkedin_search' this is
        capped at 25 per call because every result costs a profile fetch and a
        posts fetch; a result list says so when your limit was capped.
    format: Output format for 'export': 'table', 'csv', or 'json'.
    campaign_id: Campaign whose contact rows to resolve, for the 'link' action.
    match: How 'link' pairs campaign rows with contact base records. Only
        'name' is supported (exact, ignoring case and extra spaces).
    dry_run: For 'link' — True (the default) lists every row it would change
        and writes nothing. Pass False to apply.
    connected_since: For 'my_connections' — only people who became a
        1st-degree connection on or after this date (YYYY-MM-DD).
    connected_before: For 'my_connections' — only people who became a
        1st-degree connection before this date (YYYY-MM-DD). Connections
        synced before dates were recorded have no date and match neither
        filter; the result line says how many those are.

Input Schema

TableJSON Schema

Name	Required	Default
`tag`	No
`note`	No
`limit`	No
`match`	No	name
`query`	No
`action`	No	list
`format`	No	table
`dry_run`	No
`contact_id`	No
`campaign_id`	No
`min_fit_score`	No
`connected_since`	No
`lifecycle_stage`	No
`connected_before`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.10.375Sep 18, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description goes far beyond the annotations, disclosing rate limiting and pacing behavior for linkedin_search ('spends up to a fixed wall-clock budget waiting between fetches... Expect tens of seconds'), the dry-run default and apply behavior for 'link', the cap on 'limit' at 25 for linkedin_search, and the edge case where connections synced before dates were recorded match neither date filter and are counted in the result line. It also explicitly states that an empty result and a failed search are reported in different words, which is crucial for interpreting results. No contradiction with the readOnlyHint=false, destructiveHint=true annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is lengthy but appropriately so for a tool with 11 actions and 14 parameters. It is well-structured with an opening summary followed by a clear Args block, and each line earns its place by adding operational detail. It could be slightly tighter, but the verbosity is justified by the complexity and the need to communicate important behavioral caveats.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity, the description is exceptionally complete. It covers all actions, all parameters, defaults, side effects, rate limiting, and edge cases. Since an output schema exists, return-value explanation is unnecessary, and the description focuses on what the agent needs to call the tool correctly. The only minor gap is that the 'enrich' action is not detailed beyond its query parameter, but this is negligible against the completeness elsewhere.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has zero description coverage, so the description carries full responsibility for all 14 parameters. It does this thoroughly in the Args section: each parameter is explained with its purpose, defaults, and action-specific nuances, such as query being passed to LinkedIn as keywords, match supporting only 'name' with exact case-insensitive matching, dry_run defaulting to true and writing nothing, and connected_since/connected_before affecting only dated connections. This fully compensates for the schema's lack of descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with specific verbs and a resource: 'Search, browse, and manage your global contact base.' It then explains the unique value proposition: one master record per person across all campaigns, with full interaction history, tags, notes, lifecycle stages, and prospect pools, plus direct LinkedIn search without creating a campaign. This clearly distinguishes it from campaign-specific and other sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for when to use each action, such as 'view' for full cross-campaign history and 'linkedin_search' for searching LinkedIn directly without a campaign. It implies alternatives between actions (e.g., 'search' for internal contacts vs 'linkedin_search' for external), though it never explicitly states 'use this tool instead of X' or lists exclusions. The action-level guidance is strong enough for an agent to pick the right route.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.