HockeyStick Knowledge Base Knowledge Base Open Command Centre

MCP server and AI apps

Tool reference: revenue and diagnosis

Logging the company's monthly revenue by channel, and saving dormant partner diagnoses.

Tool reference: revenue and diagnosis

Two write tools touch numbers: one replaces a month of the company's revenue, the other saves a diagnosis of dormant partners. Both need hsai.write.

log_monthly_revenue

Replaces one month of the company's revenue by channel: sales, marketing, plg (Product-led) and partnerships. All four are required. It runs the same save as the Activate "Log monthly revenue" screen, so Activate Home, the metrics snapshot and monthly review work update exactly as if the client saved it in the portal.

Who can use it: client users only, inside their own organisation. Staff are refused with 403 CLIENT_WRITE_REQUIRED, so you can read a client's revenue but never log it for them. The client also needs Activate.

Which months: the current month and the previous 23. Other months return revenue_period_unavailable.

How the app must confirm:

  1. Read get_monthly_revenue_context for the currency and editable months.
  2. Expand units ("4.7M", "4,700k" and "4700000" are all 4700000). A figure under 1,000,000 with no unit is ambiguous: ask whether it is in thousands.
  3. Show the month, all four full amounts with the currency (for example "USD 4,700,000"), and whether it replaces a saved month.
  4. Save only on explicit confirmation, passing expected_updated_at from the month read (or null for an unsaved month).

Afterwards it reports the total, partner_channel_mix_pct and the gap to the Anchor target. The replaced figures are kept as history, which only staff can read.

OutcomeWhat to do
MONTHLY_REVENUE_CHANGEDSomeone changed the month. Read it again and reconfirm. Nothing was saved.
REVENUE_SAVE_OUTCOME_UNCONFIRMED or a timeoutDo not repeat. Read the month back with get_monthly_revenue.

This is not partner revenue. PartnerStack figures are read-only everywhere, and the old per-partner revenue write is retired.

record_diagnosis

Saves which partners are dormant (no resolved or partial lead, trial, activation or revenue event in the last 90 days), with a server-selected recommended next action for each. The recommendation text comes from approved category copy; the caller cannot supply it.

  • Inputs: an idempotency_key (one per diagnosis), optional partner_id to diagnose one partner. Staff must pass engagement_id or partner_id; a staff call never uses an implicit client (CONTEXT_REQUIRED).
  • Repeats are safe with the same key. Repeating with the same key and filter returns the stored rows with replayed: true. To reconcile an uncertain result, repeat with the same key, never a new one.
  • Nothing to diagnose: with no dormant partner nothing is stored.
CodeMeaning
idempotency_key_reusedThe key was used for a different diagnosis. Nothing was saved.
recommendation_unavailableNo approved recommendation exists for a dormant partner's category. Nothing was saved.