Topline OS MCP — Tool reference

Verify the Topline OS Private Integration Token works and return basic location info. Call this first to confirm setup.

No parameters.

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_ping",
    "arguments": {}
  }
}

Generic passthrough to any Topline OS API v2 endpoint. Use this when no dedicated tool fits. Provide the path (e.g. "/contacts/" or "/opportunities/pipelines") and HTTP method. If the path or query needs a locationId and you don't provide one, the configured sub-account location is used automatically. Returns the parsed JSON response.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_request",
    "arguments": {
      "method": "GET",
      "path": "string"
    }
  }
}

End-to-end setup verification for Topline OS MCP. Confirms the Private Integration Token is valid, resolves the location, and probes every major CRM scope: core (contacts, conversations, opportunities, calendars, workflows, forms, surveys, users, custom fields, custom values, tags, medias) + marketing OS surfaces (social planner, ad publishing for Facebook / Google / LinkedIn, email campaigns + templates, agent studio). Returns a structured pass/fail report so you can guide the user to fix any missing scopes. Call this immediately after a client finishes setup.

No parameters.

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_setup_check",
    "arguments": {}
  }
}

Add one or more tags to a contact.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_add_contact_tags",
    "arguments": {
      "contactId": "string",
      "tags": [
        "string"
      ]
    }
  }
}

Enroll a contact in a workflow.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_add_contact_to_workflow",
    "arguments": {
      "contactId": "string",
      "workflowId": "string"
    }
  }
}

Create a new contact. At minimum provide a name or email or phone. Custom fields go in customFields as {id, value} pairs.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_create_contact",
    "arguments": {
      "firstName": "string",
      "lastName": "string"
    }
  }
}

Permanently delete a contact. Irreversible.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_delete_contact",
    "arguments": {
      "contactId": "string"
    }
  }
}

Fetch a single contact by ID. Returns all standard fields and custom fields.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_get_contact",
    "arguments": {
      "contactId": "string"
    }
  }
}

List all notes on a contact.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_list_contact_notes",
    "arguments": {
      "contactId": "string"
    }
  }
}

List all tasks for a contact.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_list_contact_tasks",
    "arguments": {
      "contactId": "string"
    }
  }
}

Remove a contact from a workflow.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_remove_contact_from_workflow",
    "arguments": {
      "contactId": "string",
      "workflowId": "string"
    }
  }
}

Remove one or more tags from a contact.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_remove_contact_tags",
    "arguments": {
      "contactId": "string",
      "tags": [
        "string"
      ]
    }
  }
}

Search contacts by free-text query (name, email, phone) and/or tag. Returns up to 100 per call with a cursor for pagination.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_search_contacts",
    "arguments": {
      "query": "string",
      "tags": [
        "string"
      ]
    }
  }
}

Update fields on an existing contact.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_update_contact",
    "arguments": {
      "contactId": "string"
    }
  }
}

Create a contact, or update the existing one if email/phone matches. Use this when you're not sure whether the contact already exists.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_upsert_contact",
    "arguments": {
      "firstName": "string",
      "lastName": "string"
    }
  }
}

Create a new conversation with a contact (rarely needed — send_message usually creates one implicitly).

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_create_conversation",
    "arguments": {
      "contactId": "string"
    }
  }
}

Fetch a single conversation thread including recent messages.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_get_conversation",
    "arguments": {
      "conversationId": "string"
    }
  }
}

List messages in a conversation.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_get_messages",
    "arguments": {
      "conversationId": "string"
    }
  }
}

Search conversations for the sub-account. Filter by contact, status, or query.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_search_conversations",
    "arguments": {
      "contactId": "string",
      "query": "string"
    }
  }
}

Send a message (SMS, Email, WhatsApp, or Facebook/Instagram DM) to a contact. The contact must already exist.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_send_message",
    "arguments": {
      "contactId": "string",
      "type": "SMS"
    }
  }
}

Create a new opportunity in a pipeline stage, associated with a contact.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_create_opportunity",
    "arguments": {
      "pipelineId": "string",
      "pipelineStageId": "string",
      "contactId": "string",
      "name": "string"
    }
  }
}

Delete an opportunity.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_delete_opportunity",
    "arguments": {
      "opportunityId": "string"
    }
  }
}

Fetch a single opportunity by ID.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_get_opportunity",
    "arguments": {
      "opportunityId": "string"
    }
  }
}

List all opportunity pipelines in the sub-account with their stages.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_list_pipelines",
    "arguments": {
      "locationId": "string"
    }
  }
}

Search opportunities. Filter by pipeline, stage, status, contact, or free text. PAGINATION: the cursor is COMPOUND — to advance past page 1 you must send BOTH `startAfter` and `startAfterId` from the previous response's `meta` object. Sending only one silently returns the same page.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_search_opportunities",
    "arguments": {
      "query": "string",
      "pipelineId": "string"
    }
  }
}

Update an opportunity — move stages, change value, mark won/lost, etc.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_update_opportunity",
    "arguments": {
      "opportunityId": "string"
    }
  }
}

