Tools - Botdog API

Manually maintained from apps/api/src/mcp/tools/. When a tool is added, removed, or its schema changes, update this page in the same PR.

Read tools — require `mcp.read`

`list_campaigns`

List the authenticated team’s campaigns. Optional status filter. Returns each campaign’s id, name, status, leadCount, and createdAt.

{
  "status": "ACTIVE | PAUSED | ARCHIVED | COMPLETED | CREATED  (optional)",
  "limit": "integer 1..100 (default 25)",
  "cursor": "opaque string (optional)"
}

`get_campaign`

Fetch a single campaign by id.

{ "campaign_id": "string" }

`get_campaign_statistics`

Heavy aggregation. Invitations sent/accepted, messages sent/replied, profile visits, acceptance/reply rates.

{ "campaign_id": "string" }

`get_analytics`

Account-level analytics for a period.

{
  "period": "last-7-days | last-30-days | last-90-days (default last-7-days)",
  "user_id": "string (optional)"
}

`get_analytics_daily`

Per-day breakdown for a date range (max 90 days).

{
  "start_date": "YYYY-MM-DD",
  "end_date": "YYYY-MM-DD",
  "user_id": "string (optional)",
  "campaign_id": "string (optional)"
}

`get_analytics_by_user`

Per-team-member breakdown for a period.

{ "period": "last-7-days | last-30-days | last-90-days (default last-7-days)" }

`list_users`

List the authenticated team’s members.

{ "limit": "integer 1..200 (optional)" }

`get_user`

Fetch one team member by id.

{ "user_id": "string" }

`get_team`

Fetch the authenticated team’s profile.

{}

`get_leads_from_campaign`

List leads in a campaign (team-scoped). Optional filters by campaign status and reply state. Returns id, name, linkedinProfile, company, campaignStatus, and hasReplied. Paginated.

{
  "campaign_id": "string",
  "campaign_status": "CREATED | ACTIVE | PAUSED | ERROR | ARCHIVED | COMPLETED  (optional)",
  "has_replied": "boolean (optional)",
  "limit": "integer 1..100 (default 25)",
  "cursor": "opaque string (optional)"
}

`get_lead`

Look up a single lead by lead id or LinkedIn URL. Returns profile, company, campaign status, reply state, and last message.

{
  "lead_id": "string (one of lead_id or linkedin_url required)",
  "linkedin_url": "https://… (one of lead_id or linkedin_url required)"
}

`find_leads_by_linkedin_url`

Find the lead(s) for one LinkedIn profile (team-scoped). The URL is normalized before matching, so any spelling works — http/https, with or without www., a trailing slash, or tracking parameters; Sales Navigator and private profile URLs match too. The same person can hold one lead per campaign and one per list, so this returns a list — check campaignId and campaignStatus to pick the right one before stopping a sequence.

{
  "linkedin_url": "string (LinkedIn profile URL, any spelling)",
  "campaign_id": "string (optional, narrows to one campaign)",
  "limit": "integer 1..100 (default 25)",
  "cursor": "opaque string (optional)"
}

`list_replies`

Inbox view: leads who replied (team-scoped). Returns name, lastMessage preview, repliedAt, and unread state. Full message threads are not yet exposed.

{
  "unread_only": "boolean (optional)",
  "campaign_id": "string (optional)",
  "limit": "integer 1..100 (default 25)",
  "cursor": "opaque string (optional)"
}

`list_lists`

List the team’s lead/audience lists. Returns id, name, isBlacklist, and leadCount. Paginated.

{
  "include_blacklist": "boolean (default false)",
  "limit": "integer 1..100 (default 25)",
  "cursor": "opaque string (optional)"
}

`get_list`

Fetch one lead/audience list by id. Returns name, isBlacklist, and leadCount.

{ "list_id": "string" }

`get_leads_from_list`

List leads in a lead/audience list (team-scoped). Returns id, name, linkedinProfile, and company. Paginated.

{
  "list_id": "string",
  "limit": "integer 1..100 (default 25)",
  "cursor": "opaque string (optional)"
}

`list_linkedin_accounts`

List the team’s connected LinkedIn sender accounts. Returns each account’s id, connection status, and owning user email.

{ "limit": "integer 1..200 (default 50)" }

`get_account_limits`

Daily sending caps and remaining quota for today for one connected account (seat). Read-only.

{ "account_id": "integer" }

`get_paused_activities`

List the activity types currently paused for a campaign (e.g. SEND_INVITATION). Empty when nothing is individually paused.

