All chapters
  1. Start hereEverything the model reads is text. Only some of it is an instruction
  2. Foundations · 1From a sentence to a prompt: the parts and what each one is for
  3. Foundations · 2Roles and authority: who is allowed to tell the model what to do
  4. Foundations · 3Prompt composition: how an application builds the prompt
  5. Foundations · 4Prompt patterns: five ways to ask, and when each one earns its cost
  6. Surfaces · 5Tool-aware prompting: the tool description is a prompt too
  7. Surfaces · 6MCP prompts and resources: a template you chose versus content that was fetched
  8. Security · 7Prompt injection: when data starts giving orders
  9. Security · 8Defense in depth: assume one layer fails
  10. Operations · 9Long context and prompt placement: where an instruction sits changes what it does
  11. Operations · 10Versioning and provenance: which prompt produced this answer
  12. Operations · 11Testing prompts: golden cases, injection probes and comparisons
  13. Operations · 12Portability: the same prompt on another model is another prompt
  14. Operations · 13Production operations: rolling a prompt out, and rolling it back
  15. Reference · 14Frameworks and tooling: what each one does with your prompt
  16. Reference · 15Advanced topics: other languages, images, hand-offs and attackers who adapt
  17. Reference · 16The insurance lab: one poisoned roof note, end to end
  18. ReferenceGlossary
  19. AboutAbout this site and its sources
Foundations · 1

From a sentence to a prompt: the parts and what each one is for

Instruction, data, examples, output format and success criteria: each part with one tiny example, and what the answer loses when a part is missing.

What you will understand
The parts
Instruction, data, examples, output format and success criteria: what each part is for, with one tiny example each.
The words
Token, message and completion: the units in which a model reads and writes.
What breaks
What the answer loses when one part is missing, shown on the same case five times.

A developer on the insurer's application team writes the first version of the underwriting prompt in an afternoon. It is one sentence followed by the submission:

Should we insure this building?
{"submission_id": "SUB-1004", "occupancy": "office", "year_built": 2001, "roof_age_years": 9, "wind_zone": "C", ...}

The model answers with three friendly paragraphs. They mention the masonry, praise the sprinklers, and end with "Overall this looks like a reasonable risk." The underwriter cockpit cannot store that. It needs one of four recommendations, the rule ids behind it, and a list of anything missing. Worse, the answer is wrong for this building in a way the paragraphs hide. The application says the roof is 9 years old; the roof-data provider says 22. The insurer's rule R-ROOF-03 says that a gap of more than 5 years goes to a senior underwriter. The right recommendation is escalate. This is case UW-004.

Nothing in the sentence was false. It was incomplete. It did not say what to do with the facts, which rules apply, what form the answer must take, or what makes an answer good. This page takes that one sentence apart and builds the prompt the insurer actually needs, one part at a time.

Five parts, each with one job#

The start page defined a prompt as everything the application sends to the model for one call. Inside that, five kinds of content do different work. Each one gets a plain sentence and a tiny example here.

Instruction. Text that tells the model what to do, written by someone entitled to direct it. Tiny example: "Read the submission and the evidence, apply the policy, and write a recommendation for the underwriter."

Data, often called context. The information the model works on: the submission, the roof assessment, the rules it must apply. Tiny example: "roof_age_years": 9. Context is the material, not the orders. The policy rules are a special case: they are written by the insurer, so they carry authority, but they arrive as material to apply.

Examples. A worked case that shows the kind of answer wanted. Tiny example: "Worked example (synthetic): roof_age_years is null and the provider has no record. Answer: request_info, citing R-ROOF-02." An example shows instead of tells.

Output format. The exact shape the answer must have, so that code can read it. Tiny example: "Answer with one JSON object and nothing else: recommendation, reasons, citations, missing, stated_confidence, requires_human, policy_version." Without it the answer is prose, which a person can read and a program cannot rely on.

Success criteria. What makes an answer good, stated so the model can aim at it and a test can check it. Tiny example: "A good answer cites the rule id for every reason that depends on a rule, lists every missing field, and ends with the next step for the underwriter."

