> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getthread.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Prompt engineering tips and tricks

> Advanced Magic AI prompt techniques: clarity, examples, XML tags, chain of thought, and iteration, drawn from Anthropic's Claude prompt engineering.

<Info>
  Magic AI, Magic Agents, and Super Magic run on **Claude models hosted on AWS Bedrock**. The techniques on this page come from Anthropic's own prompt engineering guidance and apply directly to any prompt you write inside Thread — Triage Agent intents, recap templates, categorization rules, priority rules, Magic Title rules, and Super Magic responses.

  For the fundamentals, see [Best practices for writing Magic AI prompts](/assistive-ai/prompt-best-practices). This page is the companion for when the fundamentals aren't producing the quality you need.
</Info>

## Golden rule: write for a brand-new hire

Anthropic's guidance for writing to Claude is to picture a brilliant new employee who has no context on your MSP, no clue what your PSA looks like, and no sense of what "urgent" means in your world. Every detail you'd tell that person on day one belongs in the prompt — the company terminology, what counts as an outage, which team owns what, and what "good" looks like for the output.

If you handed your prompt to a coworker who had never seen the ticket, would they know what to do? If not, Magic AI won't either.

## 1. Be explicit — tell it what to do, not what not to do

Vague instructions produce generic output. Explicit instructions produce the output you actually want.

**Less effective**

```
Don't be too formal.
```

**More effective**

```
Write in a warm, conversational tone. Use contractions ("we'll", "it's"). Keep sentences short.
Address the end user by first name if it appears in the ticket.
```

Two patterns to lean on:

* **Lead with the action verb.** "Summarize", "Classify", "Escalate", "Rewrite" — put it at the front so the intent is unmistakable.
* **Tell Magic AI what "good" looks like.** Length, tone, structure, what to include, what to omit. Don't rely on the model to guess.

## 2. Add context and motivation

Explaining *why* a rule exists lets Magic AI generalize to cases you didn't spell out. A rule with reasoning attached holds up better than a bare instruction.

**Less effective**

```
Always set priority to High for tickets from Contoso.
```

**More effective**

```
Contoso is a Priority 1 client on a 15-minute response SLA — every ticket from them is High priority
by default. If the ticket is also flagged as an outage or affects more than one user, escalate to Urgent.
```

The second prompt tells Magic AI both the rule and the reason, so it makes sensible calls on edge cases (a single-user, non-urgent Contoso request stays High; a Contoso outage jumps to Urgent).

## 3. Use examples — show, don't just tell

Examples are one of the most reliable ways to steer Magic AI's output format, tone, and structure. This is sometimes called **few-shot prompting**, and it's especially useful for recap templates, categorization, and title rules where the desired output has a specific shape.

Good examples are:

* **Relevant** — they mirror the real tickets you see.
* **Diverse** — they cover the common edge cases, not just the happy path.
* **Structured** — wrap each example in tags so Magic AI can tell examples apart from instructions.

Example for a categorization rule:

```
Classify each ticket into Type, Sub-Type, and Item.

<example>
Ticket: "My Outlook keeps crashing when I open attachments."
Type: Incident
Sub-Type: Email
Item: Outlook client
</example>

<example>
Ticket: "Can you add Jane Doe to the Finance shared mailbox?"
Type: Service Request
Sub-Type: Access
Item: Shared mailbox
</example>

<example>
Ticket: "Nobody in the Denver office can print."
Type: Incident
Sub-Type: Printing
Item: Site-wide printer outage
</example>
```

Three to five examples is usually the sweet spot. If your output is still inconsistent after that, the problem is usually the instruction, not the number of examples.

<Tip>
  Magic AI pays close attention to details in your examples. If an example has a subtle pattern you didn't mean to establish — an emoji, a specific phrasing, an inconsistent capitalization — it will pick that up. Review examples like they're going into production, because effectively they are.
</Tip>

## 4. Structure complex prompts with XML tags

Once a prompt mixes multiple types of content — instructions, background context, examples, ticket data — plain paragraphs get ambiguous. Wrap each type in a descriptive XML tag so Magic AI can parse the boundaries.