{ "campaign_id": "string" }

`list_snippets`

List message snippets/templates visible to you: your personal snippets plus any shared with your team. Optional status filter. Paginated.

{
  "status": "ACTIVE | ARCHIVED  (optional)",
  "limit": "integer 1..100 (default 25)",
  "cursor": "opaque string (optional)"
}

`list_webhooks`

List the team’s webhooks. Returns id, name, endpoint, and status.

{}

`get_webhook`

Fetch one webhook by id (team-scoped).

{ "webhook_id": "string" }

`get_api_setup_guide`

Integration guide for the public REST API: base URL, x-api-key auth (key prefix bd_live_), a first-request snippet in the chosen language, and the list of Botdog operations (generated from this server’s tools, each marked read or write). Unlike the other tools it does not mirror a single endpoint — it explains how to call the API from your own code.

{ "language": "curl | node | python (default node)" }

Write tools — require `mcp.write`

`add_leads_to_campaign`

Add 1–100 leads to a campaign. Adds REAL leads to a LIVE outreach campaign — only call after the user has confirmed both the campaign id and the lead list.

{
  "campaign_id": "string",
  "leads": [
    {
      "linkedinUrl": "https://… (one of linkedinUrl or email required)",
      "email": "name@example.com (one of linkedinUrl or email required)",
      "firstName": "string (optional)",
      "lastName": "string (optional)",
      "company": "string (optional)"
    }
  ]
}

`pause_campaign`

Pause a running campaign (ACTIVE → PAUSED). Affects live outreach — the assistant confirms first. If the campaign was not ACTIVE, returns its current status unchanged.

{ "campaign_id": "string" }

`resume_campaign`

Resume a paused campaign (PAUSED → ACTIVE) and re-engage outreach. Affects live outreach — the assistant confirms first. If the campaign was not PAUSED, returns its current status unchanged.

{ "campaign_id": "string" }

`stop_lead_in_campaign`

Stop a single lead’s progression in its campaign (cancels pending outreach for that lead). Identify the lead by lead_id, or by campaign_id + linkedin_url — the URL is normalized before matching, so any spelling works. If the person holds more than one lead in that campaign, the most recent one that isn’t already stopped is used; call find_leads_by_linkedin_url first if you need to pick.

{
  "lead_id": "string (or supply campaign_id + linkedin_url)",
  "campaign_id": "string (with linkedin_url)",
  "linkedin_url": "https://… (with campaign_id)",
  "reason": "string, max 500 (optional, default 'Stopped via MCP')"
}

`create_list`

Create a new empty lead/audience list. Set is_blacklist for an exclusion list. Returns the new list id.

{
  "name": "string (1..200)",
  "is_blacklist": "boolean (default false)"
}

`add_leads_to_list`

Add up to 100 leads to an existing list. Each lead needs a linkedinUrl. Returns the count of newly created leads (duplicates are skipped).

{
  "list_id": "string",
  "leads": [
    {
      "linkedinUrl": "https://… (required)",
      "name": "string (optional)",
      "company": "string (optional)",
      "location": "string (optional)",
      "title": "string (optional)"
    }
  ]
}

`delete_leads_from_list`

Delete leads from a list by lead_ids or linkedin_urls. Destructive — the assistant confirms first. Returns the number deleted.

{
  "list_id": "string",
  "lead_ids": ["string, 1..100 items (one of lead_ids or linkedin_urls required)"],
  "linkedin_urls": ["https://…, 1..100 items (one of lead_ids or linkedin_urls required)"]
}

`create_webhook`

Create a webhook that posts event notifications to your endpoint. Returns the new webhook id.

{
  "name": "string (1..200)",
  "endpoint": "https://…",
  "event_types": ["string (at least one)"],
  "campaign_ids": ["string (optional — scope to specific campaigns)"]
}

`update_webhook`

Update a webhook’s name, endpoint, and/or event types.

{
  "webhook_id": "string",
  "name": "string 1..200 (optional)",
  "endpoint": "https://… (optional)",
  "event_types": ["string (optional)"]
}

`delete_webhook`

Delete a webhook by id. Destructive — the assistant confirms first.

{ "webhook_id": "string" }

`create_campaign`

Create a campaign (name + optional start/end dates). Creates the shell only — the message sequence is built, and the campaign launched, in the app.

{
  "name": "string (1..200)",
  "start_date": "ISO 8601 datetime (optional)",
  "end_date": "ISO 8601 datetime (optional)"
}