Book an appointment on a calendar for a contact.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_create_appointment",
    "arguments": {
      "calendarId": "string",
      "contactId": "string",
      "startTime": "string"
    }
  }
}

Cancel and delete an appointment.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_delete_appointment",
    "arguments": {
      "appointmentId": "string"
    }
  }
}

Delete a calendar. All future appointments on this calendar are cancelled. Past appointments are retained as historical records.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_delete_calendar",
    "arguments": {
      "calendarId": "string"
    }
  }
}

Get the full calendar definition (availability rules, team members, slot duration, etc.).

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_get_calendar",
    "arguments": {
      "calendarId": "string"
    }
  }
}

Get available time slots for a calendar within a date range (ms epoch).

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_get_calendar_slots",
    "arguments": {
      "calendarId": "string",
      "startDate": 0,
      "endDate": 0
    }
  }
}

List all calendars configured on the sub-account.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_list_calendars",
    "arguments": {
      "locationId": "string"
    }
  }
}

Update an appointment (reschedule, change status, reassign).

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_update_appointment",
    "arguments": {
      "appointmentId": "string"
    }
  }
}

Update a calendar's name, description, slot duration, availability, team members, or event title. Pass only the fields you want to change. The calendar must already exist — calendar CREATE is not available under PIT (marketplace OAuth only).

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_update_calendar",
    "arguments": {
      "calendarId": "string"
    }
  }
}

Create a task associated with a contact.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_create_task",
    "arguments": {
      "contactId": "string",
      "title": "string",
      "dueDate": "string"
    }
  }
}

Delete a task.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_delete_task",
    "arguments": {
      "contactId": "string",
      "taskId": "string"
    }
  }
}

Update a task — change title, body, due date, completion status.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_update_task",
    "arguments": {
      "contactId": "string",
      "taskId": "string"
    }
  }
}

Create a note on a contact.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_create_note",
    "arguments": {
      "contactId": "string",
      "body": "string"
    }
  }
}

Delete a note.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_delete_note",
    "arguments": {
      "contactId": "string",
      "noteId": "string"
    }
  }
}

Update the body of a note.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_update_note",
    "arguments": {
      "contactId": "string",
      "noteId": "string",
      "body": "string"
    }
  }
}

Create a new custom field on the sub-account. After creation, the returned `id` can be referenced when setting custom-field values on contacts or opportunities. For SINGLE_OPTIONS / MULTIPLE_OPTIONS / RADIO / CHECKBOX fields, supply `options` as an array of {label, value} pairs.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_create_custom_field",
    "arguments": {
      "name": "string",
      "dataType": "string"
    }
  }
}

Delete a custom field. This removes the field definition but does not affect contact/opportunity rows that already have a value stored — those become orphaned data accessible only via raw_payload.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_delete_custom_field",
    "arguments": {
      "customFieldId": "string"
    }
  }
}

Get details of a single custom field.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_get_custom_field",
    "arguments": {
      "customFieldId": "string"
    }
  }
}

List all custom fields configured on the sub-account (for contacts and opportunities). Useful before creating/updating contacts with custom data.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_list_custom_fields",
    "arguments": {
      "locationId": "string"
    }
  }
}

Update a custom field's name / options / placeholder. Pass only the fields you want to change.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_update_custom_field",
    "arguments": {
      "customFieldId": "string"
    }
  }
}

Create a new sub-account custom value. Returns the created record including its id and the auto-generated merge-tag key ({{custom_values.<slug>}}).

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_create_custom_value",
    "arguments": {
      "name": "string",
      "value": "string"
    }
  }
}

Delete a sub-account custom value. Any merge tags referencing the deleted key will render empty in workflows/messages.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_delete_custom_value",
    "arguments": {
      "customValueId": "string"
    }
  }
}

Get details of one custom value by id.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_get_custom_value",
    "arguments": {
      "customValueId": "string"
    }
  }
}

List all sub-account custom values. Use before setting workflow merge tags or composing messages that reference {{custom_values.X}}.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_list_custom_values",
    "arguments": {
      "locationId": "string"
    }
  }
}

Update an existing custom value's name and/or value. Pass only the fields you want to change.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_update_custom_value",
    "arguments": {
      "customValueId": "string"
    }
  }
}

List all workflows in the sub-account. Returns workflow IDs, names, and status.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_list_workflows",
    "arguments": {
      "locationId": "string"
    }
  }
}

Create a new tag on the sub-account. Tags are referenced by NAME from contact.tags JSON arrays, so use a concise human-readable name.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_create_tag",
    "arguments": {
      "name": "string"
    }
  }
}

Delete a tag from the sub-account. Contacts that were tagged lose the tag reference; contact records themselves are not touched.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_delete_tag",
    "arguments": {
      "tagId": "string"
    }
  }
}

List all tags available on the sub-account.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_list_tags",
    "arguments": {
      "locationId": "string"
    }
  }
}

