How to connect VarynForge with Python

Get the VarynForge agent guide — workflow paths (free vs paid), token-economy rules, walls and upgrade conversation conventions. Read this at session start.

Get the URL of the VarynForge product changelog — what shipped, newest first, in plain markdown. Fetch it when the operator asks what is new, and in the days after a send_feedback report to check whether the gap they hit has been closed.

Get the writer system prompt for drafting one content type from its brief. The writer works with your Varyn account context: every channel prompt binds to the brief, its acceptance rubric, and the opportunity behind the brief fetched from the account, and degrades to generic writing advice without them. Pass `channel` (article | x | linkedin | reels | youtube) — each channel has its own methodology: article covers voice adaptation, structure rules, and the acceptance checklist; x covers thread mechanics; linkedin covers post + carousel slides; reels and youtube cover the production script (brief -> script -> video). Load the prompt for the channel you are about to draft; article is the default.

Get the operator account status — the organization whose plan/credits/limits this payload describes (plans and usage limits are per-organization; see list_organizations), current plan, available credits, brief quota state, the lint_draft daily verification cap (applies on every tier; check lint_drafts_remaining_today before a verification loop), the idea_checks allowance (check_idea is daily- AND monthly-capped on every tier; check remaining before a check loop), locked paid tools, the upgrade URL, and next_actions: the ranked cross-project queue of what to do next. Defaults to the personal organization; pass organizationId when working a project that belongs to a different organization — its shared caps are the ones project actions consume. Read on session start and after a wall hit.

List the organizations this account belongs to — id, name, your role (owner | admin | member), is_personal, plan, and member_count — plus pending invitations awaiting a response (accept them in the web app). Plans, credits, and usage limits are per-organization, and a project belongs to exactly one organization. Pass an organizationId to create_project to target a specific organization, or to get_account_status to read that organization’s caps.

Diagnose where the operator is in their VarynForge journey and get a guided setup path. Call when the operator asks to set up VarynForge, get started, or seems unsure what to do next — and always when list_projects returns empty. Returns the server-derived stage, a stage-tailored pitch to relay to the operator, a setup checklist with done/pending status per step, and the ranked next_actions queue. Diagnose before prescribing: never run the welcome pitch on an operator whose stage says producing.

File a note to the VarynForge team: a bug, a missing capability, a friction point, or an operator idea. Call when you hit something VarynForge cannot do, a confusing tool result, or the operator voices frustration or a wish. Whenever the task would benefit from a capability this tool list does not offer, file a missing_capability BEFORE you settle for a workaround with existing tools, even if they could work as a fallback. Do NOT file entitlement walls (PAYMENT_REQUIRED / RATE_LIMITED / FEATURE_LOCKED payloads) — those are working as designed. Feedback is a note to the team, never a ticket: do not promise the operator it will be fixed. There is no reply — read get_changelog over the following days to see whether the gap closed.

Create a new project — pass either a website URL or a niche description (or both). Returns projectId immediately; niche analysis and asset mapping run async. Poll get_project until niche.analysisStatus is ready. When the operator says whose site this is, pass siteRelation: mine (their own), client (an existing client), or prospect (a site they are pitching) — ask only if it is ambiguous, never guess. Optionally pass organizationId (see list_organizations) to create the project in a specific organization; it defaults to the personal organization.

Get one project — its canonical name (operator-set, falling back to site brand then niche name), niche profile, target audience, current research status, and postsPerWeek (the operator’s publishing cadence, settable via set_posting_cadence; sizes the pitch report’s 90-day sequence). Address the project by `name`; `niche.name` is the market niche, not the project name.

Get the asset (website/product) associated with a project — URL, name, description, solution profile.

Update a niche profile — name, industry, language, country, target customer, core problem, related terms. Use after the operator refines their market definition; omitted fields keep their current values.