`update_campaign`

Update a campaign’s name and/or start/end dates. Does not change the message sequence or status (use pause_campaign/resume_campaign for status). Provide at least one field.

{
  "campaign_id": "string",
  "name": "string 1..200 (optional)",
  "start_date": "ISO 8601 datetime (optional)",
  "end_date": "ISO 8601 datetime (optional)"
}

`pause_campaign_activities`

Pause specific activity types for a campaign (e.g. stop sending invitations while messages continue) without pausing the whole campaign. Affects live outreach. Reversible with resume_campaign_activities.

{
  "campaign_id": "string",
  "activity_types": [
    "PROFILE_VISIT | SEND_INVITATION | SEND_MESSAGE | SEND_INMAIL | SEND_COMPANY_PAGE_INVITATION | REACT_TO_POSTS (at least one)"
  ]
}

`resume_campaign_activities`

Resume previously paused activity types for a campaign. Affects live outreach.

{
  "campaign_id": "string",
  "activity_types": [
    "PROFILE_VISIT | SEND_INVITATION | SEND_MESSAGE | SEND_INMAIL | SEND_COMPANY_PAGE_INVITATION | REACT_TO_POSTS (at least one)"
  ]
}

`update_lead`

Update editable lead metadata (notes, custom fields, name, company). Does not change campaign/workflow status. Provide at least one field.

{
  "lead_id": "string",
  "name": "string, max 255 (optional)",
  "company": "string, max 255 (optional)",
  "status_note": "string, max 1000 (optional)",
  "custom_field_1": "string, max 1000 (optional)",
  "custom_field_2": "string, max 1000 (optional)",
  "custom_field_3": "string, max 1000 (optional)",
  "custom_attributes": { "key": "any JSON value (optional)" }
}

`create_snippet`

Create a message snippet. TEXT snippets need content; LLM snippets need prompt.

{
  "name": "string (1..200)",
  "type": "TEXT | LLM (default TEXT)",
  "content": "string, max 10000 (for TEXT snippets)",
  "prompt": "string, max 10000 (for LLM snippets)",
  "shortcut": "string, max 50 (optional)"
}

`update_snippet`

Update a snippet’s name, content, prompt, shortcut, and/or status. Provide at least one field.

{
  "snippet_id": "string",
  "name": "string 1..200 (optional)",
  "content": "string, max 10000 (optional)",
  "prompt": "string, max 10000 (optional)",
  "shortcut": "string, max 50 (optional)",
  "status": "ACTIVE | ARCHIVED (optional)"
}

`update_account_limits`

Update a connected account’s daily caps, sending days, timezone, and auto-withdraw settings. Daily caps are clamped to safe maximums (you cannot set an unsafe value). Provide at least one field. Returns the resulting limits.

{
  "account_id": "integer",
  "max_daily_invites": "integer >= 0 (optional)",
  "max_daily_messages": "integer >= 0 (optional)",
  "max_daily_inmails": "integer >= 0 (optional)",
  "max_daily_profile_visits": "integer >= 0 (optional)",
  "max_daily_company_page_invitations": "integer >= 0 (optional)",
  "max_daily_react_to_posts": "integer >= 0 (optional)",
  "enable_auto_withdrawal": "boolean (optional)",
  "invite_withdrawal_duration": "integer 1..91 (optional)",
  "active_days_of_week": ["MONDAY … SUNDAY, at least one (optional)"],
  "timezone": "IANA timezone, e.g. America/New_York (optional)"
}

​Read tools — require mcp.read

​list_campaigns

​get_campaign

​get_campaign_statistics

​get_analytics

​get_analytics_daily

​get_analytics_by_user

​list_users

​get_user

​get_team

​get_leads_from_campaign

​get_lead

​find_leads_by_linkedin_url

​list_replies

​list_lists

​get_list

​get_leads_from_list

​list_linkedin_accounts

​get_account_limits

​get_paused_activities

​list_snippets

​list_webhooks

​get_webhook

​get_api_setup_guide

​Write tools — require mcp.write

​add_leads_to_campaign

​pause_campaign

​resume_campaign

​stop_lead_in_campaign

​create_list

​add_leads_to_list

​delete_leads_from_list

​create_webhook

​update_webhook

​delete_webhook

​create_campaign

​update_campaign

​pause_campaign_activities

​resume_campaign_activities

​update_lead

​create_snippet

​update_snippet

​update_account_limits