Rename a tag. Existing contacts tagged with the old name get the rename transitively.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_update_tag",
    "arguments": {
      "tagId": "string",
      "name": "string"
    }
  }
}

Fetch a single user by ID.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_get_user",
    "arguments": {
      "userId": "string"
    }
  }
}

List users on the sub-account. Useful for finding user IDs to assign tasks, opportunities, or appointments.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_list_users",
    "arguments": {
      "locationId": "string"
    }
  }
}

Fetch full details of the current sub-account (location) — name, address, timezone, business info.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_get_location",
    "arguments": {
      "locationId": "string"
    }
  }
}

List submissions for a specific form.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_list_form_submissions",
    "arguments": {
      "formId": "string"
    }
  }
}

List all forms on the sub-account.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_list_forms",
    "arguments": {
      "locationId": "string",
      "limit": 0
    }
  }
}

List submissions for a specific survey.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_list_survey_submissions",
    "arguments": {
      "surveyId": "string"
    }
  }
}

List all surveys on the sub-account.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_list_surveys",
    "arguments": {
      "locationId": "string",
      "limit": 0
    }
  }
}

Manage connected social-media accounts for a location. Actions: `list` (returns connected accounts + groups), `delete` (disconnect an account by id). Note: connecting (oauth) lives on the topline_social_oauth tool.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_social_account",
    "arguments": {
      "action": "list"
    }
  }
}

Bulk-import social posts via CSV. Workflow: upload → assign_accounts → finalize. Actions: `upload` (POST a CSV file or URL in the body), `list` (all imports), `get` (single import by id), `assign_accounts` (link the upload to one or more connected accounts), `finalize` (PATCH to schedule all posts from the import), `delete` (remove an import).

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_social_csv",
    "arguments": {
      "action": "upload"
    }
  }
}

Connect a social-media account via OAuth. Three-step flow per platform: `start` returns a URL the user must open in a browser to authorize; `get_accounts` fetches the accounts/pages available after the user authorizes (call with the `accountId` returned by the platform's callback); `attach_accounts` finalizes the connection by attaching one or more of those accounts/pages to this location. Supported platforms: `facebook`, `instagram`, `linkedin`, `twitter` (deprecated — X access is best-effort).

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_social_oauth",
    "arguments": {
      "action": "start",
      "platform": "facebook"
    }
  }
}

Manage scheduled and published social media posts across connected accounts (Facebook, Instagram, LinkedIn, X, Google Business Profile, TikTok). Actions: `list` (search posts by date / account / status, POSTs the filter body), `get` (single post by id), `create` (schedule a new post; provide `accountIds`, `summary`, optional `scheduleDate`, attachments, etc. in the body), `update` (edit an existing post), `delete` (remove a single post), `bulk_delete` (remove multiple posts by `postIds`). Pass `action` plus the action's required params.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_social_post",
    "arguments": {
      "action": "list"
    }
  }
}

Manage AI agents in the CRM's Agent Studio. Actions: `list` (all agents for the location), `get` (single agent with metadata + versions by `agentId`), `create` (new agent + initial draft version — provide the agent config in `body`), `update_metadata` (rename or update description on an existing agent), `delete` (remove an agent and all its versions), `execute` (run an agent synchronously with input params — provide `agentId` + `body`).

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_agent",
    "arguments": {
      "action": "list"
    }
  }
}

DEPRECATED — use topline_agent for new work. Legacy public-api endpoints kept for back-compat with older integrations. Actions: `list` (all agents), `get` (single agent by `agentId`), `execute` (synchronous run with input).

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_agent_legacy",
    "arguments": {
      "action": "list"
    }
  }
}

Manage individual versions of an agent — drafts and the production-promoted version. Actions: `update` (PATCH details of a specific version by `versionId` — system prompt, tools, model, persona, voice, etc.), `publish` (promote a draft version to production).

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_agent_version",
    "arguments": {
      "action": "update",
      "versionId": "string"
    }
  }
}

Manage email campaigns (broadcasts / scheduled sends). Actions: `list` (all campaigns for the location), `get` (single campaign by `campaignId`), `create` (new campaign — provide `body` with name, subject, recipients, template/html, etc.), `update` (edit an existing campaign), `delete` (remove a campaign), `send` (send immediately), `schedule` (schedule for a future timestamp — pass `sendAt` in body). NOTE: endpoint path is best-effort (/campaigns/); live PIT smoke test pending.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_email_campaign",
    "arguments": {
      "action": "list"
    }
  }
}

List recipients of an email campaign (with per-recipient delivery / engagement status if available). Action: `list` by `campaignId`.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_email_campaign_recipients",
    "arguments": {
      "action": "list",
      "campaignId": "string"
    }
  }
}

Aggregated performance stats for an email campaign — sends, opens, clicks, bounces, unsubscribes. Action: `get` by `campaignId`.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_email_campaign_stats",
    "arguments": {
      "action": "get",
      "campaignId": "string"
    }
  }
}