List the project's destinations — where the operator publishes (website, youtube_channel, tiktok, instagram, x, linkedin, local_business). Destination type ids are the `format` labels lint_draft stores drafts under. Each row carries its capabilities so you never cross-reference other tools: `briefChannel` is the brief/lint channel the type maps onto (null for open slots), `verifiable` says lint_draft can grade drafts for it, `publishable` says it is live and its published URLs can be recorded, and `publishVia` names the recording tool (mark_article_published for article-channel destinations, register_derived_asset for social/video; null while planned). An empty list means the operator has not configured destinations — add one with add_destination, or fall back to the brief channel name as the lint_draft `format` label.

Add a destination to a project — where the operator publishes. Pass `type` (website | youtube_channel | instagram | tiktok | x | linkedin | local_business) and `name` with `state: 'detected'` for a destination that already exists and belongs to the operator (website name = the domain like yourdomain.com; social types = the handle, @ optional), or `state: 'planned'` for one they intend to build (name is held, no live URL yet). Confirm the type and name with the operator before adding — this shapes where briefs, drafts, and lint formats anchor. A project holds up to 10 destinations; manage or remove them in the web UI.

List companies for a project — marked competitors (important / default / ignored) and SERP-discovered companies (unmarked). Sorted important → default → unmarked → ignored, then by domain. Pass `importance` to filter to one bucket. Capped at 100.

Mark a competitor important, default, or ignored. Important applies a 1.25× boost on opportunity scores for clusters where the competitor ranks top-10. Scores are then normalized 0-100 against the highest-scoring cluster, so other clusters may appear to drop in relative ranking even when their absolute (raw) scores did not change — cross-check via get_opportunity_detail.rawOpportunityScore. Ignored hides the competitor from competitor surfaces and the editorial-score pipeline.

Add a competitor to a project by domain (e.g. example.com). Marks the competitor as important or ignored on creation.

Correct the inferred profile of the project asset — description, primary offer, benefits, key differentiators, use cases. Use when get_project_asset shows claims that contradict what the operator actually sells (profileStaleAt set, or the operator says so). Only the fields you pass are written; arrays replace the whole list. No re-crawl happens. Clears the profileStaleAt flag.

Set how many articles per week the operator actually publishes (1-14). Sizes the pitch report’s 90-day content sequence; read back via get_project.postsPerWeek.

Re-read the project website and re-infer the asset profile (name, description, primary offer, benefits, differentiators, use cases) from its current content. Use before rendering a report when get_pitch_report_payload flags assetProfile.syncedBeforeRun — the stored profile facts may have drifted since they were written. Overwrites the profile facts (fields the site no longer supports inferring are left unchanged, never nulled) and stamps profileSyncedAt; the niche is not touched. Rate-limited per site; returns an error naming the wait time if the cooldown is active.

Re-crawl the project website and refresh its owned pages. Use when get_project_asset shows mappingStatus "error" or owned pages look stale. Rate-limited per site; returns an error naming the wait time if the cooldown is active.

Start a research run for a project — discovers keywords, evaluates competitors, and writes opportunity clusters. Consumes one credit. Returns `{ runId }`; poll get_research_status for progress. Returns `{ entitlement }` instead when the operator is on the free plan.

List all projects for the authenticated operator — paginated, sortable by createdAt, niche, or industry. `name` is the canonical project name (operator-set, falling back to site brand then niche name) — match operator references against it; `niche.name` is the market niche, distinct metadata. lastActivityAt is the most recent change to the project or any of its content pieces — when the operator says "my project" without naming one, the highest lastActivityAt is the right pick.

Get a competitor company detail in a project context — domain, name, importance, top pages in the project SERPs, and top keywords they rank for.

Get the at-a-glance read on a project — niche summary, keyword stats, nextActions (the ranked queue of what to do next in this project — offer its first entry when the operator asks "what now?"), and topPriorities: the ranked queue of article suggestions (best first — priorityScore desc; radar-born suggestions carry no score until briefed and rank oldest-first below scored ones; source tells you why score/cluster may be null). Entries already at ready_to_publish or published are done, not next — "do the next piece" = the first entry whose status still needs work (planned, brief_ready, drafting, draft_ready, reviewing).

