Skip to main content

Best Practice: Writing Brief Prompts

How to write a custom brief prompt in Hook that produces a consistent, useful, saved output - with a pre-publish checklist and worked example.

👤 Managers and Technical Admins can create custom briefs, under Organisation Settings → UI Configuration → The Brief.

How to write a custom brief in Hook that produces a consistent, useful, saved output.

A brief has four parts: name, description, prompt, and tools. This article covers how to write the prompt (and pick the tools) so the brief works every time.

Related articles

The mental model

A brief is generated on request, on a single account page, when someone opens it from the Brief tab. It is not a chat. The brief has one job: gather data with the tools you enabled, then call the Save Brief tool to persist a document that renders in the tab. The reader is waiting on that document and has no way to reply mid-run.

Almost every failure mode below comes from writing a prompt that reads like a conversation rather than a document spec.

1. Write an output spec, never a request

This is the big one. Phrasing the prompt as a request to the user diverts the brief from saving its output. If the prompt says "tell me", "walk me through", "let me know", "show me", or "what would you like", the brief treats its answer as a reply addressed to a person, returns it as conversational text, and never calls the save tool. The brief then renders empty or fails.

Write in the imperative, describing an artefact.

Avoid

Use

Tell me who the key stakeholders are

Section "Key Stakeholders": list primary contacts and their roles

Walk me through the risk on this account

Section "Risk Status": rate the account Low / Medium / High and state the primary risk factor in one sentence

Let me know if anything looks off

Section "Watch Items": list up to three anomalies, or state "None identified"

Ask me which product line to focus on

Cover every product the account holds

Same rule for clarifying questions. The run is one-shot: the reader is looking at a loading Brief tab, not a chat box, and cannot answer. A question is a dead end. Never leave a decision to the brief that it might resolve by asking - decide it in the prompt.

2. Enable the minimum toolset, and every tool the prompt implies

Two failure directions:

  • Too few. The prompt asks for something no enabled tool can supply. The brief fills the gap with inference or leaves the section blank. If a section mentions support tickets, Get Recent Customer Support Tickets must be on.

  • Too many. Every enabled tool is a call the brief may make, and someone is watching the tab while it makes them. Twenty tools on a five-section brief is slow, expensive, and noisy.

Draft the sections first, then list the tools each one needs. That list is your config.

Do not reference data that Hook does not hold. A prompt saying "pull the opportunity stage from Salesforce" has no matching tool and will produce invented content.

3. Always enable the date tools when the prompt mentions time

Anything containing "recent", "last 90 days", "this quarter", "since the last QBR" needs:

  • Get Current Date (always use it for any reference to now or today)

  • Get Time Period to resolve phrases like "last two months" into dates

  • Get Organization Current Fiscal Calendar if you use quarters or fiscal years

Without these the brief guesses the date and silently applies the wrong window.

4. Fix the structure, cap the length

Numbered sections with explicit names, an explicit output format, and a length cap. Briefs are read in the three minutes before a call, so they must be scannable and predictable across accounts.

Output format: bullet points throughout. Half a page maximum.
Lead each section with the most critical insight. No preamble, no
closing summary.

Naming the sections also means the brief cannot reorganise itself per account, which is what makes briefs comparable side by side.

5. Tell it what to do with missing data

Sparse accounts are the common case, and a brief with nothing to say will pad. Be explicit:

If a source returns no data, state "No data" for that section.
Do not infer, and do not substitute data from another section.

Watch out for a specific trap: an empty meeting summary or next-steps field usually means nobody populated it, not that the meeting had no outcome. If that distinction matters, instruct the brief to say "not recorded" rather than "no next steps agreed".

6. Name it for the moment of use

The name is what a CSM scans in the Brief tab. Name it for the situation, not the data: "QBR Prep", "Champion Assessor", "Exec Escalation", not "Meeting and Email Analysis". The description should say when to open it.

7. Test on three accounts before publishing

Publishing rolls the brief out to every account, so test the spread:

  1. A data-rich enterprise account (does it stay within the length cap?)

  2. A thin or newly onboarded account (does it handle empty sources, or does it pad?)

  3. An edge case: churn risk, multi-product, or part of a parent group (does it hold structure?)

If the brief is empty on all three, check rule 1 first. That is nearly always the cause.

Pre-publish checklist

  • ☐ No "tell me", "show me", "let me know", "ask me" anywhere in the prompt

  • ☐ Every section maps to at least one enabled tool

  • ☐ No enabled tool is unused by any section

  • ☐ Date tools enabled if the prompt mentions any time period

  • ☐ Sections explicitly named and numbered

  • ☐ Output format and length cap stated

  • ☐ Missing-data behaviour stated

  • ☐ Tested on rich, thin, and edge accounts

Worked example

Name: Exec Escalation Brief

Description: Open before joining a customer call at short notice as an exec.

Prompt:

Produce an executive briefing for this account. Use the sections below,
in this order.1. Key Stakeholders
   List primary contacts and their roles (Economic Buyer, Champion,
   Technical Lead). Flag anyone who has gone silent, changed role, or
   recently joined.2. Current Relationship
   Summarise relationship health in one or two sentences. Include
   engagement level, last meaningful interaction, and sentiment.3. Risk Status
   Rate the account Low / Medium / High. State the primary risk factor
   in one sentence. Include mitigating actions already in motion.4. Next Actions
   The one to three actions needed to secure the renewal.Output format: bullet points throughout, half a page maximum. Lead each
section with the most critical insight. If a source returns no data,
state "No data" for that section rather than inferring.

Tools: Get Current Date, Get Time Period, Get Customer From Id, Get Customer Contacts, Get Recent Customer Meetings, Get Recent Customer Emails, Get Detected Signals, Get Customer Renewal Likelihoods, Get Customer Metric Values, Get Recent Customer Support Tickets

Ten tools, four sections, every tool earning its place.

Did this answer your question?