Manage saved email templates. Actions: `list` (all templates for the location), `get` (single template by `templateId`), `create` (new template — provide `body` with name, subject, html, etc.), `update` (edit an existing template by `templateId`), `delete` (remove a template). NOTE: endpoint path is best-effort (/emails/builder/); live PIT smoke test pending. If a call returns 404, update the path or open an issue.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_email_template",
    "arguments": {
      "action": "list"
    }
  }
}

Manage Facebook ad creatives. Actions: `upsert` (create or update — provide ad in `body`), `pause`, `resume`, `duplicate`, `delete` (by `adId`).

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_fb_ad",
    "arguments": {
      "action": "upsert"
    }
  }
}

Manage connected Facebook ad accounts. Actions: `list` (all connected), `get` (by `adAccountId`), `delete` (disconnect).

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_fb_ad_account",
    "arguments": {
      "action": "list"
    }
  }
}

Manage Facebook ad sets. Actions: `upsert` (create or update — provide ad set in `body`), `pause`, `resume`, `duplicate`, `delete` (by `adSetId`).

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_fb_adset",
    "arguments": {
      "action": "upsert"
    }
  }
}

Manage Facebook ad campaigns. Actions: `get` (single campaign with entities by `campaignId`), `upsert` (create or update — provide full campaign in `body`), `publish` (publish a draft by `campaignId`), `pause`, `resume`, `duplicate`, `delete` (by `campaignId`).

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_fb_campaign",
    "arguments": {
      "action": "get"
    }
  }
}

Manage Facebook custom audiences and their members. Actions: `list`, `update` (by `audienceId`), `delete` (by `audienceId`), `add_member` (single — by `audienceId` + member info in `body`), `remove_member` (single — by `audienceId` + member info in `body`), `batch_update_members` (bulk — by `audienceId` + member array in `body`).

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_fb_custom_audience",
    "arguments": {
      "action": "list"
    }
  }
}

Generic Facebook entity lookup endpoint. Action: `get` (returns the requested entity — pass identifying params in `query`).

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_fb_entity",
    "arguments": {
      "action": "get"
    }
  }
}

Manage the location's Facebook integration (also surfaces Instagram via FB Pages). Actions: `get` / `create` / `delete` (the integration itself); `get_me` (the authenticated FB user); `list_pages` (FB pages available on the integration); `get_page_instagram` (Instagram accounts attached to a page — provide `pageId`); `delete_page` (remove a page connection); `set_default_page` (mark a page as default for publishing); `get_lead_form` (single lead form by `leadFormId`).

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_fb_integration",
    "arguments": {
      "action": "get"
    }
  }
}

Manage Facebook lead forms (page-level + conversation-level). Actions: `list_page_forms` (by `pageId`), `create_page_form` (by `pageId` + `body`), `list_conversation_forms`, `create_conversation_form` (provide `body`).

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_fb_lead_form",
    "arguments": {
      "action": "list_page_forms"
    }
  }
}

Manage Facebook conversion pixels for the location. Actions: `list`, `upsert` (create or update — provide pixel config in `body`).

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_fb_pixel",
    "arguments": {
      "action": "list"
    }
  }
}

Facebook ads reporting. Actions: `data` (aggregated metrics across campaigns / ad sets / ads — pass `level` + date range), `campaign` (metrics for a specific campaign by `campaignId`), `list` (list entities with their reporting data — pass `type` + `listType` + optional `fields`). ALL actions take `dateFrom` and `dateTo` as ISO date strings (YYYY-MM-DD). Common values for `level` / `type`: `account`, `campaign`, `adset`, `ad`. Common values for `listType`: `active`, `paused`, `all`. `fields` is a comma-separated list of metric column names (e.g. `spend,impressions,clicks,conversions`). If the endpoint rejects your values with 422, surface that to the operator — the valid enum set isn't stably published in CRM docs and can shift.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_fb_reporting",
    "arguments": {
      "action": "data"
    }
  }
}

Search Facebook targeting options — geo locations, interests, behaviors, demographics. Action: `search` (pass search params like `query`, `type`, `country` in `body` or `query`).

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_fb_targeting",
    "arguments": {
      "action": "search"
    }
  }
}

Manage connected Google ad accounts. Actions: `list` (all connected), `get` (by `adAccountId`), `delete` (disconnect).

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_google_ad_account",
    "arguments": {
      "action": "list"
    }
  }
}

Manage Google Ads audiences. Actions: `list` (all combined audiences), `get` (by `audienceId`), `upsert` (create or update — provide audience config in `body`), `create_offline_user_list_job` (offline-conversion user-list upload job — provide job config in `body`).

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_google_audience",
    "arguments": {
      "action": "list"
    }
  }
}

Manage Google Ads campaigns (creates or updates the full structure: campaign, ad groups, ads, keywords). Actions: `upsert` (provide full campaign in `body`), `get` (by `adId`), `publish_ad` (publish a draft ad by `adId`).

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_google_campaign",
    "arguments": {
      "action": "upsert"
    }
  }
}