Poll the latest research run for a project — runId, status, current pipeline phase, progress percent, elapsed seconds, and structured failure diagnostics when failed. failure carries failureClass (upstream_timeout | upstream_rate_limited | invalid_input | internal | unknown), the phase the run died in, retryable (true = transient upstream issue, safe to retry; false = retrying will fail again — fix inputs or report it; null = unknown, retry at most once before reporting), and the raw message. A running run with phase "initializing" and large elapsedSeconds is stalled, not queued — report it instead of waiting. Token-light: returns a small fixed shape, no step payloads.

Assemble the client-ready pitch report payload for a completed research run — niche + solution profile, competitor landscape, ranked opportunity map holding GAPS ONLY (0-100 normalized; demand sized as volumeBucket buckets, no search-volume numbers by design; each entry carries overlapStatus net_new|partial plus siteOverlap — covered-keyword share + closest owned pages), coveredOpportunities as a separate defend-and-refresh list (topics the site already covers — never pitch these as new work), and a derived 90-day content sequence sized to the project posting cadence (postsPerWeek, up to 12 weeks; planned articles first, then gap topics marked type: topic — topics to develop, not article titles; covered clusters never enter the sequence; entries may carry advisory notes — near-duplicates, already-published near-matches, working titles needing a rewrite — keep the notes visible when rendering). assetProfile reports when the profile facts were last synced; when assetProfile.syncedBeforeRun is true, offer the operator the choice between resync_asset_profile first and rendering with the profile as-is, and always render the "Asset profile last synced <date>" stamp. renderGuide carries the full report structure with an explicit branding slot: render it in the operator’s own template (Docs, Slides, Notion, or PDF) under the operator’s name. Included with every run, no extra cost. Pass the runId from get_research_status; a run that is not completed returns { runStatus, report: null }.

Get the free starting-point report for a project — a client-facing document assembled from setup-time data: positioning (niche + market profile), the site and its current content inventory, the curated competitor set, and early rising-topic signals. Free on every plan, no research run required. markdown is the ready-to-send render; the structured fields are the same data for custom rendering. lockedSections names the sections a research run adds (full opportunity map, 90-day sequence, competitor gap analysis) — absent here, not previewed. Once the project has a completed run, prefer get_pitch_report_payload: that is the full report.

List content opportunity clusters sorted by opportunity score. Goal filters: fast_wins, high_intent, authority_building, competitor_gap. coverage filters by site-coverage status and defaults to ["gap","partial"] — clusters the site already COVERS (ranks top-10 for a cluster keyword) are hidden unless "covered" is included (refresh candidates). Dismissed clusters (set_opportunity_status) are hidden, and keywords matching the project exclusion terms (set_excluded_terms) down-weight their cluster scores. Clusters flagged by the asset-fit assessment (fitFlag unservable_feature | off_catalog, with fitReason explaining why) are down-weighted rather than hidden — treat them as comparison-content candidates at best, never headline opportunities. Scores are normalized 0-100 against the highest-scoring visible cluster, so coverage filtering, dismissing, excluding, or fit-flagging can shift the relative numbers of other clusters.

Get a cluster detail — top-20 keywords by score, top-10 ranked pages by position, top-5 competitor podium, linked article suggestions, and rawOpportunityScore (un-normalized; list_opportunities returns the 0-100 normalized version).

Dismiss or restore an opportunity cluster. status=dismissed hides it from list_opportunities and the create_content_plan_from_opportunities harvest; status=default restores it. Dismissal lasts until the next research run rewrites the project clusters — for a durable "not my product" signal use set_excluded_terms. Removing a cluster from the pool changes the 0-100 normalization of every remaining cluster.