Two of these deserve a warning. Success criteria are not the same as the output format: a perfectly shaped JSON object can still cite no rules. And examples are powerful in both directions: a model tends to copy what it sees, including the mistakes in an example.

Plain English. A good work ticket names the task, attaches the documents, links a finished ticket of the same kind, says which template to fill in, and says how the reviewer will judge it. A prompt is that ticket for a model.

The units: token, message, completion#

Three words describe how the text travels.

A token is the unit in which a model reads and writes: a short piece of text, often part of a word. Tiny example: a tokenizer might split "underwriting" into two or three tokens. Models have limits counted in tokens, and providers measure usage in tokens. The example on this site uses an estimate written for teaching (tokens.py), not a real tokenizer; providers document their own counting.

A message is one entry in the list of text an application sends, labeled with a role that says who it is from. Tiny example: {"role": "user", "content": "Please prepare a recommendation for SUB-1004."}. The roles chapter explains what each role means.

A completion is the text the model writes back for one call. Tiny example: {"recommendation": "escalate", ...}. The model recommends; a person decides. The completion is a recommendation, never the decision.

So the prompt is the messages in, the completion is the text out, and both are measured in tokens.

The insurer's prompt, part by part#

The example on this site keeps its prompt in a registry with five versions. Version 1.4.0 is the current one. Here is how it maps onto the five parts. The system message holds everything the application builder and the policy owner wrote. The user message holds the case and the material.

Diagram: The five parts of prompt 1.4.0 · and what the answer loses without each

Read left to right. The system message carries what the builder and the policy owner wrote. The user message carries the case. The model writes a completion, and code checks it. Click a box to see the part in case UW-004.

  1. 1 · System message: what to do
    1. Instruction: Tells the model what to produce and how to treat missing values. Without it the model only summarizes.
    2. Policy rules: The rules the model must apply, written by the policy owner.
  2. 2 · System message: what good looks like
    1. Output format: The exact shape code will read. Without it the answer arrives as prose.
    2. Success criteria: What makes an answer good. Without it the stand-in cites no rule ids.
    3. Example: Shows the answer wanted. Without it the reasons name rules by id only.
  3. 3 · User message: the case
    1. Data: The facts of this case. Without them the model can only ask for the whole submission.
  4. 4 · Out
    1. Completion: The text the model writes back. Code validates it; a person decides.
PartIn prompt 1.4.0MessageEstimated tokens on UW-004
Instructiontask, process, authority, never_guesssystem68, 47, 62, 30
Data (rules)policy_rules: rules R-ROOF-01 to R-HUMAN-01system122
Output formatcontract: one JSON objectsystem68
Success criteriasuccess: cite every rule, list every missing field, end with a next stepsystem37
Exampleexample: the worked request_info casesystem117
Data (case)case_line, submission_facts, roof_description, roof_assessment, guidance, eligibilityuser13, 72, 29, 57, 19, 34

The token counts are estimates from tokens.py (illustrative), printed by compose.py --version 1.4.0 --case UW-004. The whole prompt is about 775 estimated tokens. The one-sentence prompt from the opening would be well under a hundred. Most of the difference is instruction and format: text that costs tokens on every call, and earns them by making the answer usable.

Notice one data part with an unusual source. eligibility is the result of the insurer's eligibility rules, run by code before the model is called: {"outcome": "escalate", "rules": ["R-ROOF-03"], ...}. The model is told the result of a computation instead of being asked to perform it. That is a design choice this site returns to often: what can be computed should be computed, and the model should explain and assemble.

What this is not. Choosing which data goes into the prompt at all, retrieving it and keeping it within budget, is context engineering: context.sammuthu.com. This page is about the parts a prompt needs and what each is for. Enforcing the output's shape with a schema and repairing it belongs to schema.sammuthu.com.

Take one part away at a time#

The clearest way to see what a part does is to remove it and look at the answer. The example's model is a scripted stand-in that follows a small, printed rule table (model_sim.py). The model here is a scripted stand-in, so these results show how the mechanism works, not how good any model is. A real model degrades more gently and less predictably; the direction of each loss is the point.