Manage Google Ads conversion actions and conversion goals. Actions: `list` (all conversions), `upsert` (create or update — provide conversion config in `body`), `get` (by `conversionId`), `delete` (by `conversionId`), `list_goals` (available conversion goals for the location).

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_google_conversion",
    "arguments": {
      "action": "list"
    }
  }
}

Manage the location's Google Ads integration. Actions: `get`, `create` (provide auth payload in `body`), `get_me` (authenticated Google user).

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_google_integration",
    "arguments": {
      "action": "get"
    }
  }
}

Google Ads reporting. Actions: `data` (aggregated metrics — pass `level` + date range), `list` (list entities with reporting data — pass `type` + `listType` + optional `fields`), `campaign` (metrics for a specific campaign by `campaignId`). ALL actions take `dateFrom` and `dateTo` as ISO date strings (YYYY-MM-DD). Common `level` / `type`: `account`, `campaign`, `ad_group`, `ad`. Google Ads reports cost in micros internally; this MCP forwards the CRM's normalized values.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_google_reporting",
    "arguments": {
      "action": "data"
    }
  }
}

Search Google Ads targeting options. Action: `search` (pass search params in `query`).

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_google_targeting",
    "arguments": {
      "action": "search"
    }
  }
}

Manage connected LinkedIn ad accounts. Actions: `list`, `get` (current/details), `delete` (disconnect).

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_linkedin_ad_account",
    "arguments": {
      "action": "list"
    }
  }
}

Manage LinkedIn ad campaign groups (with nested campaigns and ads). Actions: `upsert` (create or update — provide full campaign group in `body`), `get` (by `adId` — returns the campaign group + nested campaigns / ad groups / ads), `publish` (publish a draft by `adId`), `update_status` (pause, resume, archive an ad or campaign by `adId` — provide status in `body`).

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_linkedin_campaign",
    "arguments": {
      "action": "upsert"
    }
  }
}

Manage the location's LinkedIn Ads integration. Actions: `get`, `create` (provide auth payload in `body`), `get_me` (authenticated LinkedIn user).

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_linkedin_integration",
    "arguments": {
      "action": "get"
    }
  }
}

Manage LinkedIn lead forms per ad account. Actions: `list` (by `accountId`), `create` (by `accountId` + form config in `body`).

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_linkedin_lead_form",
    "arguments": {
      "action": "list",
      "accountId": "string"
    }
  }
}

LinkedIn Ads reporting. Actions: `data` (aggregated metrics — pass `level` + date range), `list` (list entities with reporting data — pass `type` + `listType` + optional `fields`), `campaign` (metrics for a specific campaign group by `campaignId`). ALL actions take `dateFrom` and `dateTo` as ISO date strings (YYYY-MM-DD). Common `level` / `type`: `account`, `campaign_group`, `campaign`, `ad`. LinkedIn's campaign-group is the equivalent of Meta's campaign — the top of the hierarchy.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_linkedin_reporting",
    "arguments": {
      "action": "data"
    }
  }
}

Search LinkedIn targeting options (location, industry, job title facets). Action: `search` (pass search params in `query`).

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_linkedin_targeting",
    "arguments": {
      "action": "search"
    }
  }
}

Build a fully-attributable URL by appending UTM params to a website URL. Validates source + medium against the tenant's configured taxonomy and throws on unknown values. Either pass explicit UTM params, or pass a registered campaign `slug` to resolve from the campaign UTM registry.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_build_utm_url",
    "arguments": {
      "websiteUrl": "string"
    }
  }
}

Get a registered campaign's canonical UTM set by `slug`. Returns null if not registered. Use this before emitting a link in any surface to ensure consistency.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_get_campaign_utm",
    "arguments": {
      "slug": "string"
    }
  }
}

Returns this location's marketing config — the channel taxonomy (allowed utm_source / utm_medium values), attribution rules (qualified-pipeline name, closed-won stage names, stage probabilities for forecast MRR), spend-classification rules, dashboard layout, and Slack webhook target. Stored as a JSON-encoded custom value named `_topline_marketing_config` in the location. Falls back to generic defaults if the value doesn't exist yet.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_get_marketing_config",
    "arguments": {
      "locationId": "string"
    }
  }
}

Ensure the six attribution custom fields exist on contacts for this location: utm_source_first, utm_medium_first, utm_campaign_first, utm_source_last, utm_medium_last, utm_campaign_last. Idempotent — creates each that's missing, skips ones that already exist. Run once during marketing setup so the homepage form snippet can populate them.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_init_attribution_fields",
    "arguments": {
      "locationId": "string"
    }
  }
}

Lint a URL (or explicit UTM params) against the tenant's marketing config. Returns an array of warnings: missing required fields, non-canonical source/medium values, common typos. Empty array if everything looks good. Useful for sanity-checking links before they ship in a post / email / ad.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_lint_utm",
    "arguments": {
      "url": "string",
      "source": "string"
    }
  }
}

