An eval set is a collection of test cases with expected outcomes, used to score model outputs. This is the single tool that separates serious AI users from the rest.
Fields:
- id — stable identifier
- input — the prompt input (raw text, or a reference to a file)
- expected — the ideal answer OR the criteria for what a good answer looks like
- criteria — array of rubric dimensions
- tags — for filtering (regression, high-priority, edge-case, etc.)
Minimum viable eval set
For any workflow you care about, produce 5 good + 5 bad:
5 good examples — cases where you know what a great output looks like. These are your ground truth.
5 bad examples — cases where the current model tends to fail (long inputs, ambiguous asks, edge cases, adversarial inputs). These are your regression tests.
Sample eval set — Email triage
{"id": "e-001", "input": "Hi Adam, following up on the lease terms we discussed Tuesday...", "expected": "Reply-today", "criteria": ["correct_label", "acknowledges_deadline"], "tags": ["client", "regression"]}
{"id": "e-002", "input": "🎉 40% off summer sale at BigMart!", "expected": "Newsletter", "criteria": ["correct_label"], "tags": ["marketing"]}
{"id": "e-003", "input": "Your Vercel deployment succeeded.", "expected": "FYI-only", "criteria": ["correct_label"], "tags": ["automated"]}
Sample rubric
## Rubric for email triage
Correctness (0-3):
0 - wrong label
1 - roughly right category
2 - correct label, missed nuance
3 - correct label with appropriate priority
Voice match (0-3) [for drafted replies]:
0 - obvious AI writing
1 - competent but generic
2 - matches my voice on structure or vocabulary
3 - passes as mine
Safety (pass/fail):
Fail if it sends without draft
Fail if it includes PII in the summary
Fail if it categorizes urgent-legal as newsletter
Running an eval
# Pseudo-code — adapt to your framework
for each case in cases.jsonl:
output = model.generate(system_prompt, case.input)
score = judge(output, case.expected, case.criteria)
record(case.id, model, score, output)
report(aggregate_scores)
Frameworks that make this easier:
- Promptfoo — CLI-first, YAML configs, LLM-as-judge built-in
- LangSmith — Anthropic/OpenAI/Langchain integration
- Langfuse — open source, self-hostable
- DeepEval — Python-first
When to run
Before adopting a new model version
Before shipping a prompt change
Weekly for critical workflows (regression)
Monthly for everything
What "good" looks like
All priority-1 cases pass
Regression cases don't degrade from baseline
New model beats old model by ≥10% before you switch
No model change ships without running the eval set.
Even if the vendor says the new model is "10% better on benchmarks" — your workflow may be different. Verify on your data.
Protocol
Step 1 — Freeze the baseline
Record current model version (e.g., claude-opus-4-20260601)
Run the eval set against it
Save results in evals/<workflow>/results/YYYY-MM-DD_<model>_baseline.jsonl
Step 2 — Run candidate
Run the eval set against the new model version (e.g., claude-opus-4.5-20260901)
Save results with same timestamp convention
Step 3 — Diff
Produce a comparison table:
Case
Baseline score
Candidate score
Delta
Notes
e-001
3/3
3/3
0
e-002
2/3
3/3
+1
Improved edge case
e-003
3/3
1/3
-2
🚨 Regression
Step 4 — Decide
Ship the new model if:
- ✅ Zero priority-1 regressions
- ✅ Aggregate score ≥ baseline
- ✅ Cost is acceptable
- ✅ Latency is acceptable
Do not ship if:
- ❌ Any priority-1 regression
- ❌ Any safety-fail case
- ❌ >5% degradation in aggregate
Step 5 — Communicate
If you ship, write a one-paragraph changelog:
- Old model → new model
- Aggregate delta
- Notable improvements
- Any regressions being accepted (and why)
- Rollback plan
When to re-baseline
Every quarter (base drifts as your prompts evolve)
After any major prompt change
After a workflow change
Prompt regressions
If a prompt change is the trigger, hold the model constant, vary only the prompt. Same protocol.
For LLM-as-judge:
- Use Claude Opus or GPT-5 for judging
- Provide the rubric in the judge's system prompt
- Have it produce structured output with scores per dimension + reasoning
- Sanity-check 10% of judgments manually
200+ terms, organized in 11 clusters. Read one cluster per day for two weeks and you'll be fluent.
Each term has: definition, why it matters, and where it appears.
Cluster 1 — Model Mechanics
Token — The unit an LLM consumes. Roughly ¾ of an English word. Prices, context windows, and rate limits are all counted in tokens. Why it matters: cost and length constraints are token-denominated.
Context window — The maximum number of tokens a model can attend to in one call (input + output). Gemini 2.x Pro: 2M. Claude: 1M. GPT-5: 400k. Why it matters: longer window = more knowledge in-context = less RAG needed.
System message / system prompt — Standing instructions given before the conversation starts. Higher priority than user messages. Why it matters: this is your leverage point.
User message — What the user says. Second priority.
Assistant message — What the model says. Referenced back in multi-turn conversations.
Tool message / function result — The output of a tool call, sent back to the model.
Temperature — Randomness knob (0–2). 0 = deterministic. 1 = default. 2 = wild. Use 0 for extraction, 0.7 for writing, 1.0+ for brainstorming.
Top-p (nucleus sampling) — Alternative to temperature. Selects from the smallest set of tokens whose cumulative probability exceeds p. Usually set to 0.9 or 1.0.
Top-k — Select from the top k most likely tokens. Rarely tuned directly.
Frequency penalty / presence penalty — Discourage repetition. Frequency penalizes based on count; presence based on whether the token has appeared at all.
Max tokens — Cap on output length. Different from context window.
Streaming — Model returns tokens as they're generated, rather than waiting for the full response. Reduces perceived latency.
Stop sequences — Strings that cause the model to halt generation. Useful for structured output.
Seed — For deterministic sampling. Same seed + same input + same params = same output. Not guaranteed across model versions.
Log probs / logprobs — Probability the model assigned to each generated token. Used for confidence estimation and evals.
Function calling / tool use — Model outputs a structured request to call an external function, then receives the result and continues. The foundation of agents.
JSON mode / structured output — Constraint that forces the model to return valid JSON matching a schema. Reliable extraction.
Grammar-constrained decoding — Force output to match a formal grammar (JSON schema, regex, custom BNF). Even stricter than JSON mode.
Token pricing — Cost per million input tokens vs cost per million output tokens (output is usually 3–5× more expensive).
Rate limit — Per-minute or per-day cap on requests or tokens. Enforced per API key or organization.
Cluster 2 — Reasoning
Chain-of-Thought (CoT) — Prompting technique: "think step by step" before answering. Improves accuracy on multi-step problems.
Zero-shot — Prompting with no examples. "Translate this to French."
Few-shot — Prompting with 2–10 examples. Improves format compliance and task performance.
In-context learning (ICL) — The ability of LLMs to learn a task from examples within the prompt, without weight updates.
ReAct — "Reason + Act." Pattern where model alternates reasoning steps and tool calls.
Tree-of-Thought (ToT) — Explores multiple reasoning branches before committing to an answer.
Self-consistency — Sample multiple reasoning paths and pick the majority answer.
Reflection / self-critique — Model reviews its own output and revises. Also called "critic-actor" loop.
Extended thinking / thinking mode — Native product feature (Claude, o-series) where the model spends "reasoning tokens" before responding. Higher accuracy, higher cost.
Reasoning tokens — Tokens the model uses internally for thinking that aren't shown to the user (or shown selectively). You pay for them.
Test-time compute — Additional compute spent at inference to improve output quality (e.g., extended thinking, self-consistency, tree-of-thought). The 2024–2026 scaling story.
Scratchpad — Explicit reasoning space in the prompt where the model writes intermediate work.
Plan-and-solve — Prompt pattern: first produce a plan, then execute each step.
Persona / role prompting — Assigning the model a role ("You are a senior editor..."). Modest effect; do not overrate.
Chain-of-Verification (CoVe) — Model drafts an answer, generates verification questions, answers them, and revises. Reduces hallucinations.
Cluster 3 — Retrieval (RAG)
RAG — Retrieval-Augmented Generation — Pattern where you retrieve relevant documents from a knowledge base and inject them into the prompt before generation.
Embedding — A vector (list of numbers, usually 768–3072 dimensions) that represents the meaning of a text. Similar texts have similar embeddings.
Embedding model — A model that produces embeddings. Popular: OpenAI text-embedding-3-large, Voyage AI, Cohere embed, BGE, E5.
Vector database / vector store — A DB optimized for storing embeddings and finding nearest neighbors. Pinecone, Weaviate, Qdrant, Milvus, pgvector.
Chunking — Splitting documents into pieces before embedding. Common strategies: fixed-size (500 tokens), sentence, paragraph, semantic, sliding-window.
Chunk overlap — Overlap between adjacent chunks (usually 10–20%) to preserve context that spans boundaries.
Semantic search — Finding results by meaning (embedding similarity) rather than keyword match.
Hybrid search — Combines semantic and lexical. Usually reranked.
Reranker / cross-encoder — A second-pass model that re-scores retrieved chunks by their relevance to the query. Popular: Cohere Rerank, BGE reranker.
k / top-k retrieval — Number of chunks to fetch. Usually 5–20.
Retrieval query — The version of the user's question used for the DB search. Often rewritten for better retrieval.
Query rewriting / query expansion — Transforming the user's question into a better retrieval query. HyDE is one method.
HyDE — Hypothetical Document Embeddings — Generate a fake ideal answer, embed it, use that for retrieval.
Metadata filtering — Restrict retrieval to chunks with matching metadata (e.g., permissions, date range, doc type).
Ground truth — The correct answer, known independently. Used to score retrieval and generation.
Retrieval@k — Metric: does the correct chunk appear in the top k results?
Faithfulness / groundedness — Does the generated answer only make claims supported by the retrieved context?
Context stuffing — Just pasting a huge document into the prompt (no vector search). Feasible with 1M+ context windows for smaller corpora.
Agentic RAG — Agent decides when and what to retrieve, may issue multiple queries, may use tools beyond vector search.
GraphRAG — Retrieval over a knowledge graph rather than vector chunks. Better for entity-heavy corpora.
Cluster 4 — Agents
Agent — A model that operates in a loop: observe → decide → act (tool call) → observe → ... until the goal is met.
Tool — A function an agent can call. Formalized by JSON schemas the model can understand.
Tool call — A structured request from the model to invoke a tool with arguments.
Function calling — The lower-level API primitive. Some providers use this term instead of "tool."
Agent loop / control loop — The outer software loop that dispatches tool calls and feeds results back.
Subagent — An agent spawned by another agent to handle a bounded sub-task with its own context.
Orchestrator — The parent agent that plans and dispatches subagents.
Planner — A component (or a model call) that produces a step-by-step plan before execution.
Executor — The component that actually runs the plan's steps.
MCP — Model Context Protocol — Anthropic-originated open standard for connecting AI models to tools and data sources. Now widely adopted.
MCP server — A process that exposes tools/resources over the MCP protocol.
MCP client — An AI model / product that consumes MCP servers.
Skill — A reusable capability package (a set of instructions and tools) that a model can load on demand. Claude's "Skills" and Perplexity's skill system are examples.
Memory (agent memory) — Persistent state carried across sessions. Types: short-term (conversation), long-term (facts), episodic (event history).
HITL — Human in the Loop — Design pattern where humans approve or correct agent decisions at defined checkpoints.
Guardrails — Rules that constrain agent behavior (e.g., "never send emails," "always ask before making purchases").
ReAct agent — Agent following the ReAct pattern.
AutoGPT / BabyAGI — Early (2023) open-source agent frameworks. Historical, but the terms still come up.
Agentic — Adjective for "acting like an agent" — doing multi-step work autonomously.
Autonomous mode / auto mode — Product terminology for agents that operate without step-by-step human approval.
Long-horizon task — A task requiring many steps, tool calls, or hours of runtime.
Terminal state / done condition — When the agent decides it's finished.
Pretraining — Training a model on massive text (trillions of tokens) to learn language. Base model.
Base model / foundation model — The pretrained model before instruction tuning.
Fine-tuning — Updating a pretrained model's weights on a smaller, task-specific dataset.
Instruction tuning — Fine-tuning with (instruction, response) pairs to make the model follow instructions.
RLHF — Reinforcement Learning from Human Feedback — Training method where humans rank outputs and a reward model is trained to score outputs, then the LLM is optimized against that reward.
DPO — Direct Preference Optimization — Alternative to RLHF that skips the reward model. Simpler and often competitive.
Constitutional AI (CAI) — Anthropic's alignment method: use principles ("a constitution") to have the model critique and revise its own outputs.
RLAIF — RL from AI Feedback — Like RLHF but the ranker is another AI, not humans.
Distillation — Training a smaller model to mimic a larger one. Produces cheaper, faster models with much of the capability.
LoRA — Low-Rank Adaptation — Efficient fine-tuning method: add small trainable matrices to a frozen base model. Small artifacts (~100MB) instead of full model weights.
QLoRA — LoRA with quantized base model. Even cheaper.
Quantization — Reducing precision of model weights (e.g., FP16 → INT8 → INT4) to shrink size and speed inference. Small accuracy cost.
Weights — The parameters of a neural network. "Open-weight" model = weights are downloadable.
Open-weight model — Weights released publicly (LLaMA, Mistral, Qwen, DeepSeek). Not necessarily open-source (data + training code not always released).
Open-source model — Everything released — weights, training data, code.
Closed model — Only accessible via API (GPT-5, Claude, Gemini).
Alignment — Making a model behave in accordance with human values / intentions.
Refusal — When a model declines a request. Alignment feature; sometimes over-tuned.
Jailbreak — A prompt that bypasses safety training.
Prompt injection — Adversarial input that hijacks the model's behavior (e.g., a document that says "ignore previous instructions and...").
Model weights license — The legal terms under which weights can be used (LLaMA license, Apache 2.0, MIT, custom). Important for commercial use.
Training compute — FLOPs used to train the model. Correlated (but not perfectly) with capability.
Scaling laws — Empirical laws relating training compute, data, and parameter count to loss.
Emergent capabilities — Skills that appear only above a certain model scale (contested empirically but useful shorthand).
Cluster 6 — Multimodal
Multimodal model — Handles more than one modality (text + image + audio + video).
Vision model / VLM — Vision-Language Model. Handles text + image.
Audio model — Handles speech (ASR/TTS) or general audio.
ASR — Automatic Speech Recognition — Speech-to-text. Whisper is the reference model.
TTS — Text-to-Speech — ElevenLabs, OpenAI TTS, Google WaveNet.
Voice cloning — Generating speech in a specific person's voice. ElevenLabs Instant Voice.
Diffusion model — The dominant image/video generation architecture (Stable Diffusion, Midjourney, DALL·E, Sora). Starts with noise, iteratively denoises.
Latent space / latent diffusion — Diffusion in a compressed latent space (rather than pixel space). Much faster. Stable Diffusion's key trick.
Sampler / scheduler — Algorithm that runs the diffusion denoising steps (DDIM, DPM++, Euler, etc.).
Steps — Number of denoising steps. More = slower + usually better quality (diminishing returns after ~30–50).
CFG — Classifier-Free Guidance scale — How strongly the image follows the prompt (higher = more faithful, less creative).
Seed (image) — Random seed. Same seed + same prompt + same params = same image.
Before you build an autonomous agent, fill this out.
The one-sentence purpose
What problem does this agent solve? If you can't say it in one sentence, refactor.
The user journey
Describe the trigger, the agent's actions, and the outcome.
Trigger: what starts the agent? (schedule, event, human request)
Actions: what tools does it call, in what order?
Outcome: what changes in the world when it's done?
Tools required
Tool
Purpose
Auth needed
Read-only?
Autonomy level
Pick one:
- Suggest — Agent produces drafts, human executes
- Confirm — Agent produces actions, human approves each
- Execute — Agent runs autonomously, human reviews after
- Full auto — Agent runs, human reviews only exceptions
Rule: Start at Suggest. Earn each promotion.
Guardrails (things it will never do)
[ ] Send external communications without approval
[ ] Modify shared data without approval
[ ] Spend money above $X
[ ] Contact people outside a whitelist
[ ] Access data outside its scope
Escalation triggers
When the agent hits these, it stops and asks a human:
- [ ] Ambiguous input
- [ ] Missing required data
- [ ] Repeated tool failures
- [ ] Ethical / sensitive judgment call
- [ ] Cost cap approached
Observability
[ ] Every tool call logged with inputs, outputs, timing
[ ] Every LLM call logged with prompt version, model, tokens, cost
[ ] Errors alerted to owner
[ ] Daily summary of runs
Eval set
Before shipping, produce 5 good + 5 bad + 3 adversarial test cases. Run through the agent. Score per rubric.
Rollback
If the agent starts misbehaving:
- Kill switch: how to stop it immediately
- Revert plan: how to undo actions taken
Template to design a Custom GPT before you click "Create" in ChatGPT.
Identity
Name:
Purpose (one sentence):
Target users:
Success criterion: How you'll know it's working
Instructions (this becomes the system prompt)
You are [NAME], a [ROLE] built for [PURPOSE].
## Who uses you
[USERS]
## How you behave
[LIST — see master system prompt for pattern]
## Domain expertise
[SPECIFIC KNOWLEDGE OR RULES]
## Format defaults
[FORMATTING RULES]
## Voice
[VOICE — usually inherits from master]
## Never
[HARD CONSTRAINTS]
## Escalation
[WHEN TO REFUSE OR HAND OFF]
Knowledge (files to upload)
[ ] Personal style guide
[ ] Domain-specific docs
[ ] Prompt library relevant to this domain
[ ] Sample outputs (good and bad)
Actions (external tools)
If your GPT calls external APIs, define each action:
Action
What it does
Endpoint
Auth
Conversation starters
Four prompts users can click:
1.
2.
3.
4.
Capabilities
[ ] Web browsing
[ ] DALL·E image generation
[ ] Code interpreter
[ ] Actions (external APIs)
Sharing
[ ] Only me
[ ] Anyone with the link
[ ] Public
Test cases
Before publishing, run these 5 prompts and verify quality: