HockeyStick Knowledge Base Knowledge Base Open Command Centre

MCP server and AI apps

Tool reference: briefs

The draft, setup, generate and decide tools for Story, Social, Webinar and Event briefs, with their confirmation rules.

Tool reference: briefs

Brief tools follow one path: start a draft, answer its questions, generate the reviewed version, then approve or regenerate. All of these need hsai.write, and the Activate product allocated. Staff and clients can both use them.

The tools

ToolWhat it doesConfirmation rule
start_briefSaves a Story, Social, Webinar or Event draft from the user's sentence. Story and Social take one partner_id; Webinar and Event can take partner_ids (up to 20, host first). Returns the version, setup, proposed and missing markers and the questions. Never generates.Pass the user's own words. Ask every returned question; never guess.
update_story_setup, update_social_setup, update_webinar_setup, update_event_setupSave only the user's answers against the reviewed expectedVersion. Objects and arrays replace the whole field; omitted answers keep earlier facts.Never invent a transcript, source facts, speakers or an offer. Show proposals before generating.
generate_briefGenerates the reviewed expectedVersion. Returns a queued receipt.Only on the user's explicit request, after showing all proposals. Never fetch a newer version and generate it silently.
decide_briefApproves a ready brief (it becomes live) or queues a regeneration of a Story, Social or Webinar target, with a note for Story and Social.Confirm first. For an Event, tell the user approval opens the public registration page.

Setup controls kept apart from answers

  • Routing: segment, workstream and journey_stage come from the strategy anchor. They are proposed when the anchor has one value, otherwise asked as choices.
  • Strategy decision, always last: strategy_action proceed_off_anchor with the user's strategy_reason, or edit_request with revised_text. A later change to title, description or routing cancels it.
  • Proposals: accept_proposed, for example ["format"] for an Event's proposed format, only with the user's answer.
  • Unscored generation: allow_unscored: true only with explicit permission.
  • Webinar defaults: the first timezone saved for a client is remembered. partner_speakers is saved only with the partner's own speakers after the user reviews them. Both can be cleared with null, and edited in Activate on the partner page.

Formats that trip people up

  • Webinar localDate is YYYY-MM-DD, localStartTime is HH:mm, timezone is IANA, duration 30, 45, 60 or 90.
  • Every Webinar agenda row needs a presenter by speakerIndex, confirmed with the user, or null for a row with no single presenter.
  • Event startsAt and endsAt are full ISO date-times with offset, for example 2026-11-12T18:00:00+10:00.
  • jointOffer: "" is sent only when the user confirms there is no offer.

Common refusals

CodeMeaning
BRIEF_INCOMPLETEQuestions remain; ask them.
setup_validation_failedLists each field, rule and correction. Nothing was saved.
draft_version_conflictThe draft changed. Re-read, show it, reconfirm.
generation_already_requestedRead the brief; do not repeat.
story_branding_requiredPartner branding must be saved in Activate first.
story_approval_placeholders_remainingResolve visible placeholders before approval.
asset_staleRead the current output first.
GENERATION_FUNDING_UNAVAILABLEWebinar or Event generation is not funded or licensed for this client.
generation_unavailableGeneration readiness is not verified. Nothing was accepted.

Event regeneration stays in the portal. Forms (where the app supports them) share the request's 45-second budget; declining saves nothing and a form never generates.