List all registered campaign UTM entries for this location.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_list_campaign_utms",
    "arguments": {
      "locationId": "string"
    }
  }
}

Register or update a campaign's canonical UTM set. Same campaign slug always emits the same utm_source / utm_medium / utm_campaign / utm_id / utm_term / utm_content across every surface (social planner, email campaign, ad publishing). Validates source + medium against the tenant's marketing config. Stored in the `_topline_campaign_utms` custom value on this location.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_register_campaign_utm",
    "arguments": {
      "slug": "string",
      "source": "string",
      "medium": "string"
    }
  }
}

Write the location's marketing config. WHOLE-BLOB REPLACE — pass the complete config object you want stored. To do a partial update, call topline_get_marketing_config first, merge your changes, then call this. Validates that `sources` and `mediums` are non-empty arrays of strings. Stored as JSON in the `_topline_marketing_config` custom value on this location.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_set_marketing_config",
    "arguments": {
      "config": {
        "sources": [
          "string"
        ],
        "mediums": [
          "string"
        ],
        "attribution": {},
        "spend_rules": [
          {}
        ],
        "dashboard_layout": {},
        "slack": {}
      }
    }
  }
}

Append a spend classification rule. Each rule has a `when` matcher (merchant_regex / memo_regex / account_regex — at least one required) and a `classify_as` value (one of the tenant's configured sources). Rules are evaluated top-to-bottom; first match wins. To reorder or replace, use topline_set_marketing_config with the full rules array.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_add_spend_classification_rule",
    "arguments": {
      "when": {
        "merchant_regex": "string",
        "memo_regex": "string",
        "account_regex": "string"
      },
      "classify_as": "string"
    }
  }
}

Per-channel spend rollup for a date range. Pulls transactions from configured providers, applies the tenant's spend classification rules from marketing_config, and aggregates by canonical channel. Unclassified transactions land in the 'needs_review' bucket and need either a rule (topline_add_spend_classification_rule) or manual reclassification.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_get_channel_spend",
    "arguments": {
      "since": "string",
      "until": "string"
    }
  }
}

List the tenant's spend classification rules (from marketing_config.spend_rules).

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_list_spend_classification_rules",
    "arguments": {
      "locationId": "string"
    }
  }
}

List all spend providers compiled into the MCP. Spend is sourced from the CRM's ad-publishing reporting endpoints — no third-party expense integration is required. Bundled providers: meta_ads, google_ads, linkedin_ads. Each provider is `configured: true` as long as PIT auth is present; whether it actually returns spend depends on the network being connected in the CRM Integrations UI for this location. Returns { providers: [{ name, configured }], configured_count }.

No parameters.

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_list_spend_providers",
    "arguments": {}
  }
}

Fetch raw spend transactions across configured providers within a date range. Each transaction includes provider, amount, merchant, date, memo, etc. Pass `provider` to filter to a single source (otherwise all configured providers are queried). Does NOT apply channel classification — use topline_get_channel_spend for the per-channel rollup.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_list_spend_transactions",
    "arguments": {
      "since": "string",
      "until": "string"
    }
  }
}

Reconcile totals across two providers for a date range — useful for cross-checking spend totals between ad networks or against an external source. Returns per-channel totals from each provider plus delta and a list of transactions present in one but not the other (best-effort match by date + amount + merchant).

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_reconcile_spend",
    "arguments": {
      "since": "string",
      "until": "string",
      "provider_a": "string",
      "provider_b": "string"
    }
  }
}

Process a single form submission: classify its channel from captured UTM/referrer, format a Slack notification, and post. Pass `submission` with at minimum { contactId, contactName, formName, utm_source?, utm_medium?, utm_campaign?, referrer? }. Returns { ok, channel, slack_ok }. No-ops Slack if not configured; still classifies and returns the channel so the dashboard widget feed (P5) can render the row.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_dispatch_form_submission",
    "arguments": {
      "submission": {
        "contactId": "string",
        "contactName": "string",
        "formName": "string",
        "utm_source": "string",
        "utm_medium": "string",
        "utm_campaign": "string",
        "referrer": "string",
        "contactUrl": "string"
      }
    }
  }
}

Show whether Slack notifications are wired and which source is active (env var TOPLINE_SLACK_WEBHOOK_URL takes precedence; otherwise marketing_config.slack.webhook_url). Returns { configured: bool, source?: 'env' | 'marketing_config' }.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_get_slack_config",
    "arguments": {
      "locationId": "string"
    }
  }
}

Send a free-form message to the location's configured Slack channel. Use this for one-off alerts (e.g., 'Hot lead landed', 'Pipeline anomaly'). For structured form-submission notifications, use topline_dispatch_form_submission. No-ops gracefully (ok: false, reason: 'not_configured') if no webhook URL is set.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_notify_slack",
    "arguments": {
      "text": "string"
    }
  }
}