Set the project-level exclusion terms — products or topics the operator explicitly does NOT sell (e.g. "wedding suite", "free template", "printing"). Keywords mentioning any term are down-weighted in opportunity scoring and dropped from the content-plan harvest, before results reach the operator. Replaces the whole list; pass [] to clear. Survives research re-runs, unlike per-cluster dismissal.

List keywords tracked for a project — text, difficulty, intent, volume bucket (no_traffic | long_tail | average | high). Paginated; supports sorting and intent filter.

Get a keyword detail — pages ranking for it with positions and ownership, plus related keywords already tracked in the project.

List ranked pages tracked for a project — URL, title, company, query count, ownership. Filter by ownership or company domain.

Get a page dossier — URL, title, project rankings, ownership. `headingOutline`, `targetKeywords`, and `contentAnalysis` populate for owned (asset-mapped) pages only.

List article suggestions for a project — title, status, priority, cluster, intent, source, publishedAt, scheduledFor, and a per-channel distributions rollup ({ channel, count, latestAt, scheduledFor } per channel the content went out on). Use distributions to spot gaps from the list alone — e.g. items with no linkedin entry have no LinkedIn post yet — without per-item reads. Page through suggestions; call get_article_suggestion for the full record. Status semantics: generating_brief with briefQueuedAt set means the brief is QUEUED behind the free daily cap and forges automatically at cap reset (get_article_brief returns queuedUntil); generating_brief with briefQueuedAt null means it is actively forging — re-check within a minute.

Create a content plan by harvesting the top-30 opportunity clusters from a completed research run. Auto-creates article suggestions linked to each cluster. Left out of the harvest: dismissed clusters (set_opportunity_status), keywords matching the project exclusion terms (set_excluded_terms), and clusters the site already covers (>=80% of keywords covered — refresh work on existing pages surfaces via editorial scores, not here).

Add a bare article suggestion to a content plan (title + optional intent and reasoning). For richer input that produces a brief-ready suggestion, use create_article_suggestion_with_input.

Create a brief-ready article suggestion from the operator's own input. Auto-resolves a default content plan; creates/links search-query rows for the keywords; returns suggestionId + contentPlanId. Free-tier compatible (no research run required).

Move an article through the production pipeline. Statuses: planned, generating_brief, brief_ready, drafting, draft_ready, reviewing, ready_to_publish, published. For the published transition use mark_article_published instead — it records the live URL, which Search Console outcome tracking keys off; setting status to published here records no URL. When the article is scheduled to go live later (CMS/external scheduler), pass scheduledFor with the planned date — it shows in the app and holds the "stalled at ready_to_publish" flag until the schedule lapses; do NOT call mark_article_published before the URL is live, publish auto-detect attests it (and pings IndexNow) when it actually appears.

Forge a writer-ready brief from an article suggestion. `channel` picks the brief template: article (default, SEO article outline), reels (hook/beats/shot list), youtube (retention beats/chapters), x (thread posts), linkedin (carousel slide deck: cover hook, one-idea slides, recap, CTA). A suggestion holds one brief per channel — generating a second channel adds a brief without touching the others. When the suggestion already has an article brief, channel briefs DERIVE from it (its key points, hook, and keyStats flow into the channel shape) and are free — they do not consume a daily brief slot. Idempotent per channel: if that channel already has a brief, returns it without consuming a slot; pass `force: true` to regenerate it. When regenerating, pass `guidance` — corrective direction the forge must follow (e.g. the angle the operator actually wants, a section to drop, an audience correction) — instead of re-rolling blind and hoping. Free tier: 10/day for article briefs and non-derived channel briefs. Returns `{ entitlement }` when the daily cap is reached.

Get article suggestion details — metadata, cluster context, brief availability, registered derived assets (carousels, social posts), target keywords with volumes. Call get_article_brief for the full brief. Status semantics: generating_brief with briefQueuedAt set means the brief is QUEUED behind the free daily cap (forges automatically at reset); briefQueuedAt null means actively forging.

