> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to the Calven MCP server

The Calven MCP connector routes your AI agent's tool calls to Calven's own MCP server through Scalekit. Each user signs in to Calven once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 16 tools.

**Authentication:** OAuth 2.1/CIMD
**Categories:** Marketing, CRM & Sales
**Tools:** 16: 13 read, 3 write, 0 destructive
**Users sign in with:** OAuth
**OAuth app:** Your own Calven MCP server app
**Built by:** Vendor MCP
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=CALVENMCPOAUTH)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".env"
   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>
   ```

3. ### Create the Calven MCP connection

   In **AgentKit > Connections**, create a Calven MCP connection and copy its redirect URI. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/).

4. ### Register an OAuth app

   Calven MCP server connections use your own OAuth app. Register one with Calven MCP server and add the redirect URI you copied.

   Then enter the app's Client ID and Client Secret on the Calven MCP connection.

5. ### Authorize a user and make your first call

   **Node.js** (`quickstart.mts`)

   ```typescript
   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   import { createInterface } from 'node:readline/promises'

   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENVIRONMENT_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions

   const connector = 'calvenmcpoauth'
   const identifier = 'user_123'

   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize Calven MCP:', link)
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   await rl.question('Press Enter after authorizing...')
   rl.close()

   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'calvenmcpoauth_get_competitor',
     toolInput: {},
   })
   console.log(result)
   ```

   ```bash
   npx tsx quickstart.mts
   ```

   **Python** (`quickstart.py`)

   ```python
   import os
   from scalekit import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()

   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions

   connection_name = "calvenmcpoauth"
   identifier = "user_123"

   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Calven MCP:", link_response.link)
   input("Press Enter after authorizing...")

   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="calvenmcpoauth_get_competitor",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)
   ```

   ```bash
   python quickstart.py
   ```

   Each user signs in once. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses.

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'calvenmcpoauth_get_competitor',
  toolInput: {},
  connector: 'calvenmcpoauth',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="calvenmcpoauth_get_competitor",
    tool_input={},
    connection_name="calvenmcpoauth",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `calvenmcpoauth_get_competitor`

Get competitor · Read-only

One competitor in a single call: the row, its battlecard (how to sell against them: traps, objections, proof points), its most recent competitive signals, and the outline of its deep-dive dossier (pricing, packaging, positioning, strengths, weaknesses) with the call that reads the dossier whole.
Use when: a question names a specific rival, including how they price, package, position or sell. Competitor pricing lives in their dossier, not in any product brief: read it with the read_document call the result prints.
Do NOT use when: you want the whole roster or a filtered feed: list_records({ kind: "competitors" }) and list_records({ kind: "competitive_signals" }) do that.
Args: Pass `id` or `name`, not both.
Returns: competitor { id, name, cells, battlecard, recent_signals, signals_has_more, deep_dive { asset_id, word_count, sections } }. A null battlecard or deep_dive is not published; the notes say which documents are.
Example: get_competitor({ name: "Collibra" })

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, optional): The 8-character id shown in results, or a full id.
- `name` (`string`, optional): The competitor name, case-insensitive. Use instead of `id`.

Example input: `{}`

### `calvenmcpoauth_get_insight_detail`

Get insight detail · Read-only

The rows behind one number on an Insights dashboard: the deals in a pricing bucket or loss outcome, the deals against one competitor, what buyers answered to one survey question, one AI assistant answer, the market-signal feed.
Use when: get_insights returned a number and you need its evidence. Sections name the drill-downs they support under "Rows behind these numbers".
Args: detail is one of win_loss.verbatims, win_loss.answers, win_loss.pricing_deals, win_loss.product_deals, win_loss.loss_outcome_deals, competitive_intelligence.competitor_deals, competitive_intelligence.pricing_deals, positioning.ai_answer, market_research.signals. Pass the same product and window as the get_insights call it drills into. verbatims needs group, answers needs question (a question_id), product_deals needs product. Other arguments narrow where they apply; leave verdict, bucket or outcome out to get every group, labelled.
Returns: items[] (at most `limit`, max 100) and more_available with how to narrow. Deal names, amounts and buyer survey answers follow the workspace security settings.
Example: get_insight_detail({ detail: "competitive_intelligence.competitor_deals", competitor: "AuditBoard", outcome: "lost" })

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `detail` (`string`, required): Which drill-down. One of: `win_loss.verbatims`, `win_loss.answers`, `win_loss.pricing_deals`, `win_loss.product_deals`, `win_loss.loss_outcome_deals`, `competitive_intelligence.competitor_deals`, `competitive_intelligence.pricing_deals`, `positioning.ai_answer`, `market_research.signals`.
- `answer` (`string`, optional): ai_answer: an assistant's name (e.g. ChatGPT) or an answerId. Omit for every assistant's latest answers.
- `bucket` (`string`, optional): loss_outcome_deals: what beat us. Omit for every bucket, each row labelled. One of: `competitor`, `in_house`, `no_decision`, `unattributed`.
- `competitor` (`string`, optional): CI details: one competitor, by name.
- `from` (`string`, optional): First day counted, YYYY-MM-DD. Pass `to` with it.
- `group` (`string`, optional): verbatims: a survey group with written answers, e.g. "Product".
- `include_untagged` (`boolean`, optional): With `product`: also count rows with no product tag (company-wide, or not yet tagged). Default: `false`.
- `limit` (`integer`, optional): Rows to return, default 20, max 100.
- `loss_reason` (`string`, optional): competitor_deals: one loss reason.
- `month` (`string`, optional): competitor_deals: YYYY-MM.
- `offset` (`integer`, optional): Rows to skip: the `next rows: offset` a previous reply printed.
- `outcome` (`string`, optional): Omit for both, each row labelled. One of: `won`, `lost`.
- `product` (`string`, optional): Product name (case-insensitive, as list_products prints it) or id: only rows tagged with it, like the dashboard's product chip. "untagged" alone: only rows with no product. Omit for the whole company.
- `question` (`string`, optional): answers: a question_id.
- `rating` (`integer`, optional): answers: one rating.
- `tier` (`integer`, optional): CI details: one tier of rivals, as the HTTP drill-down takes it: 1, 2 or 3 (the pricing_distribution pool tier_N), "emerging" or "untiered". Accepts 1, 2 or 3 (as a number) or "emerging" or "untiered".
- `timeframe` (`string`, optional): Today is 2026-11-14. trailing4w / trailing12m (default) = this week / month so far plus the 3 / 11 before; thisQuarter, thisYear = so far; lastMonth, lastQuarter, lastYear = the previous complete one. Any other month or quarter ("Q2"): from + to. One of: `trailing4w`, `trailing12m`, `thisQuarter`, `thisYear`, `lastMonth`, `lastQuarter`, `lastYear`.
- `to` (`string`, optional): Last day counted, YYYY-MM-DD (August 2026 = 2026-08-01 to 2026-08-31).
- `verdict` (`string`, optional): pricing_deals: less_expensive|on_par|more_expensive (win_loss), cheaper|on_par|pricier (CI). Omit for every verdict, each row labelled.

Example input: `{"detail":"win_loss.verbatims"}`

### `calvenmcpoauth_get_insights`

Get insights · Read-only

Any agent's Insights dashboard as data: the numbers each section of the tab shows (KPIs, rates, breakdowns, trends, rankings), computed exactly as the dashboard computes them. Each comparable KPI comes with its change against the period before.
Use when: a question is about totals, rates, shares, trends or rankings, or any KPI tile (the `sections` parameter lists the tiles of each section): win rate, why we lose, which segment sells best (win_loss segments), ICP vs non-ICP pipeline, product gaps that cost deals, competitor momentum, customer themes, messaging drift, how AI describes us.
Do NOT use when: "how are we doing" or a periodic review across dashboards (get_insights_overview first); the individual rows behind a number (get_insight_detail, or list_records); a strategy document (get_strategy_document).
Args: dashboard + optional sections (omit for every section). Window: timeframe OR from+to (both days counted), default trailing12m; positioning and messaging have no window. product: strict, like the dashboard chip.
Returns: sections[] { id, title, status, data, notes, placeholders }, the window counted and the period it is compared with, the product scope, and a link to the dashboard. A KPI's `comparison` is { prior, delta, prior_n } (delta in percentage points for rates), or { reason } when it cannot be compared (never read that as no change); a KPI marked snapshot is current state, with no change; a KPI marked not_compared counts the period but has no change on purpose (it is still filling in or reads today's state), so never compute one from other periods. Placeholders are widgets with no numbers behind them: say there is no number, never estimate one. Cite the sample (n) beside every rate.
Example: get_insights({ dashboard: "competitive_intelligence", sections: ["performance"], timeframe: "thisQuarter" })

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `dashboard` (`string`, required): Which Insights tab. win_loss: win rate, pipeline won/lost, why we win and lose, segments; win_loss_program_health: the survey program; competitive_intelligence: per-competitor performance, battlecards, influenced revenue; icp: ICP fit, win predictors; voice_of_customer: customer themes, signals, quotes; persona: buying group, multi-threading; positioning and messaging: consistency, drift, AI perception; market_research: opportunities, trends, signals; product_intelligence: product gaps that cost deals, drift. One of: `win_loss`, `win_loss_program_health`, `competitive_intelligence`, `voice_of_customer`, `icp`, `persona`, `positioning`, `messaging`, `market_research`, `product_intelligence`.
- `from` (`string`, optional): First day counted, YYYY-MM-DD. Pass `to` with it.
- `include_untagged` (`boolean`, optional): With `product`: also count rows with no product tag (company-wide, or not yet tagged). Default: `false`.
- `list` (`string`, optional): With one section: the rest of a list a reply cut, by the name its header prints ("next rows: list: …"), 200 rows from `offset`.
- `offset` (`integer`, optional): With `list`: rows to skip, as the cut header prints.
- `product` (`string`, optional): Product name (case-insensitive, as list_products prints it) or id: only rows tagged with it, like the dashboard's product chip. "untagged" alone: only rows with no product. Omit for the whole company.
- `sections` (`array`, optional): Omit for all, or ids to read only those ([KPI tiles], * no numbers): win_loss: scoreboard [Competitive win rate,Pipeline won,Pipeline lost,Sentiment],segments,buying_group,surveys_head_to_head,surveys_product,surveys_pricing_legal,surveys_sales_team,why_won_lost,deciding_forces; win_loss_program_health: scoreboard [Deals with completed win-loss,Completion rate,AI interview vs. online survey],volume,email_delivery [Bounce rate,Emails sent],response_funnel,ai_interviews [Picked the AI interview,Rated the AI interview good],respondent_experience [Rated the online survey good],enrollment_coverage [Deals enrolled,Deals analyzed],segment_coverage,timing [Median AI interview length,Median online survey time,Started but not finished]; competitive_intelligence: kpis [Competitive win rate,Influenced revenue,Battlecard coverage,Competitors in catalog],performance,showdown,market_movement [Feature parity coverage*,"Bullshit detector" flags*]; voice_of_customer: kpis [Conversations analyzed,Customer-voice signals,Product feedback signals,Analyst-hours saved],customer_signals,tied_to_revenue,quotes; icp: kpis [ICP share of wins,ICP-fit pipeline,Avg deal size,Sales cycle],expand_icp,win_predictors,reality_check; persona: kpis [Multi-threading win-rate,Single-threaded pipe,Multi-threaded pipe,Contact coverage],buying_group,persona_intelligence,keeping_honest; positioning: kpis [Positioning alignment,Drift resolved,Positioning moves],consistency,market_landscape [Perceptual map*,Differentiator defensibility*],grounded,ai_perception; messaging: kpis [Message sharpness,Customer-language fit,Messaging alignment,Evidence-backed pillars],effectiveness,quality,customer_language,field_adoption; market_research: kpis [Opportunities surfaced,Opportunities actioned,High-impact trends,Signals tracked],opportunities_trends,signal_intelligence; product_intelligence: kpis [Drift flagged,Assets synced,Unsupported claims*,Enablement coverage*],product_changes [Strengths vs gaps*,Product claims feed*],outcomes
- `timeframe` (`string`, optional): Today is 2026-11-14. trailing4w / trailing12m (default) = this week / month so far plus the 3 / 11 before; thisQuarter, thisYear = so far; lastMonth, lastQuarter, lastYear = the previous complete one. Any other month or quarter ("Q2"): from + to. One of: `trailing4w`, `trailing12m`, `thisQuarter`, `thisYear`, `lastMonth`, `lastQuarter`, `lastYear`.
- `to` (`string`, optional): Last day counted, YYYY-MM-DD (August 2026 = 2026-08-01 to 2026-08-31).

Example input: `{"dashboard":"win_loss"}`

### `calvenmcpoauth_get_insights_overview`

Get insights overview · Read-only

Every Insights dashboard's headline KPIs for one window, each comparable one with its change against the period before, plus what moved most in each ranked list, the current top loss reasons and product gaps, and which dashboards have no data.
Use when: "how are we doing", a monthly or quarterly review, a launch readout (with product), or one headline KPI. Each item names the get_insights section to read next.
Do NOT use when: a breakdown, trend or longer ranking (get_insights; a long list says how many it shows of the total).
Args: product and the window, as get_insights.
Returns: kpis[] with `comparison` (as get_insights), movers[], top_loss_reasons, product_gaps (amount_at_risk covers won and lost deals: not lost revenue), availability, window and compared period.
Example: get_insights_overview({ timeframe: "lastMonth" })

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `from` (`string`, optional): First day counted, YYYY-MM-DD. Pass `to` with it.
- `include_untagged` (`boolean`, optional): With `product`: also count rows with no product tag (company-wide, or not yet tagged). Default: `false`.
- `product` (`string`, optional): Product name (case-insensitive, as list_products prints it) or id: only rows tagged with it, like the dashboard's product chip. "untagged" alone: only rows with no product. Omit for the whole company.
- `timeframe` (`string`, optional): Today is 2026-11-14. trailing4w / trailing12m (default) = this week / month so far plus the 3 / 11 before; thisQuarter, thisYear = so far; lastMonth, lastQuarter, lastYear = the previous complete one. Any other month or quarter ("Q2"): from + to. One of: `trailing4w`, `trailing12m`, `thisQuarter`, `thisYear`, `lastMonth`, `lastQuarter`, `lastYear`.
- `to` (`string`, optional): Last day counted, YYYY-MM-DD (August 2026 = 2026-08-01 to 2026-08-31).

Example input: `{}`

### `calvenmcpoauth_get_persona`

Get persona · Read-only

One persona's row plus its deep-research canvas: pains, gains, jobs to be done, objections, messaging hooks.
Use when: you are tailoring copy, a play or an objection response to a specific persona.
Do NOT use when: you want the roster of personas: list_records({ kind: "personas" }) is the lightweight read.
Args: Pass `id` or `name`, not both.
Returns: persona { id, name, cells, canvas }. A null canvas means no canvas is published; the row attributes still apply.
Example: get_persona({ name: "VP of Data" })

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`string`, optional): The 8-character id shown in results, or a full id.
- `name` (`string`, optional): The persona name, case-insensitive. Use instead of `id`.

Example input: `{}`

### `calvenmcpoauth_get_record`

Get record · Read-only

One row with its FULL cell set. Each list_records result names the columns get_record would add; when it says none, the list line already had everything.
Use when: you have a row id (or an exact name) and need everything the workspace knows about it.
Do NOT use when: the row is a competitor or a persona: get_competitor and get_persona add its documents.
Args: Pass one of `id`, `name` or `ids`. `id` is the short `id:` a list_records line prints (8 characters), or the full id. `name` is the exact name or title (case-insensitive); quotes, findings, drivers and claims go by id. `ids`: up to 25 rows of one kind in one call, never one call per row.
Returns: record { id, kind, name, cells }, or records[] with `ids`. Agent-only bookkeeping columns are never included.
Example: get_record({ kind: "trends", name: "AI governance" })

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `kind` (`string`, required): Which curated database the row belongs to. One of: `competitors`, `competitive_signals`, `personas`, `trends`, `market_opportunities`, `analyst_findings`, `themes`, `quotes`, `vendor_quotes`, `customer_conversations`, `market_signals`, `deal_drivers`, `product_changes`, `product_drift_findings`, `claims`, `surveyed_deals`, `survey_responses`, `crm_accounts`, `crm_contacts`, `crm_deals`.
- `id` (`string`, optional): The 8-character id a list_records line prints, or a full id.
- `ids` (`array`, optional): Several rows of this kind at once, by the ids list_records prints. Use instead of `id`.
- `name` (`string`, optional): The exact row name, case-insensitive. Use instead of `id`.

Example input: `{"kind":"competitors"}`

### `calvenmcpoauth_get_strategy_document`

Get strategy document · Read-only

One of the four workspace strategy documents, as published markdown. positioning = category, target, differentiation, narrative. messaging = value props, pillars and approved wording. product_brief = what the product does, its features, packaging, PRICING and plans. icp = who it is for.
Use when: you are writing or checking anything that must match this company's position, wording, product truth or target. Our own pricing, plans or packaging: read product_brief. A competitor's pricing: get_competitor. Why deals were won or lost: get_insights (dashboard win_loss) for the totals, then list_records on surveyed_deals, survey_responses or deal_drivers.
Do NOT use when: you want a competitor dossier, a battlecard or a persona canvas: use get_competitor, get_persona, or list_documents plus read_document.
Args: `product` scopes to that product's instance; if it has none, the company-wide document comes back with `scope.product` null and a note, and it still applies.
Returns: document { asset_id, kind, name, product, version, word_count, sections[], content, part? } or null when nothing has been published. A document longer than one reply comes in parts: the reply names the call for the next part.
Example: get_strategy_document({ document: "icp", product: "Billing" })

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `document` (`string`, required): Which strategy document to read. One of: `positioning`, `messaging`, `product_brief`, `icp`.
- `offset` (`integer`, optional): Only for a document longer than one reply: the parts (H2 sections) to skip, i.e. the `offset` in the "Next part" call the previous reply printed. Omit to start at the top.
- `product` (`string`, optional): Product name, e.g. "Billing" (case-insensitive; an id also works). Returns that product's own version of the document, or the company-wide one with a note when it has none. Without it: the company-wide document. A wrong name returns the valid names; so does list_products.

Example input: `{"document":"positioning"}`

### `calvenmcpoauth_get_task`

Get task · Read-only

The status of a background task you started, and its result once it finishes.
Use when: you hold a task_id from review_against_personas, ask_the_market or ask_about_competitor and are waiting for the result.
Args: Poll while status is "working", waiting as long as the start verb said (poll_after_seconds).
Returns: working (still running), input_required (waiting on a human in the app), completed (result is in `result`), failed (reason is in `error`).
Example: get_task({ task_id: "…" })

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `task_id` (`string`, required): The task_id a start verb such as review_against_personas or ask_the_market returned: the 8-character id it printed, or a full id.

Example input: `{"task_id":"<task_id>"}`

### `calvenmcpoauth_get_workspace_overview`

Get workspace overview · Read-only

A map of everything this workspace holds: its products, which strategy documents exist (and which products have their own instance), and every record kind with its true row count.
Use when: you do not yet know what this workspace covers or which kind holds the answer. An empty result from the kind you asked already answers for that kind.
Do NOT use when: you already know the kind you need: call list_records or get_strategy_document directly.
Returns: workspace { product_mode, products[] of { id, name, state }, documents[], records[] }. A product with state `proposed` is unconfirmed: say so before treating it as part of the catalog. A record kind with total 0 exists but is empty. A kind marked restricted exists but this account may not read it (workspace security settings): say so, never that it is empty.
Example: get_workspace_overview({})

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `calvenmcpoauth_list_documents`

List documents · Read-only

Every published document here: per-product strategy instances, per-competitor dossiers and battlecards, per-persona canvases.
Use when: you need to know which documents exist, or you want the `asset_id` of one to read.
Do NOT use when: you already know which strategy document you want: get_strategy_document reads it in one call.
Args: `kind` narrows to one document kind; `product` to that product's documents plus the company-wide ones; `q` matches names (a competitor's or persona's name finds its documents). For one competitor or persona with its documents, get_competitor or get_persona is one call.
Returns: items[] of { asset_id, uri, kind, name, linked_to, version, updated_at }. Capped, not paginated: `truncated` means narrow with `kind` or `q`. Read one with read_document.
Example: list_documents({ kind: "competitor_battlecard" })

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `kind` (`string`, optional): One of: positioning, messaging, product_brief, icp, competitor_deep_dive, competitor_battlecard, persona_canvas.
- `limit` (`integer`, optional): Documents to return. Default 50, max 100. Default: `50`.
- `product` (`string`, optional): Product name, e.g. "Billing" (case-insensitive; an id also works). Returns that product's documents plus the company-wide ones. Without it: every document. A wrong name returns the valid names; so does list_products.
- `q` (`string`, optional): Literal case-insensitive substring of the document name, not a semantic match.

Example input: `{}`

### `calvenmcpoauth_list_products`

List products · Read-only

The products this workspace tracks: the names the `product` argument accepts.
Use when: a question is about one product rather than the company as a whole, and you need the exact name.
Returns: items[] of { id, name, description, status, state } plus the shared page envelope. state `proposed` means an agent suggested the product and no one has approved it yet: it is still a valid `product` argument, but say it is unconfirmed before treating it as part of the catalog. A single-product workspace returns an empty list and a note: there is nothing to scope to, and the portfolio-level content covers everything.
Example: list_products({})

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `limit` (`integer`, optional): Rows in this page. Default 25, max 100. Default: `25`.
- `offset` (`integer`, optional): Rows to skip: the `next_offset` a previous call printed (offset + limit). Omit for the first page. Max 2000; past that, narrow with `filter`.

Example input: `{}`

### `calvenmcpoauth_list_records`

List records · Read-only

One bounded page of a curated workspace database (`kind`): competitors, competitive and market signals, personas, trends, opportunities, analyst findings, customer-voice themes and quotes, rep (vendor) quotes, customer conversations, win/loss deal drivers, surveyed deals and survey answers, product changes and drift findings, messaging claims, CRM accounts, contacts and deals. Every result starts with that kind's filter, sort and search keys and their allowed values.
Use when: you want a collection: a roster, a feed, everything matching a property.
Do NOT use when: you want one row in full (get_record), or one competitor or persona (get_competitor, get_persona).
Args: `filter`: up to 4 AND-combined { key, op (default "eq"), value }. A key marked [has_any] holds several values per row: op "has_any" with a list. A key marked [id] takes a row id; other keys that point at a row take the NAME. `sort`: "<key>:asc|desc". `product` scopes the read like the product filter in the app: only rows tagged with it (never put it in `filter`); add include_untagged: true for the company-wide rows too. Page with `offset`: the `next_offset` a page prints.
Returns: the kind's keys line, then items[] of { id, kind, name, product[] (empty = untagged), cells } plus { has_more, next_offset, total (exact count of every match) }. Pass a line's short `id:` to get_record as is.
Example: list_records({ kind: "quotes", filter: [{ key: "sentiment", value: "negative" }], limit: 10 })

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `kind` (`string`, required): Which curated database to read. One of: `competitors`, `competitive_signals`, `personas`, `trends`, `market_opportunities`, `analyst_findings`, `themes`, `quotes`, `vendor_quotes`, `customer_conversations`, `market_signals`, `deal_drivers`, `product_changes`, `product_drift_findings`, `claims`, `surveyed_deals`, `survey_responses`, `crm_accounts`, `crm_contacts`, `crm_deals`.
- `filter` (`array`, optional): Up to 4 AND-combined conditions. Keys per kind ([has_any]: several values per row, use op has_any; [id]: a row id; allowed values come with every result): competitors: tier, categories[has_any], name, size; competitive_signals: severity, signal_type, source, competitor, confidence, change_type, detected_at; personas: type, name, seniority, buying_role; trends: category, name, severity, horizon, first_seen; market_opportunities: sizing_tier, name, type, impact, timeline, status, created_at; analyst_findings: finding_type, report_quarter, created_at; themes: label, category, status; quotes: category, highlight, source, deal_context, competitor_ref_id, source_language, theme_id, occurred_at, type[has_any], speaker_role, conversation_id, account, sentiment; vendor_quotes: category, source, conversation_id, sentiment, created_at; customer_conversations: deal_context, source_type, source_ref_id[id], source_language, occurred_at; market_signals: last_cited_at; deal_drivers: driver, group, category, direction, rank, outcome, source, competitor, competitor_ref_id, grouped_as, created_at; product_changes: change_kind, change_type, severity, confidence, detected_at; product_drift_findings: classification, confidence, product_change, product_change_state, created_at; claims: origin, assertion_type, claim_type, concern, status; surveyed_deals: outcome, summary_status, no_decision, in_house, competitor, created_at; survey_responses: outcome, source, completed_at, competitor, deal; crm_accounts: industry, size, region, funding_stage, icp_fit_tier, name; crm_contacts: role, lifecycle_stage, name; crm_deals: stage, reached_stages[has_any], furthest_stage, status, deal_type, lead_source, loss_reason, account_size, account_industry
- `include_untagged` (`boolean`, optional): With `product`: also return rows with no product tag (company-wide, or not yet tagged); each line is then marked [Product] or [untagged]. Default: `false`.
- `limit` (`integer`, optional): Rows in this page. Default 25, max 100. Default: `25`.
- `offset` (`integer`, optional): Rows to skip: the `next_offset` a previous call printed (offset + limit). Omit for the first page. Max 2000; past that, narrow with `filter`.
- `product` (`string`, optional): Product name, e.g. "Billing" (case-insensitive; an id also works): only rows tagged with it, like the product filter in the app. Without it: the whole company. A wrong name returns the valid names; so does list_products.
- `q` (`string`, optional): Literal case-insensitive substring over the kind's search columns. Not semantic: prefer one word, or `filter`. Search columns per kind: competitors: name, aliases, description; competitive_signals: title, summary; personas: name, role_title; trends: name, description; market_opportunities: name, description; analyst_findings: summary, publisher, subject; themes: label; quotes: quote, quote_original, author_name; vendor_quotes: quote, quote_original, author_name; customer_conversations: title; market_signals: title, domain; deal_drivers: driver, group, detail, competitor; product_changes: title, summary; product_drift_findings: asset_name, rationale; claims: claim; surveyed_deals: competitors, lost_to; survey_responses: respondent, competitors; crm_accounts: name, domain, industry; crm_contacts: name, email; crm_deals: name
- `sort` (`string`, optional): "<key>:asc" or "<key>:desc". Omit for the kind's own order. Sort keys per kind: competitors: tier, name, created_at; competitive_signals: detected_at, severity, source; personas: type, name; trends: first_seen, name, severity, category, last_seen; market_opportunities: impact, created_at; analyst_findings: report_year, created_at; themes: mentions, label, created_at; quotes: created_at, occurred_at; vendor_quotes: created_at; customer_conversations: occurred_at, created_at; market_signals: last_cited_at; deal_drivers: created_at, driver, group; product_changes: detected_at, severity; product_drift_findings: created_at, asset_name; claims: first_seen; surveyed_deals: created_at, summary_generated_at; survey_responses: completed_at; crm_accounts: icp_fit_score, name, icp_fit_tier; crm_contacts: name; crm_deals: close_date, opened_at, amount_usd, created_at

Example input: `{"kind":"competitors"}`

### `calvenmcpoauth_read_document`

Read document · Read-only

The published markdown of any document, addressed by the `asset_id` on a list_documents line.
Use when: you hold an asset_id and need the document body.
Do NOT use when: you have no asset_id and want one of the four strategy documents: get_strategy_document addresses those by name and handles product scoping.
Returns: document { asset_id, kind, name, product, version, word_count, sections[], content, part? }: the whole document, or for one longer than one reply (a competitor knowledge base can run past 50K chars) its first part and the call for the next.
Example: read_document({ asset_id: "…" })

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `asset_id` (`string`, required): The 8-character id shown beside a document in results, or a full id.
- `offset` (`integer`, optional): Only for a document longer than one reply: the parts (H2 sections) to skip, i.e. the `offset` in the "Next part" call the previous reply printed. Omit to start at the top.

Example input: `{"asset_id":"<asset_id>"}`

### `calvenmcpoauth_ask_about_competitor`

Ask about a competitor · Write

Starts a background research run that answers ONE question about a competitor with a cited answer: product, pricing, packaging, positioning, people, recent moves, how we win or lose.
Use when: a rival question that the stored dossier, battlecard and signals may not settle. It uses those, buyer quotes and win/loss first, then the web. Omit `competitor` to ask across all tracked rivals.
Do NOT use when: stored data is enough (get_competitor is instant), or the question is about the market (ask_the_market).
Args: `competitor` is a tracked rival by name or id.
Returns: RETURNS IMMEDIATELY with { task_id, status, poll_after_seconds }; the answer is NOT here and takes minutes. Poll get_task(task_id) while status is "working"; at "completed" it holds the cited answer, its confidence, freshness and what was not found.
Example: ask_about_competitor({ competitor: "Collibra", question: "How does Collibra price?" }) then get_task({ task_id: "…" })

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `question` (`string`, required): The question, in full.
- `competitor` (`string`, optional): Tracked competitor name (case-insensitive) or id. Omit to ask across all. An untracked rival cannot be named here: omit it and put the name in the question.

Example input: `{"question":"<question>"}`

### `calvenmcpoauth_ask_the_market`

Ask the market · Write

Starts a background research run that answers ONE market question with a cited answer: size and growth, budgets, pricing norms, regulation, shifts in the field.
Use when: the question is about the market, not this company or one named rival, and stored data may not settle it. It uses stored trends, analyst findings and buyer evidence first, then the web for gaps.
Do NOT use when: the question is about one rival (ask_about_competitor), or stored data is enough (the read tools are instant).
Args: `product` frames the "what it means for us" section.
Returns: RETURNS IMMEDIATELY with { task_id, status, poll_after_seconds }; the answer is NOT here and takes minutes. Poll get_task(task_id) while status is "working"; at "completed" it holds the cited answer, its confidence, freshness and what was not found.
Example: ask_the_market({ question: "How fast is the GRC software market growing?" }) then get_task({ task_id: "…" })

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `question` (`string`, required): The market question, in full.
- `product` (`string`, optional): Product name, e.g. "Billing" (case-insensitive; an id also works): frames "what it means for us". Omit for the whole company. A wrong name returns the valid names; so does list_products.

Example input: `{"question":"<question>"}`

### `calvenmcpoauth_review_against_personas`

Review against personas · Write

Starts a background review of a piece of text against this workspace's buyer, stakeholder and user personas.
Use when: you have drafted copy, an email or a message and want it pressure-tested against the real audience.
Args: `scope` narrows to one persona type. `product` runs the review against that product's personas plus the company-wide ones.
Returns: RETURNS IMMEDIATELY with { task_id, status: "working", poll_after_seconds }. The review is NOT in this response. Call get_task(task_id) after poll_after_seconds and repeat while status is "working"; at "completed", get_task carries the severity-rated findings.
Example: review_against_personas({ text: "…" }) then get_task({ task_id: "…" })

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `text` (`string`, required): The text to review: the copy, email, or draft to pressure-test.
- `product` (`string`, optional): Product name, e.g. "Billing" (case-insensitive; an id also works): review against that product's personas plus the company-wide ones. Without it: every persona. A wrong name returns the valid names; so does list_products.
- `scope` (`string`, optional): Buyer, stakeholder or user personas. A stakeholder gates the purchase without buying it. Omit for all three. One of: `buyers`, `stakeholders`, `users`.

Example input: `{"text":"<text>"}`

## Related

Other Marketing connectors ([all 190](/agentkit/connectors/?category=marketing)):

- [HubSpot](/agentkit/connectors/hubspot/): Scalekit connector, OAuth, 457 tools
- [Mailchimp](/agentkit/connectors/mailchimp/): Scalekit connector, OAuth, 73 tools
- [Twitter / X](/agentkit/connectors/twitteroauth/): Scalekit connector, OAuth, 92 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |
