MCP server and AI apps
Tool reference: reads
Every read tool, what it returns, its key inputs and how staff and clients use it.
Tool reference: reads
All read tools need hsai.read. They change nothing, so apps call them without asking. Staff pass engagement_id from list_clients; client users never need it. Every read is still audited against the person.
Account and partners
| Tool | What it returns | Key inputs and defaults |
|---|---|---|
list_clients | The signed-in account (email, ID, role) and the clients it can access. Always the first call. | None. |
list_partners | Partners with one month of PartnerStack revenue, leads, trials and activations. | period (default: previous complete UTC month), sort revenue, leads, trials, activations or name (default name), order, status active, dormant or all (default all), limit 1 to 100, offset. For "top partners" the app uses revenue, descending, active, limit 10 unless told otherwise. |
get_partner_performance | One partner's month: revenue, leads, trials, activations. | partner_id, period (default: current UTC month). |
Partner figures are read-only on every surface. The old manual partner revenue field is retired and always null. Revenue amounts are decimal strings in the currency named in the result.
Dormant means no resolved or partial lead, trial, activation or revenue event in the last 90 days.
Company revenue
| Tool | What it returns | Key inputs |
|---|---|---|
get_monthly_revenue_context | Currency for new months, editable range (first_editable_period to current_period), saved_periods, latest_period, next_due and the Anchor partner revenue share target. | engagement_id for staff. |
get_monthly_revenue | One month by channel (Sales, Marketing, Product-led, Partnerships), total, partner_channel_mix_pct, anchor_target_pct and gap_pp. | period is required; there is no default month. An unsaved month returns MONTHLY_REVENUE_NOT_FOUND. |
Briefs
| Tool | What it returns | Key inputs |
|---|---|---|
search_briefs | Story, Social, Webinar and Event briefs, newest first, with lifecycle status, generation state and asset count. No asset links. | q (title, partner name or public ID), partner_id, asset_type, status (draft, awaiting_dispatch, dispatched, live, done), limit up to 50. |
get_brief | The full brief: partners (host first), lifecycle, generation state and any failure with its recovery, deliverables with short copy inline and private links, complete, registration state and URL, regeneration targets, promotions. | Exact brief_id. |
get_brief_graphic | One Webinar graphic shown inline as a JPEG, at most 1200 px on the long side. A stale render comes with a note to regenerate the kit. | brief_id, slot from get_brief. graphic_unavailable means no render exists. |
get_brief_timeline | Decision history: strategy routing, dispatch, and approvals and regenerations made through the API, MCP or Slack, each with its surface. Portal approvals are not listed. | brief_id, limit, cursor. |
Asset links are private. A Webinar kit archive link lasts seven days and stops working if any output changes.
Staff-only reads
| Tool | What it returns |
|---|---|
get_activate_readiness | The client's Activate programme readiness and each required check with its status. Read it before activate_programme. |
get_riley_publish_preflight | Whether the Riley pack can be published: readyToPublish, publishAction, revisionToken, blocking issues by field and the current strategy draft with its lock versions. |
Client users who call these get "Staff permission required".