GTM Otto

Who this key belongs to, and what the workspace may do: org name, plan, subscription status, how many products and plays exist, and the LEAD METER (leads added this calendar month, the plan's cap, and what is left). Start here — the remaining lead allowance is the one number that changes what is worth proposing. Read-only.

Takes no parameters.

Every play in the workspace with enough context to route on: which product it sells, whether it is active or paused, whether a LinkedIn seat is actually connected (`seatConnected: false` means the play cannot act, whatever its status says), and how its leads are spread across the pipeline stages. Read-only.

Takes no parameters.

ONE play in full — everything needed to judge it or copy it into a better one: goal and voice, the account's daily cap and working hours (shared by every play on the seat), the ICP facets, the five sourcing lanes with their config and last run, the autonomy ladder (which rungs run alone and which wait for a human), the LinkedIn seat, and today's used/cap for the seat plus this play's share. Read-only. Pass a playId from gtm_list_plays.

The play's Stats screen: the pipeline (leads sourced → warmed → invited → new connections → conversations started) over four windows — all time, last 30 days, last 7 days, last 24 hours — each windowed count paired with the window before it as a percentage delta. 'Conversations started' counts real replies, never the openers Otto sent. Read-only.

The play's LinkedIn seat and today's headroom against the LinkedIn limits. States: `no_seat` (nothing connected — the play cannot act), `seat_broken` (the account was disconnected or deleted; the queue is parked until a human reconnects), `pending`, `classic`, or `sales_navigator` (which search backend the ICP compiles to). Read-only. Connecting a seat is a browser flow — link the human to the cockpit for it.

How big an audience a CANDIDATE ICP would reach — '≈ N companies match' — before committing to it. Writes nothing: no play, no ICP row, no cache. Use it to iterate (propose facets → see 40 → widen the locations → see 900 → then create the play). Returns null when the data provider has no key configured, which is not an error. Needs a write-scoped key only because it rides the gateway's action channel.

Create a fully-configured play in one call: the product (an existing productId, or a websiteUrl which seeds one and kicks its research), the play itself, the ICP facets, which sourcing lanes are on, the autonomy ladder and the caps. Three rules are enforced server-side and cannot be talked around. (1) `activate` DEFAULTS TO FALSE — turning a play on spends the month's lead quota and takes real actions from the user's own LinkedIn account, so hand the human the returned cockpit link and let them press go. (2) A play with no live LinkedIn seat stays a draft whatever you pass. (3) Autonomy rules are written ONLY for the steps you name; every step you omit keeps gtmotto's own default, which is 'wait for a human'. Lanes that need their own seeds (post_engagers, competitor_posts, account_list) are refused if switched on without them.

THE REFERENCE for configuring sourcing lanes — read it before your first gtm_configure_source / gtm_set_source / gtm_run_source call. Every lane (people_search, competitor_posts a.k.a. Post discovery, job_offers, account_list, and the retired post_engagers), every config field with its meaning, default and cap, the fit/intent/post gates, what makes a lane runnable, how the 5-minute tick and the 24h cadence work, what a preview costs versus a run, and what this surface deliberately will not do. No backend call; safe to call any time.

Takes no parameters.

All five sourcing lanes of a play, configured or not — the read to make before touching any of them. Per lane: `configured`, `on`, the parsed `config` (defaults filled), the cockpit's `summary` (null = needs setup), `blocked` (why it cannot run, judged without running: needs_config / icp_empty / null), last/next run and the last run's funnel, `addedToday`, `failures`, and the lane's memory — `accounts[]` with `found: true|false` per typed company on account_list, `harvestedPosts` on the post lanes, the cached `searches` the model wrote on Post discovery. Play level: `state` is the same verdict the cockpit shows when the Leads table is empty (no_sources / paused / draft / no_seat / seat_broken / icp_empty / needs_config / lead_quota / never_ran / no_results / provider_error / added_nothing / ok), plus provider, seat, ICP facet count and the month's remaining lead quota. Read-only.

The run history of ONE lane, newest first — the funnel over time (scanned → dropped by fit → dropped by intent → added / duplicates / capped), the ICP facets LinkedIn could not filter on, and the provider's status and message when it refused. Use it to tell 'the query returns nobody' from 'everyone was already a lead' from 'LinkedIn is rate-limiting the seat'. Read-only.

Write a lane's settings — upload an account list, set the Post-discovery intent and anchors, change the job keywords, move a gate. MERGE semantics: only the fields you send change. Lists (companies, postUrls, competitors) REPLACE by default; pass listMode 'append' to add to what is there (deduped, case-insensitive). Caps: 100 companies, 25 posts, 25 anchors — what did not fit comes back in `truncated`. Unknown fields are refused. Saving creates the lane's row if it never had one (OFF, because configuring is not switching on), makes the lane due again immediately and resets its retry backoff; on account_list it also forgets the cached misses so unfound companies are looked up again. Pass `on: true` to switch it on in the same call — refused, with nothing saved, if the lane would still have nothing to run on. Nothing runs inside this call: an ON lane on an ACTIVE play runs on the next tick (≤5 min); otherwise use gtm_run_source. Read gtm_sources_reference for each field's meaning.

Switch a lane on or off — the toggle on the Sources list. Switching ON a lane that has nothing to run on (no companies, no intent/anchors/posts, no role) is refused: configure it first. An empty ICP is not a refusal — people_search may go on ahead of the ICP and comes back `blocked: icp_empty` until gtm_update_icp fills it. Switching OFF never fails and creates nothing. The lane then runs (or stops running) on the daily cadence; nothing runs inside this call.

Dry-run ONE lane: '≈ N people match' and a 10-person sample, WITHOUT inserting a lead, spending the day's budget or moving the run clock. Same query, same gates, same scorers as a real run, on up to 50 people — so what it shows is what a run would keep. `size.precision` is honest: 'exact' (the query ran out inside the probe), 'atLeast' (the probe filled up; LinkedIn reports no total) or 'unavailable' (no seat, no config, paused play — `skipped` says which). Reports the ICP facets LinkedIn could not filter on (`unmapped`), facet values it had no id for (`unresolved`), which sampled people are `alreadyALead`, and on account_list what each company resolved to. Costs provider calls and, when a gate is on, model tokens. Refused on a paused play.

'Run once now' — run ONE lane immediately through the same code the sourcing tick runs, with force: an OFF lane still runs (that is what run-once means while configuring), a DRAFT play still runs (how you try a lane before launch), a PAUSED play does not. REAL: provider calls are made, leads are inserted, the play's daily budget and the org's monthly lead quota are spent. Only call it when the human asked for a run in this conversation; to look without spending, use gtm_preview_source. Returns the run's funnel (scanned / dropped / droppedIntent / added / duplicates / capped), the unmapped ICP facets, and `skipped` + `reason` when it could not run (no_seat, needs_config, icp_empty, daily_cap, lead_quota, no_results, provider_error).

The tuning escape hatch for the post lanes. A post lane remembers every post it already paid to harvest so it never buys the same engagers twice — which makes it impossible to TUNE: change the intent or a gate, run, and the answer is 'no new posts since last time'. This clears that memory so the next run (or gtm_run_source) judges today's posts against the new settings. It COSTS: every forgotten post is a fresh engager fetch. Call it only after a deliberate settings change the human wants re-tested. Only competitor_posts and post_engagers have this memory.

Change the ICP a play runs — the query behind people_search and the fit gate on every other lane. Seven string arrays, plain words (gtmotto normalises 'Swiss' → Switzerland, 'Fintech' → Financial Services itself): titles, seniority, languages, industries, sizes (headcount bands like '11-50'), locations, exclude ('never contact' — absolute). ONLY the facets you name change; the first write on a play forks its own ICP row from the product baseline (or a sibling play's row), so no other play's targeting is rewritten. Filling an empty ICP unblocks lanes parked on icp_empty and kicks the play's due lanes if it is active. Size a candidate first with gtm_estimate_icp.

Change a play's own knobs — name, goal, voice — its two switches, and the ACCOUNT's pacing (daily action cap, working hours: shared by every play on the LinkedIn account, not per play). `paused: true` is the human's stop button (nothing runs, nothing is sent); `paused: false` resumes. `status: 'active'` LAUNCHES a draft; `status: 'draft'` takes it back off the road. Seat rule, enforced server-side: no live LinkedIn seat ⇒ neither launch nor resume makes it active — it stays/falls back to draft and the note says so. Launching or resuming kicks the play's due lanes at once. Only launch, resume or raise the cap when the human asked for it in this conversation: an active play spends the month's lead quota and acts from the human's own LinkedIn account. Does not touch the autonomy ladder.

The link a human opens to connect (or reconnect) their LinkedIn account to a play — the one cockpit step the play cannot run without. Hand the URL to the human, tell them to say when it is done, then call gtm_linkedin_status: the seat reads `classic` or `sales_navigator` once bound. The link expires in 15 minutes; call again for a fresh one. Nothing is sent, nothing is read from their account by this call.

Every drafted action that waits for the human — an invite note, a first message, a follow-up, a reply or a comment the planner wrote — with the draft, the 'why now', the lead, and a cockpit link. One play, or the whole workspace when playId is omitted. Show each draft to the human before gtm_approve / gtm_reject; never decide for them. Read-only.

Approve ONE drafted action by its approvalId (from gtm_list_approvals). It then leaves on the seat's next slot, inside LinkedIn's limits — this is the human's tap, moved from the cockpit to the chat, so ONLY call it after showing them the draft and getting a yes in this conversation. An already-decided card is refused.

Reject (skip) ONE drafted action by its approvalId. Nothing is sent; the planner records the decline and re-plans around it instead of proposing the same step again. Ask the human first, as for gtm_approve.