Return the marketing dashboard payload for a date range — channel rollup (spend per source from configured spend providers), summary cards, and a list-shaped placeholder for opportunity + MRR figures that require the analytics SQL surface (queryable via topline_execute_query against the opportunity_attribution view from P4). Dates default to the current month if omitted. Returns: { range, taxonomy_sources, channel_rollup, summary_cards, todo_sql_widgets }.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_get_marketing_dashboard",
    "arguments": {
      "since": "string",
      "until": "string"
    }
  }
}

Standard contact activity audit in a single call. Replaces the legacy fan-out of search_contacts → get_contact → search_opportunities → search_conversations → get_messages. Accepts an opaque contact ID OR a fuzzy identifier (email like 'jane@acme.com', phone like '+15551234567', or name like 'Jane Smith'); resolves it internally and echoes how it matched. Accepts since/until as 'this-week-et', 'now', RFC3339, YYYY-MM-DD, or relative shorthand (e.g. '90d', '24h'). Default since = 90d, until = now. Returns { contact, contactResolution, window, freshness, opportunities, activity, timeline, messages } where opportunities lists all deals for the contact with pipeline_name/stage_name/value/status (via opportunity_funnel), activity is a counts rollup by event_kind+direction over the window, timeline is per-event rows from contact_timeline within the window (messages + opportunities-created + appointments), and messages is the last N raw message bodies for context. PREFER THIS over topline_execute_query, topline_search_contacts, topline_search_conversations, or topline_get_messages for any 'what's going on with contact X' / 'what did Y say this month' / 'give me a brief on Z' question — it is faster, cheaper, and prevents the agent from inventing SQL the warehouse views already cover. Tasks and notes are NOT included (they are REST-only); drill down with topline_list_contact_tasks / topline_list_contact_notes if the user asks.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_contact_audit",
    "arguments": {
      "contact": "string"
    }
  }
}

COMPLETE catalog of every Topline object that exists upstream — including objects we sync (queryable via SQL), objects we've catalogued but haven't built sync for yet, objects that require OAuth/agency scopes our PIT auth can't reach, and objects we've declined to sync. Call this when topline_describe_schema doesn't show something the user is asking about — it will tell you whether the data lives on disk (queryable now), is pending (answer will lag a sync cycle), or is inaccessible (tell the user to request it instead of inventing a workaround). Contrast with topline_describe_schema, which is SCHEMA-only and hides everything not currently exposed. Returns { entries: [{ name, category, status, description, sql_table?, endpoint?, notes? }...] } with status in {exposed, syncing, catalogued, requires_oauth, inaccessible, declined}.

No parameters.

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_describe_data_catalog",
    "arguments": {}
  }
}

Overview of every table currently exposed to SQL queries in this sub-account's data warehouse. Returns table names, one-line descriptions, row counts, and a short SQLite-dialect cheat sheet. Call this FIRST when the user asks anything analytics-flavored ('how many', 'group by', 'trend', 'compare', 'duplicate'). It's cheap and tells you what's queryable. Follow up with topline_explain_tables on the ones you want to use, then topline_execute_query with the SQL.

No parameters.

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_describe_schema",
    "arguments": {}
  }
}

Run a read-only SQL query against this sub-account's SQLite warehouse. ONE SELECT or WITH...SELECT statement at a time. DDL, DML, PRAGMA, ATTACH, and admin commands are rejected by the parser before they reach the database. Results are capped at 5000 rows; larger result sets come back with truncated: true. Returns { columns, rows, elapsed_ms, truncated, effective_limit, rewritten_sql }. SQLite dialect — no DATE_TRUNC (use strftime), JSON columns need json_extract / json_each, timestamps are ISO 8601 strings that compare lexicographically.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_execute_query",
    "arguments": {
      "query": "string"
    }
  }
}

Per-column detail for one or more tables returned by topline_describe_schema. Gives column names, SQLite types, nullability, JSON-column flags, enum values for closed-set text columns, foreign-key hints for joins, and approximate row counts. Call this before writing a SELECT so your WHERE / JOIN clauses use real column names and valid enum values. Rejects tables that aren't in the exposed set.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_explain_tables",
    "arguments": {
      "tables": [
        "string"
      ]
    }
  }
}

Answer 'what uses X?' across synced CRM objects. Closed-enum dispatcher — runs hard-coded SQL per kind; no arbitrary SQL accepted. Supported kinds: tag, custom_field, custom_value, pipeline, pipeline_stage, calendar, user, contact, opportunity, form, survey. WORKFLOWS are NOT supported: the upstream platform's public API does not expose workflow internals, so we cannot know which workflows reference any given object. kind=opportunity returns ONLY direct references (the opportunity itself, its pipeline, stage, and contact) — it does NOT include downstream activity like messages or calls, since those belong to the contact and may span multiple opportunities. To get a contact's full activity, call this tool again with kind=contact using the contact_id from the opportunity's extra payload. Results are capped at 500 rows total (not per kind); truncated=true means upstream had more. For tags, accepts either the tag id or the tag name.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_find_references",
    "arguments": {
      "kind": "tag",
      "id": "string"
    }
  }
}

