Trial workflows

Five workflows an agency or brand runs during a trial_100_v1 trial, or explores before starting one. Each has a real-trial path (your own workspace, real capacity) and a demo path (a fictional five-client portfolio, demo_portfolio_v1) — use the demo path to see the shape of the output before spending any trial allowance on it.

Call get_account_context first. trial is non-null there (and on get_plan_and_usage) exactly while your organization is on a trial — state is one of active/expired/suspended/retired.

The demo portfolio

get_workflow_examples { workflow } returns static, fixture-backed example output for any of the five workflows below — no database or provider call, ever. Every payload is prefixed "Sample data — not live brand results" and carries version: "demo_portfolio_v1". The fixture is five fictional clients (Northwind Dental, Harbor & Vine Coffee, Summit Trail Outfitters, Bluefin Analytics, Maple Grove Pediatrics), 8 buyer-intent questions each, and 4 weeks of labeled answers across the three included platforms (chatgpt, gemini, google_ai_mode) — including one deliberately-included provider-failure row, so the sample also shows how a failed collection attempt reads. Call get_workflow_examples with no trial active at all, or before onboarding your first real brand, to see what each workflow produces.

Allowance semantics

A trial_100_v1 grant is a fixed, lifetime pool per organization — not a recurring monthly allowance. get_trial_usage reports, for prompts, daily watchlist slots, refreshes, attempt units and AI generations: used/reserved/cap/remaining for each. remaining reaching zero on any dimension means every write against that dimension is refused (trial_prompt_limit, trial_refresh_limit, trial_attempt_limit, and trial_report_limit for AI generations — the trial's AI writing allowance, not a report count) until you upgrade — create_upgrade_link returns a URL for that, and never charges anything itself (opening the link is what starts a real checkout). Once the trial's endsAt passes, every read tool still works (get_trial_usage included), but preview_collection (and every other write) refuses trial_expired with an upgradeUrl in its detail.

The five workflows

prospect_audit

Run a prospect's own buyer-intent questions across all four included platforms once, before spending any ongoing trial capacity monitoring them. Real-trial path: preview_collection { promptIds, kind: 'refresh' } to see the refresh/attempt-unit cost before committing, using whatever prompts you have configured for the prospect. Demo path: get_workflow_examples { workflow: 'prospect_audit' } shows Northwind Dental's week-1 results — "does this brand show up at all today", not a trend (a trend needs more than one week of collection).

weekly_client_report

A weekly narrative per client: visibility, sentiment and competitor mentions for the week, plus 2-3 action items. Real-trial path: get_trial_usage for allowance context, plus your own answer history for the week. Demo path: get_workflow_examples { workflow: 'weekly_client_report' } returns Harbor & Vine Coffee's full weekly-report shape — the same shape a real workspace's report-generation tools produce.

daily_watchlist

A small, high-priority subset of questions tracked every day instead of on a weekly cadence, up to the trial's dailySlots cap (get_trial_usage). Demo path: get_workflow_examples { workflow: 'daily_watchlist' } returns Bluefin Analytics' latest day, including a provider_error row — a failed collection attempt for ONE question on ONE platform, not evidence the brand was actually absent; retry rather than reading it as a visibility drop.

portfolio_report

One rolled-up view across every client workspace: latest visibility, trend direction, and which clients need attention (declining trend, or visibility under 55%). Demo path: get_workflow_examples { workflow: 'portfolio_report' } rolls up all five demo clients this way — the shape a real portfolio-entitled organization's get_portfolio_summary / get_clients_needing_attention / get_clients_with_visibility_decline tools produce.

monthly_action_plan

Look across the full 4-week window (not just the latest week) before deciding what to change — weighting the trend over any single week's number matters here: a client can dip one week and recover, which a single-week snapshot would misread as a real decline. Demo path: get_workflow_examples { workflow: 'monthly_action_plan' } returns Maple Grove Pediatrics' full 4-week trend plus example action items.

What a connected assistant can and cannot call

A connection — a personal access token (apt_…) or an OAuth sign-in alike — gets its write scopes from your CURRENT membership role, never from a fixed read-only grant and never from anything the token itself claims. See authentication.md's role table for the exact grant per role: organization_owner/organization_admin get reads + content writes (brand:write, prompt:write, report:write, workspace:write) + run (run:execute, run:cancel); agency_analyst gets reads + content writes only; client_admin/client_viewer stay read-only.

Those write and run grants are switched on per deployment: they apply only where MCP_CONNECTION_WRITES_ENABLED=true is set on the MCP service. Where it is off (the default), every connection is read-only whatever its role, and the write and run tools below are simply not listed.

Never reachable over MCP, whatever your role or connection type:

• member:manage, billing:manage, org:manage, webhook:manage, workspace:archive, report:approve and report:send are never granted to a connection — those stay console-only. create_upgrade_link and the member/key-management tools are typical.
• Every personOnly tool — allocate_workspace_capacity, set_market_profile, the member/key-management tools and the rest — is unreachable from a personal access token regardless of role, even organization_owner: a personOnly tool needs a human signed in through OAuth, which a token by itself never is (authMethod: 'personal_token', not 'oauth').

Three things a reader is easily wrong about:

• request_approval is listed for every role — it is tier 0 and carries no scope of its own — but it runs the TARGET tool's own workspace, scope and role checks before it will mint anything, so it is never a way around any of the above. An owner/admin connection holding prompt:write CAN reach a tier-5 prompt tool (delete_prompts, finalize_prompt_candidates, …) through it, exactly as an agency_analyst connection with prompt:write reaches a tier-2 one directly — the role table, not the approval mechanism, decides what is reachable.
• preview_collection and validate_prompts are available to every role: the first is run:read and only prices a collection, reserving nothing and calling no provider; the second is prompt:read and only checks prompt text, with no write mode. Neither writes anything.
• Spending the organization's allowance — run_question_now, retry_failed_executions, onboard_brand, generate_buyer_questions, discover_keywords, get_keyword_volumes, expand_topics — is NOT blocked just because the caller is "a token": an organization owner or admin connection, personal access token or OAuth alike, reaches every one of these. A non-owner/admin connection never even reaches this rule for the two run:execute tools (run_question_now, retry_failed_executions) — that scope is never granted below owner/admin, so those are refused forbidden_scope first. But the other five are prompt:write/brand:write, which an agency_analyst connection DOES hold — this rule is what refuses onboard_brand, generate_buyer_questions, discover_keywords, get_keyword_volumes and expand_topics to it anyway, with forbidden_role, specifically because holding the scope alone isn't enough for a tool that spends the organization's allowance.

Everything read-only in tools.md — including get_collection_status, get_engine_health, list_runs and get_trial_usage — is available to every role. Ask the assistant to run describe_capabilities to see the exact split for its own connection.

Collection mode (paid organizations, not trials)

get_collection_mode_options, preview_collection_mode_change, request_collection_mode_change, get_pending_collection_mode_change and cancel_collection_mode_change switch a PAID organization between weekly_coverage and daily_focus tracking. A trial organization gets a typed refusal (mode_change_not_available) from any of these that would attempt or describe a change — a trial has one monitoring profile, not a mode to switch; choose your paid mode at checkout instead (create_upgrade_link). Only an organization owner or admin may call these — any other role, or a service-account token, gets forbidden_scope.