Re-read an article suggestion's verification state without re-linting: the suggestion's single pipeline status plus, per destination `format`, the stored draft and the latest gate receipt (verdict, per-check detail, thresholds) from its last lint_draft submission. Free and uncapped — always use this instead of lint_draft to recover a known verdict. Pass `format` to read one destination including the stored draft text; omit it for the per-destination overview (receipts only, no draft bodies). Status-ownership model: ONE suggestion status drives the pipeline while verdicts are per-destination (N receipts), and status transitions are forward-only — a later flagged submission on one destination never demotes a suggestion another destination already moved to ready_to_publish.

Get the full content brief for an article suggestion. A suggestion holds one brief per channel — pass `channel` (article default | reels | youtube | x | linkedin) to pick which. Every brief carries hookStatement (one verbatim-usable hook sentence naming the reader payoff); article briefs also carry keyStats (a stat bank of { claim, value, source, sourceUrl } entries for evidence blocks and data slides). Pass compact=true to drop referenceArticles (informational only). internalLinks, curatedTargetQueries, and targetKeywords always populate. When the requested channel's brief does not exist yet, returns { hasBrief: false, briefStatus: 'queued' | 'forging' | 'none', queuedUntil } — 'queued' means the forge is waiting for the free daily cap to reset at queuedUntil; poll after that moment.

Delete an article suggestion and its associated brief. Cascades to keyword and cluster links.

Get a brief as inline markdown the host agent can use as a writing prompt. Pass format=markdown_inline, and `channel` (article default) to pick which of the suggestion’s per-channel briefs to render. Returns the brief assembled into a single markdown string capped at ~8K chars — markdown only; the structured fields are get_article_brief’s job and are omitted here.

Record that an article went live at a URL. Flips the suggestion to published, writes the distribution ledger row, stamps the Passport, and pings IndexNow. Call it only once the URL actually resolves — the IndexNow ping fires immediately, and a ping for a dead URL is wasted (search engines crawl, hit the 404, drop it; nothing re-pings later). For a CMS-scheduled article, set scheduledFor via update_article_status and stay in ready_to_publish: publish auto-detect attests it (and pings IndexNow) when it appears. Use this instead of update_article_status for the published transition — a status flip alone records no URL, and without a URL the article is invisible to Search Console outcome tracking (clicks/impressions on the Earnings page). Also works on an already-published suggestion to attach a missing or corrected URL. Pass `publishedAt` (ISO datetime, must not be in the future) when the article went live EARLIER than this call — e.g. attesting after the fact or matching a CMS publish date — so the record carries the real go-live moment instead of the call time.

Register a derived asset (LinkedIn carousel PDF, social post, video, image) produced from an article suggestion. Appends a distribution-ledger row so the suggestion shows everything it produced — the article plus its derivatives — for content-ROI reporting (get_article_suggestion returns them as derivedAssets). Pass `channel` (reels | youtube | x | linkedin) so the app can show per-channel distribution status; register again with a new URL for repeat posts on the same channel — every registration is kept. `scheduledFor` records a future post date from an external scheduler (Buffer etc.) for display only — VarynForge never posts on your behalf. Derivative rows never affect publish status or Search Console attribution; use mark_article_published for the article itself.

Get the verification rubric for an article suggestion: the submission format for the channel (markdown | --- separated thread | post-with-slides | production script), required vs advisory checks, the exact numeric limits each check grades against (checkParams), plus the brief fields lint_draft reads (keywords, outline, FAQ, channel payload). Pass `channel` to read the rubric of that channel's brief (article default) — use the same channel you will pass to lint_draft. Fetch this before writing so the draft passes on the first submission.