Owner-scoped activity audit in a single call. THE tool for any 'how is rep X doing' / 'rep snapshot for X' / 'what did X work on this week' / 'X's book' / 'who's most active' / 'is X caught up on their book' question. Replaces the legacy fan-out of topline_list_users → topline_search_opportunities(assignedTo=...) → topline_execute_query on pipeline_activity_window. Accepts an opaque user_id, email, or fuzzy name; resolves via REST /users/ once and echoes how it matched. Accepts since/until as 'this-week-et' (default since = 7d), 'now', RFC3339, YYYY-MM-DD, or relative shorthand. Optional `pipeline` arg (id or fuzzy name) scopes everything to one pipeline. Optional `stale_days` (default 14) defines the stale-ownership threshold. Returns { userId, ownerResolution, user, window, pipelineFilter, status, staleDays, freshness, book, bookByStage, activity, deals, staleOwnedDeals, crossAssignedTouches, movement }. TWO OWNERSHIP LENSES: `book` / `bookByStage` / `staleOwnedDeals` / `movement` use opportunities.assigned_to (deals owned by this user). `activity` / `deals` / `crossAssignedTouches` use messages.user_id / call_events.user_id (touches THIS USER personally logged). AUTOMATION FILTER: activity/deals/staleOwnedDeals/crossAssignedTouches all exclude messages where raw_payload.$.source IN ('campaign','workflow') — those are workflow blasts and bulk campaigns, not personal rep touches. Calls and appointments are always counted as rep activity (no automation noise there). staleOwnedDeals = opps in book with no rep-attributed touch in the last `stale_days` days, ordered by monetary_value DESC — this is the 'what's rotting in the rep's book' surface. crossAssignedTouches = deals THIS USER personally touched in window where assigned_to is someone else, ordered by unique_touches DESC — this is the 'helping someone else's book' surface. PREFER THIS over topline_execute_query for any owner-scoped question. NEVER hand-write CTEs for owner book + touches + stale + cross-assignment when this tool returns all four in one call.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_owner_audit",
    "arguments": {
      "owner": "string"
    }
  }
}

Standard pipeline activity audit in a single call. Replaces the legacy 3-step flow (describe_schema → resolve pipeline name → hand-write SQL across pipeline_snapshot / pipeline_activity_window / pipeline_movement_window / warehouse_freshness). Accepts an opaque pipeline ID or a fuzzy name ('flex triage', 'qualified'); resolves the name internally and echoes how it matched. Accepts since/until as 'this-week-et' (default since = 7d), 'now', RFC3339, YYYY-MM-DD, or relative shorthand (e.g. '7d', '24h'). Returns { pipelineId, pipelineResolution, window, status, freshness, snapshot, activity, deals, movement } where activity uses unique_touches (deduped against source_id), deals carries per-deal touch breakdowns, and movement is stage/status changes inside the window. PREFER THIS over topline_execute_query for any 'what happened in pipeline X over window W' question — it is faster, cheaper, and prevents the agent from inventing SQL the audit views already cover.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_pipeline_audit",
    "arguments": {
      "pipeline": "string"
    }
  }
}

Open opportunity count, pipeline value, and stage distribution for one pipeline. Single-call equivalent of `topline --agent query snapshot --pipeline ... --status open`. Accepts either an opaque 20-char pipeline ID or a fuzzy pipeline name (e.g. 'flex triage', 'qualified'); on 0 or >1 matches it errors with the candidate list. Use this when the user wants a snapshot without activity/movement detail. Returns { pipelineId, pipelineResolution, status, snapshot }.

Parameters

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_pipeline_snapshot",
    "arguments": {
      "pipeline": "string"
    }
  }
}

Deterministic readiness probe for the SQL warehouse surface. Confirms the schema endpoint is reachable, lists which expected tables are present, and reports any coverage gaps as actionable bugs (not as a reason to fall back to REST). Run this once at the start of any standard pipeline audit; if the report is green, proceed to topline_pipeline_audit. Returns { schemaReachable, tableCount, expectedTables, missingTables, recommendation }.

No parameters.

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_query_doctor",
    "arguments": {}
  }
}

Describes the HTTP query API you can point Looker Studio, Retool, Lovable, Claude Code, n8n, or curl at for live-data dashboards. Returns URL shapes, auth format, example curl commands, and guidance for wiring up a dashboard. Use this when the user asks about building dashboards, embedding the data in another tool, or when a query is too complex for chat and they'd rather save it as a saved view.

No parameters.

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_utilize_api",
    "arguments": {}
  }
}

Per-table sync freshness probe for the warehouse tables that drive pipeline audits. Returns row_count, last_synced_at, and lag_seconds for each tracked table. Call this when the user asks whether warehouse data is current, or when a pipeline audit shows stale numbers and you need to attribute it to sync lag versus coverage gaps. Cheap, no arguments.

No parameters.

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "topline_warehouse_freshness",
    "arguments": {}
  }
}