```
<role>
You are a triage assistant for an MSP that supports small law firms.
</role>

<instructions>
Read the incoming ticket, decide whether it needs same-day response, and draft a first reply.
</instructions>

<company_context>
- Business hours: 8am–6pm Central, Monday–Friday
- After-hours phone: 1-800-555-0199
- We support Windows-only environments
</company_context>

<ticket>
{{ticket_body}}
</ticket>
```

Rules of thumb:

* Use consistent, descriptive tag names across your prompts.
* Nest tags when content has natural hierarchy (`<examples>` wrapping multiple `<example>` blocks).
* Tag names should describe the content, not the format (`<company_context>`, not `<section_2>`).

## 5. Give step-by-step instructions when order matters

For decisions where the order of checks changes the outcome — triage flows, escalation logic, categorization with fallbacks — write the steps as a numbered list. Magic AI follows structured procedures better than it infers them from prose.

```
When a new ticket arrives, work through these steps in order:

1. Check the sender domain. If it matches a known VIP client (Contoso, Fabrikam, Northwind), tag it VIP.
2. Check the subject and body for outage language ("down", "can't access", "nobody can", "everyone's").
   - If found and it's a VIP client, escalate to Urgent and page the on-call tech.
   - If found and it's a non-VIP client, escalate to High.
3. If neither of the above applies, fall back to the standard priority matrix.
4. Draft an acknowledgment reply using the "First response — general" template.
```

## 6. Ask Magic AI to think before it answers

For decisions that need reasoning — a nuanced priority call, a categorization with overlapping options, a sentiment read — telling Magic AI to reason step by step before committing to an answer measurably improves quality. Anthropic calls this **chain-of-thought prompting**.

Two ways to structure it:

**Basic — just ask for reasoning:**

```
Before choosing a priority, think step by step about the impact, the number of users affected, and the SLA
tier of the client. Then choose the priority.
```

**Structured — separate the reasoning from the final answer:**

```
Work through your reasoning inside <thinking> tags, then give your final answer inside <answer> tags.

<thinking>
- How many users are affected?
- Is the client on a premium SLA?
- Is this blocking billable work?
</thinking>

<answer>
Priority: [Low | Medium | High | Urgent]
Reason: [one sentence]
</answer>
```

The structured version is especially useful when you want to log the reasoning for audit or coaching.

## 7. Give it permission to say "I don't know"

Magic AI will try to be helpful even when the ticket doesn't contain enough information — and that's when hallucinations creep in (a made-up asset name, an invented user, an assumed office location). Give it an explicit exit:

```
If the ticket doesn't contain enough information to categorize it confidently, set the category to
"Needs human review" and leave a one-line note explaining what's missing. Do not guess.
```

This one addition dramatically reduces confident-but-wrong output.

## 8. Match the style of your prompt to the style you want back

Magic AI's output tends to mirror the style of the prompt. If you write your prompt in dense paragraphs, expect dense paragraphs back. If you want short, scannable bullets, write the prompt in short, scannable bullets.

Practical consequences:

* **Recap prompts that use markdown produce markdown recaps.** If you want a recap in plain sentences, remove the markdown scaffolding from the prompt.
* **Title prompts that use ALL CAPS in examples produce ALL-CAPS titles.** Match your examples to the casing you actually want.
* **Casual prompts produce casual replies; formal prompts produce formal replies.** Set the register in the instructions, and reinforce it in your examples.

## 9. Iterate — the first prompt is never the best one

The best prompts are refined over 5–10 revisions, not written in one shot. A simple loop:

<Steps>
  <Step title="Write the shortest version that could work">
    Start with a plain-language instruction and one example. Don't over-engineer up front — you don't yet know where it breaks.
  </Step>

  <Step title="Test on real tickets from your PSA">
    Not made-up examples. Run it against 10–20 recent tickets that cover the range of scenarios you actually see.
  </Step>

  <Step title="Find the failures, not the successes">
    Where did Magic AI produce the wrong category, the wrong priority, the wrong tone? Those failures tell you what the prompt is missing.
  </Step>

  <Step title="Target the failure — not general 'be better' language">
    Vague fixes ("be more careful") don't work. Concrete fixes ("if the ticket mentions Outlook AND crashing, the sub-type is Email, not Applications") do.
  </Step>

  <Step title="Retest and repeat">
    Keep going until you can't find a failure mode on real tickets. Then run it for a week and check again — new tickets will surface new gaps.
  </Step>
</Steps>

## 10. Use another AI to help you write prompts

Anthropic explicitly recommends using an assistant (Claude, ChatGPT, or Magic AI itself) as a prompt-writing partner. You describe the goal in plain language and ask it to draft a prompt, generate additional examples, or point out ambiguity in your draft.

A good starting query:

```
I'm writing a categorization prompt for a helpdesk ticketing system. Categories are Type, Sub-Type, and Item.
The tickets are from small-business end users, mostly Windows and Microsoft 365 issues.

Please draft a categorization prompt that:
- Handles ambiguous requests where the user describes symptoms, not causes
- Falls back to "Needs human review" when there isn't enough information
- Includes 3 diverse worked examples

Ask me clarifying questions before drafting if any part of the goal is unclear.
```

Treat the draft as a starting point — always test it against real tickets before rolling it out.

## Common mistakes to avoid

<AccordionGroup>
  <Accordion title="Over-engineering the prompt">
    Longer isn't better. Every extra sentence is another chance to introduce a contradiction or an edge case the model over-indexes on. Start short, add only what a real failure justifies.
  </Accordion>

  <Accordion title="Telling Magic AI what NOT to do, over and over">
    A prompt full of "never" and "do not" gives Magic AI a list of banned behaviors but no picture of the correct behavior. Rephrase as positive instructions: "Use first names" instead of "Never use titles like Mr. or Ms.".
  </Accordion>

  <Accordion title="Contradicting your own examples">
    If the instruction says "use short sentences" but your example uses 40-word sentences, Magic AI will follow the example. Examples always beat instructions when they disagree — so review them together.
  </Accordion>

  <Accordion title="Assuming the model will 'just figure out' the context">
    It won't. Explicitly state who the audience is, what tools you use, what "urgent" means in your world, and what output format you need. Ambiguity in the prompt shows up as inconsistency in the output.
  </Accordion>

  <Accordion title="Referencing variable names in the prompt text">
    Write in natural language, not `{{variable_name}}`. Variables are substituted with their real values before Magic AI ever sees the prompt — for the full explanation, see [Using variables in Magic AI and Magic Agents](/assistive-ai/variables).
  </Accordion>

  <Accordion title="Never testing on real tickets">
    A prompt that works on invented examples often falls apart on the messy, half-punctuated, forwarded-three-times tickets you actually get. Always validate on real data before rolling out.
  </Accordion>
</AccordionGroup>

## Where to go next

* [Best practices for writing Magic AI prompts](/assistive-ai/prompt-best-practices) — the fundamentals, with worked examples for prioritization, categorization, recaps, and triage.
* [Using variables in Magic AI and Magic Agents](/assistive-ai/variables) — how runtime substitution works and why you write prompts in natural language, not with variable names.
* [Magic Title rule creation guide](/assistive-ai/magic-title-rule-creation-guide) — applying these techniques to ticket title generation.
* [Getting started with Triage Agent](/ai-agents/getting-started-with-triage-agent) — applying these techniques to conversational triage.

For deeper reading on the model itself, Anthropic's [prompt engineering overview](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview) and [prompting best practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices) are the authoritative source. Not every technique there applies to writing prompts inside Thread — some are aimed at developers building directly on the Claude API — but the fundamentals on this page carry over cleanly.


## Related topics

- [Configure Magic Title in Thread](/assistive-ai/setting-up-magic-title.md)
- [Engineering Escalation to Linear](/skill-library/escalation/engineering-escalation-linear.md)
- [Supporting Architecture and Engineering Firms](/skill-library/industry-packs/architecture-engineering.md)