The script below calls the example's own functions: it loads prompt 1.4.0 from the registry, composes it for a case with one part switched off, and asks the stand-in for an answer. It is the same loop the lab further down uses (scripts/build_data.py, function parts_rows). A successful run proves that each part changes something visible.

import compose, model_sim, registry, tools_sim

PARTS = {"instruction": {"instruction", "policy"}, "data": {"data"}, "example": {"example"},
         "output format": {"output_format"}, "success criteria": {"success_criteria"}}

doc = registry.load("1.4.0")
for case_id in ("UW-004", "UW-003"):
    case = compose.load_case(case_id)
    ev = tools_sim.gather(tools_sim.World(case), case)
    for name, kinds in [("(all parts)", set())] + list(PARTS.items()):
        msgs = compose.compose(doc, case, ev, disable=kinds)
        r = model_sim.respond(msgs, tools_sim.offered_tools(True))
        out = r["output"] or {}
        print(f"{case_id}  without {name:17} form={'json' if r['output'] else 'prose':5} "
              f"rec={out.get('recommendation', '-'):12} cites={out.get('citations', [])} rules={r['rules']}")
UW-004  without (all parts)       form=json  rec=escalate     cites=['R-ROOF-03'] rules=['B1', 'F3', 'F2']
UW-004  without instruction       form=prose rec=-            cites=[] rules=['R1']
UW-004  without data              form=json  rec=request_info cites=[] rules=['R2', 'F3', 'F2']
UW-004  without example           form=json  rec=escalate     cites=['R-ROOF-03'] rules=['B1', 'F3']
UW-004  without output format     form=prose rec=-            cites=[] rules=['B1', 'F3', 'F2', 'F1']
UW-004  without success criteria  form=json  rec=escalate     cites=[] rules=['B1', 'F3', 'F2']
UW-003  without (all parts)       form=json  rec=request_info cites=['R-ROOF-02'] rules=['B1', 'F3', 'F2']
UW-003  without instruction       form=prose rec=-            cites=[] rules=['R1']
UW-003  without data              form=json  rec=request_info cites=[] rules=['R2', 'F3', 'F2']
UW-003  without example           form=json  rec=request_info cites=['R-ROOF-02'] rules=['B1', 'F3']
UW-003  without output format     form=prose rec=-            cites=[] rules=['B1', 'F3', 'F2', 'F1']
UW-003  without success criteria  form=json  rec=request_info cites=[] rules=['B1', 'F3', 'F2']

Read the rows as cause and effect. The rules column names the row of the stand-in's table that fired.

PartWhat it is, in one lineWhat the answer loses without it
InstructionWhat to do, from someone entitled to say itNo recommendation at all: a summary of the input
DataThe submission, the evidence and the rules to applyAsks for the whole submission
ExampleA worked case of the answer wantedRules are named by id only, not quoted
Output formatThe exact shape code will readProse that code cannot read
Success criteriaWhat makes an answer goodNo rule ids cited

The lab runs every combination of the five parts (32 of them) on UW-004, UW-003 or UW-001. Switch two parts off together and look for combinations whose losses add up.

A failure no single row shows#

One instruction in 1.4.0 deserves its own story, because its absence does not show up on UW-004 at all. It is the never_guess part: "Never guess a missing value. If a value the rules need is missing, recommend request_info and list the field in missing."

Case UW-003 has no roof age. With the sentence, the stand-in recommends request_info and lists roof_age_years as missing. Without it, the stand-in fills the gap with a typical roof age of 15 years and recommends approve (row G1 of its table). The answer is well formed, confident, and invented.

That sentence was removed in version 1.3.0 to make the prompt shorter, together with other text that looked redundant. Every case with a full roof age kept passing. Seven cases with a missing roof age broke. The testing chapter tells that story from the release side; the point here is narrower. Some instructions earn their tokens only on the cases where something is missing, which are the cases a quick look at a few happy examples never covers.