Submit a draft for verification against its brief. Returns a pass/flag verdict with per-check detail. Pass moves the article to ready_to_publish; flag moves it to draft_ready for revision. `channel` (article | reels | youtube | x | linkedin) declares WHICH of the suggestion's per-channel briefs the draft is graded against AND the submission shape — always pass it for non-article content; when omitted, the channel is inferred from `format`. Submission shapes (get_lint_rubric returns the same spec + the numeric limits): article = markdown draft; x = thread text with one post per --- separated section, NO links in post bodies (put links in a reply); linkedin = post/caption text first, optional --- separated carousel slides after, NO links in the body (put links in the first comment); reels/youtube = the production SCRIPT — the process is brief -> script -> video, this gate validates the script, and the video is produced after it passes (published URL is recorded at publish time, not here). `format` labels the storage destination: prefer one of the project's destination type ids (see list_destinations) so receipts and drafts group per destination — re-submitting the same `format` replaces that destination's draft, a different `format` keeps both. The response reports the suggestion's post-lint `status` and a `nextAction` hint; `thresholds` is the article ratio block on the article channel and null otherwise (channel limits live in get_lint_rubric checkParams). `waiveChecks` marks check ids the OPERATOR deliberately deviates from (e.g. a brief section they dropped on purpose): waived checks still run and are recorded as waived in the receipt, but no longer fail the verdict — only pass ids the operator explicitly waived, never waive on your own initiative. Verdicts and drafts are stored per `format` and re-readable any time via get_draft_status (free — never re-lint to recover a lost verdict). Status transitions are forward-only: a flagged re-submit never demotes a suggestion already at ready_to_publish or published. Daily-capped (cap and remaining are in get_account_status limits); re-submitting an unchanged draft is served from cache.

One-call writer handoff: returns a compact writing payload for an article suggestion (brief essentials, keywords, acceptance criteria, lint instructions). Compact by design — FAQs cap at 6 and long sections degrade to fit a deep-link budget; the FULL brief is get_article_brief and the full check list is get_lint_rubric, so verify against those, not this. deepLinks (ChatGPT/Claude URLs embedding the payload) is null over MCP — it exists for web users without a connected agent.

Score a raw article idea against the project's niche without writing anything to the plan. Returns a title, angle, search intent, related queries, a coarse demand estimate, and a 0-100 niche-fit score. Pass the returned fields to accept_idea to commit the idea as a brief-ready suggestion.

Commit an expanded idea (from expand_idea) to the content plan as a brief-ready article suggestion. Stores the verbatim idea as provenance, lands the suggestion in generating_brief, and forges its brief automatically (free tier: queues past the daily cap). Returns the new suggestionId.

Attach real search data to one article idea that is already in the project — runs one live Google search per target keyword and returns volume bands and the pages currently ranking for each. Use after create_article_suggestion_with_input, or on any existing suggestion the operator wants judged on data instead of instinct. Opportunity score and cluster placement are returned only when the project has a completed research run to compare against; on a project without one they are absent, and start_research_run is what produces them. Do not use to find new ideas or map a niche — that is start_research_run. Consumes no credits; daily- and monthly-capped per account.

List the latest emergent-topic radar snapshot for a project: rising narrative topics (label, summary, momentum, novelty, drivers, evidence) with per-topic index and how many article suggestions were already added from each. Returns null when the project has no radar snapshot yet. Use expand_radar_topic to turn a topic into article angles.

Expand one radar topic (by signalObservationId + topicIndex from list_radar_topics) into 3-6 candidate article angles with title, intent, and editorial positioning; each angle is flagged when a near-duplicate already exists in the content plan. Optionally pass customPov for angles from a specific point of view. No writes — pass chosen angles to add_radar_topic.

Add selected angles from a radar topic to the content plan as radar-born article suggestions (provenance preserved; exact-title duplicates skipped). Angles come from expand_radar_topic; call list_radar_topics first to get signalObservationId + topicIndex. Auto-creates the content plan when the project has none. Each added suggestion lands in generating_brief and its brief forges automatically (free tier: queues past the daily cap and forges at reset) — do not also call generate_article_brief. Returns the created suggestionIds.