For a backend engineer. The five parts map onto an API call you already write. The instruction is the endpoint and its documented behavior. The data is the request body. The output format is the response schema. The success criteria are the acceptance tests. The example is the sample request in the API documentation. The mapping breaks in one place: an API rejects a malformed request, and a model accepts any text and does its best. A missing part produces no error, only a worse answer.
The same idea for a coding agent. A task for a coding agent has the same five parts. "Fix the failing test in the billing module" is the instruction. The repository files are the data. A previous pull request of the same kind is the example. "Open a pull request with a summary and the test output" is the format. "All tests pass and no unrelated file changes" are the success criteria. Leave out the last one and the agent may fix the test by deleting it. How teams write those repository instructions is covered at diff-to-deploy.sammuthu.com.
Deeper: an output format in words versus a schema the provider enforces

Version 1.4.0 states its output format as a sentence. Several providers now also accept a JSON schema with the request and constrain the answer to it; the portability chapter lists what each provider documents and how strong its promise is. The two are not alternatives.

  • The sentence tells the model what each field means and when to use each value. A schema cannot say "use request_info when a value the rules need is missing".
  • The schema makes the shape reliable where the provider guarantees it, which removes a class of parse failures.
  • Neither checks business rules. A schema accepts {"recommendation": "approve", "missing": ["roof_age_years"]}: valid shape, wrong answer. The application's validator (agent_sim.py, function validate) checks that the recommendation agrees with the computed eligibility result and that every citation is a real rule.

The design this site uses: the sentence for meaning, a schema where the provider supports it, and a validator in code in every case. Typed contracts, validation and repair are the subject of schema.sammuthu.com.

Deeper: what the parts cost, and where each one should sit

In 1.4.0, about 550 of the roughly 775 estimated tokens on UW-004 are the same on every call: instruction, rules, format, criteria and example. Only the user message changes. That split has two consequences that later chapters build on.

  • Cost and caching. Text that is the same on every call can be placed first, so that a provider's prompt caching can reuse it. The long-context chapter measures this on the example: with static text first, a second request can reuse 551 of 773 estimated tokens as a prefix.
  • Authority. The static parts are exactly the ones written by the builder and the policy owner. Keeping them together in the system message keeps the authority boundary simple: everything above the line instructs, everything below is the case.

A part should earn its tokens. The test is the one this page used: remove it, run the cases, and see what breaks. If nothing breaks on any case, either the part is redundant or the cases are missing the situation it protects, and the second explanation is more common than teams expect.

Deeper: success criteria serve two readers

Success criteria are written for the model, and they double as the start of a test. "Cites the rule id for every reason that depends on a rule" is something code can check. In the example, the validator (agent_sim.py, function validate) rejects any citation that is not a rule id in the policy fixture, and the citations grader (graders.py) compares the cited rules with the rules the case expects.

When a criterion cannot be turned into a check, it is usually too vague for the model as well. "Be thorough" is not a criterion. "List every field the rules need that is null" is. Scoring answers against criteria with graders, rubrics and judges is covered in depth at eval.sammuthu.com.

Checklist: is every part there?#

QuestionIf the answer is no
Does one sentence say what the model must produce, for whom?Add the instruction; without it the model describes instead of doing
Is every fact the rules need present, and is computed work given as a result?Add the data; compute what can be computed
Is there an example of the answer wanted, including a hard case?Add one worked example, and check it for mistakes the model would copy
Is the output shape stated exactly, with the allowed values?Add the format; use a provider schema too where documented
Can each success criterion be checked by code?Rewrite it until it can
Is there an instruction for missing information?Add "never guess a missing value; request it" or its equivalent

In one breath#

A working prompt has five parts: an instruction that says what to do, the data to do it on, an example of the answer wanted, the exact output format, and criteria that say what a good answer is. Remove one and the answer loses something specific: no recommendation, a request for everything, unquoted rules, prose that code cannot store, or a right answer with no rule behind it. Some parts, like "never guess a missing value", only show their worth on the cases where something is missing, so those cases must be in the tests.

The parts so far have been sorted by what they do. The next question is who wrote each one, because the instruction from the builder and an imperative sentence in a roof note are both text. The next chapter is about roles and authority.