Prompt Engineer

Prompt Engineering for AI Agent APIs

First step (do this NOW, before reading further): run touch /tmp/.prompt-engineer-skill-loaded once. The ~/.claude/hooks/protect-prompts.sh PreToolUse hook blocks Edit/Write on prompt files (prompts/, system_prompt*, agents/tools/) until that flag exists; setting it confirms you've loaded these guidelines and lets subsequent edits proceed without re-loading the skill.

Guidelines for writing system prompts, tool descriptions, and agent instructions for building AI agents via the Claude, GPT, and Gemini APIs. This covers both prompt engineering (crafting instruction text) and the broader discipline of context engineering (orchestrating everything the model sees — tools, memory, retrieved documents, state — to maximize the likelihood of desired behavior).

Step 0 — MANDATORY before anything else

Before reading the rest of this skill, do these two things in order. They are not optional and they are not "later." Skipping them is the #1 failure mode of this skill: the user repeatedly has to ask "did you read the provider-specific md?" because the universal section below got read in isolation and the version-specific knobs were never loaded.

0a. Identify the model family in scope

Look at the code, the file being edited, the SDK being imported, or what the user just said. Match against these signals — first hit wins. Split by model family, not platform: prompt engineering is identical whether GPT runs on OpenAI or Azure, or whether Claude runs on Anthropic or AWS Bedrock. This matters more now that each major platform hosts several families — AWS Bedrock serves GPT and Claude, Vertex AI serves Gemini and Claude, and Microsoft Foundry serves GPT and Claude — so the platform alone never tells you which reference file to load; identify the model family and load that file.

If you see more than one family (cross-provider code, comparison work, or a router), load all matching reference files. If you see none (the user is asking abstractly, e.g. "how should I structure a system prompt"), ask which provider/model they're targeting before continuing — do not guess. A wrong-provider answer is worse than one clarifying question.

0b. Read the matching reference file(s) NOW

• claude → read ${CLAUDE_SKILL_DIR}/references/claude.md
• gpt → read ${CLAUDE_SKILL_DIR}/references/gpt.md
• gemini → read ${CLAUDE_SKILL_DIR}/references/gemini.md

Read the full file before giving advice or editing anything. The universal section below covers ~70% of prompt engineering, but the version-specific knobs (Opus 4.8 effort defaults + sampling removal, GPT-5.5 "stop doing" list, Gemini 3.5 thought signatures, caching mechanics, reasoning-effort defaults, migration breakages) live only in those files and change every release. Working from the universal section alone produces stale advice — the exact failure the user keeps catching.

Red flags — STOP and go back to 0a/0b

• "I already know what Claude/GPT/Gemini wants here" — model behavior shifts every version; verify against the current reference file before recommending anything model-specific.
• "The universal section is enough for this small change" — even small prompt edits interact with provider-specific defaults (reasoning effort, thinking, caching, sampling). Load the reference.
• "I'll load it later if needed" — later never comes; the load is now, before the first recommendation.
• "The user didn't mention a provider" — check the code, imports, model strings, or filename. If still unclear, ask. Do not guess.
• "This is just a debugging question, not a prompt edit" — debugging prompts IS a prompt-engineer task. The reference file likely names the exact failure mode.

Process

When editing an existing prompt, follow this order:

1. Read the full existing prompt. Understand its intent, structure, and target provider.
2. Identify the specific failure mode or improvement needed. Don't rewrite what isn't broken.
3. Draft the minimal change that addresses the issue, following the guidelines below.
4. Re-read the full prompt after editing to check for contradictions or broken flow.
5. Test the prompt on the target provider with representative inputs.

For new prompts: start minimal (role + constraints + examples + output format), test, then add instructions only when you observe failure modes.

When the prompt targets a model version newer than the one it was written for, treat it as a new model family, not a drop-in swap: switch the model, pin reasoning effort, re-run evals, trim instructions the new model no longer needs, and only then add new guidance. Legacy prompts routinely over-specify processes that newer models handle natively. See the provider reference file for version-specific migration notes.

Before submitting any prompt edit: check for contradictions (if two rules conflict, the model picks arbitrarily — remove one), and verify clarity (could a colleague with no context follow this prompt unambiguously?).

A. Universal Best Practices

These apply to all three providers and cover ~70% of prompt engineering work.

System Prompt Structure

• Set a clear role in one sentence at the top. Every provider respects persona framing.
• Use XML tags (<role>, <constraints>, <examples>, <output_format>) to separate sections. All three providers parse XML — it is the safest cross-provider delimiter.
• Be explicit and specific. Explain why a behavior matters, not just what to do. Models generalize better from explanations than from rigid rules.
• Aim for the right altitude. Sit between hardcoded if-this-then-that logic (brittle) and vague high-level guidance (under-specified). Give concrete signals while leaving room for judgment. "Minimal" does not mean "short" — it means the smallest set of high-signal tokens that fully outlines the desired behavior.
• Lead with the outcome. Describe the destination — success criteria, constraints, available context, allowed side effects, required output shape — rather than prescribing a step-by-step process. State stopping conditions explicitly. Reserve step-by-step process instructions for cases where the exact path is product-critical. (Strongest on GPT-5.x, but now good practice everywhere.)
• Tell the model what TO do, not what NOT to do. Positive framing ("Write in prose paragraphs") beats negative ("Don't use markdown").
• Prefer decision rules over absolutes for judgment calls. "If the action is reversible, proceed; otherwise confirm first" generalizes; "ALWAYS confirm" does not. Reserve hard rules for genuine invariants (safety, security).
• Start minimal, then iterate. Add instructions only when you observe failure modes. Over-engineered prompts cause over-analysis on Gemini and overtriggering on Claude.
• Don't lead the witness. Stating the answer you expect — or your own opinion, or "are you sure?" pressure — biases the model toward agreeing (sycophancy is trained in by RLHF; when a prompt hints an answer, models reason backward to justify it — arXiv:2310.13548). For judgments, extraction, and LLM-as-judge, withhold your expected answer and ask for reasoning before a verdict; to stress-test a claim, ask for the counter-case, not "do you agree?"

Few-Shot Examples

• Include 3-5 diverse examples — one of the most reliable steering mechanisms across all providers.
• Cover typical cases, edge cases, and at least one "what not to do" example.
• Wrap in <example> tags with <input> and <output> sub-tags. Keep formatting identical across every example — inconsistent structure confuses the model.
• Budget models need MORE examples (5-6 minimum) with simpler patterns.
• On reasoning/thinking models, few-shot CoT is model-family-specific — check the matching reference file before adding it. The cross-model default is to skip it: stacked exemplars and hand-written step-by-step demos run neutral-to-harmful, and the model tends to ignore the exemplars and follow the instructions instead. Describe the task + output format zero-shot and reach for examples to pin output format/schema. (DeepSeek-R1's own guidance: few-shot "consistently degrades its performance… use a zero-shot setting" — arXiv:2501.12948; corroborated by arXiv:2506.14641.) Claude is the documented exception — Anthropic recommends the opposite; see references/claude.md.

Output Format

• Prefer the provider's structured-output feature over describing a JSON schema in prose: OpenAI Structured Outputs (strict: true), Claude Structured Outputs, Gemini responseSchema. These constrain the response far more reliably than prompt text and remove the validation burden from the model.
• When you must specify format in the prompt (markdown template, structured text), provide a concrete example of the expected output, not just a description.
• Use enum arrays for valid values rather than prose descriptions — works on all providers and improves accuracy.
• When a task needs reasoning AND structured output, order the schema so a reasoning/scratchpad field comes before the answer field. Forcing the answer token first makes the model commit before it thinks and can sharply cut accuracy; the loss is largest on small/local models, and well-ordered constrained decoding is otherwise neutral-to-positive (arXiv:2408.02442; JSONSchemaBench, arXiv:2501.10868).

Context Engineering

• Context window is working memory. Every token competes for attention — more is not always better. Find the smallest set of high-signal tokens that maximize the likelihood of your desired outcome.
• Four levers (the industry-standard taxonomy, from LangChain building on Anthropic's context-engineering work). Most of the techniques below are instances of one of these — name the lever you're pulling: Write (persist context outside the window — scratchpads, state, long-term memory — so it survives truncation), Select (pull only the relevant subset back in — RAG, semantic tool selection, exposing specific state fields), Compress (keep only the tokens the next step needs — summarization, trimming, dropping used tool payloads), Isolate (split context across separate spaces — subagents with their own windows, sandboxed state, schema fields hidden from the model until needed). For how these map to concrete primitives in a framework, see the LangGraph reference.
• Put long documents at the top, queries and instructions at the bottom. This ordering improves response quality by up to 30% on complex multi-document inputs.
• Prefer progressive discovery — let agents find context through tools rather than front-loading everything. Maintain lightweight identifiers (paths, names, links) and load full content dynamically. Combine upfront retrieval (fast, known-relevant) with autonomous exploration (discovers unknowns).
• Use semantic names over technical IDs — replace UUIDs, mime_types, internal codes with human-readable names (file names, descriptive labels). LLMs reason more accurately over natural language than opaque identifiers.
• When context grows large, ask the model to quote relevant sections first before reasoning — this cuts through noise and grounds the response.
• For multi-turn agents: compact and summarize conversation history at context limits. Maximize recall first (capture every architectural decision, unresolved issue, and key finding), then tighten for precision. Use a cheap model (Flash, Haiku) for summarization. Clearing stale tool-call results is a cheap, low-risk form of compaction — once a result has been used, the raw payload can be dropped.
• For long-horizon tasks: maintain structured notes (scratchpad, state JSON) outside the conversation for information that must survive compaction.
• Point at an artifact instead of describing one. When a spec is hard to write out — a visual design, a behavior with a lot of edge cases, a convention you'd recognize but can't articulate — hand over the thing itself. Anthropic reports source code is the highest-fidelity reference (it carries structure, naming, and idiom a paraphrase loses) and that an HTML mockup of a design outperforms a prose description or a screenshot of it. Other forms that work as specs: a test suite, a function in another codebase to port (language doesn't have to match), and a rubric a verifier agent scores against. Beyond "code beats prose beats screenshot," these are alternatives rather than a ranked ladder — pick by which one you can actually produce.
• Irrelevant context actively degrades performance, and length itself is a cost — "context rot." Every added token lowers reliability, even far below the window limit and even on trivial retrieval; a single distractor measurably hurts, and models can do worse on a coherent long context than a shuffled one (Chroma "Context Rot," 18-model study, 2025). Treat a 200K/1M window as reliable to tens of thousands of tokens, not its max: retrieve the few highest-relevance chunks, prune near-duplicate distractors, and don't pad. Degradation is gradual, not a cliff.

Reducing Hallucinations

Hallucination is not one problem — different types require different mitigations.

Factual fabrication (model invents facts):

• "Ground all claims in [source]. Quote the relevant section before answering."
• "According to..." prompting — guide model to cite specific trusted sources.
• Use search/retrieval tools to connect to verified information rather than relying on training data.
• Force citations on every material fact (not necessarily shown to user). Research-validated lever for production document-grounded agents. Authoritative head-to-head (Princeton ALCE, EMNLP 2023): on ASQA dataset, "Vanilla" (passages in context + cite instruction) achieves 73.6 citation recall + 72.5 precision; "Vanilla + Rerank" (sample 4 responses, pick best) reaches 84.8 + 81.6 — the highest measured. "InlineSearch" (search-during-generation) underperforms (58.3 recall) — "retrieving text on the fly does not improve performance." Provider-level: Anthropic Citations API (Jan 2025 GA) auto-chunks documents and returns interleaved citation blocks with cited_text; cited_text doesn't count toward output tokens. Anthropic claims significantly better citation quality than prompt-based approaches. Google's NotebookLM reports 13% hallucination vs 40% for ungrounded LLMs (3× reduction) via RAG + inline citations. DeepMind GopherCite added a critical pattern: the model can abstain ("I don't know") when no good evidence exists — accuracy improved dramatically when allowed to refuse. Implementation patterns ranked by ROI: (1) verifier pass with bounded retry (Chain-of-Verification, +3-5s latency), (2) ALCE-style sample-then-rerank (2-3× cost), (3) full citation-token system with deterministic grounding guard (regex + SQL + set-membership; survives prompt injection because no LLM step is in the verification loop).

Premise acceptance (model builds on false/incoherent premises):

• "Before answering, evaluate whether the question's assumptions are valid. If concepts don't belong together or the premise is incoherent, say so specifically — identify what's wrong, don't just hedge."
• Generic disclaimers ("As an AI...") and polite hedging do NOT reduce premise acceptance. Only specific identification of the flaw works.
• It's heavily model-dependent, and effort doesn't fix it. On BullshitBench (a nonsense-detection benchmark: 100 false-premise prompts across 5 domains, 3-judge panel), clear-pushback rates span 2%–95% across models, and raising reasoning/effort does not help — it often lowers detection (GPT-5.2 none 38% > high 28%; Gemini 3.6 Flash minimal 39% > xhigh 28%), because more reasoning lets the model rationalize a way to engage the premise. Its judge rubric corroborates the point above — hedging, disclaimers, and compliments score as failure; only making the incoherence the central point counts. Those rates are un-prompted defaults (models tested with a bare "helpful assistant" prompt), so an explicit "first, check whether the premise holds" instruction is exactly the lever the benchmark leaves untested. Fix premise-acceptance with explicit prompting + model choice, not the effort/thinking_level knob.
• For agentic systems: instruct agents to verify factual claims via tools before stating them.
• Multi-tool fan-out compounds the problem — when a false-premise question (user cites a fabricated section, benefit name, specific number) triggers a generic "fire all relevant retrieval tools in parallel" rule, the parallel tools return legitimate-looking adjacent data (e.g. the kupah's equivalent benefit, the general claim-filing process, a similar-but-different section) that the agent then weaves into a reply as if it validates the fabricated premise. Mitigation: for fabricated-premise questions, do ONE targeted fact-check call to the authoritative source — not the broad fan-out.
• Trigger phrasing for the exception matters more than the exception itself. Broad triggers ("if the user cited a specific section, cap, or benefit name") fire on every coverage question — "what's the cap on heart transplants?", "what's the IVF benefit?" — and the model resolves the contradiction with the main retrieval rule by skipping fan-out broadly, regressing every legitimate multi-tool fixture. Narrow, consequent-gated triggers ("if get_user_policy returned no_results AND the user's question cited a specific section number — don't retry with a 'how to file' phrasing") only fire after a verifiable absence and stay gated to the genuine adversarial cases. When adding an exception to a tool-routing rule, verify the trigger is gated on an observable downstream signal, not a surface feature of the user message; otherwise the exception will swallow the main rule.

Reasoning errors (logically coherent but factually wrong chains):

• Use Step-Back Prompting: "First identify the high-level principles involved, then reason about the specific case." (Outperforms chain-of-thought by up to 36%.)
• Chain-of-Verification: generate answer → create verification questions → run them → produce final answer incorporating corrections.
• Verification loop before finalizing: have the agent check (1) correctness against every requirement, (2) grounding of factual claims in provided context, (3) format match to the requested schema, (4) whether the next action needs permission. Particularly effective on GPT-5.4+ agentic tasks.
• A verification/critic step needs an EXTERNAL signal to help. Intrinsic self-correction — re-checking with no new information — is flat-to-negative and can flip correct answers to wrong (Huang et al., ICLR 2024, arXiv:2310.01798). Give the check something the generator lacks: a tool/test result, retrieval, a schema/validator, or a separate-context (different-lineage) judge. Cap reflection at 2–3 iterations — unbounded self-critique loops degenerate.

Confabulation (fills knowledge gaps with plausible fiction):

• Define explicit fallback behavior: "If the provided context doesn't contain information about X, say 'I don't have information about X' — do not guess."
• In tool responses: state what is NOT included ("Does NOT include financial data — use get_project_details.")
• Eliciting usable confidence: models are reasonably calibrated on multiple-choice and on "propose an answer, then rate P(it is correct)" (P(True)), but overconfident in free-form "how sure are you, 0–100%?". Prefer MC framing or a few-shot P(True) self-check, and route low confidence to a tool or human — don't trust a free-form percentage (arXiv:2207.05221).

Tool hallucination (wrong tool, fabricated parameters):

• Addressed by tool description quality (see Section B) — this is why tool descriptions are the highest-leverage quality factor.

The unifying principle: instruct models to check against external reality (tools, documents, search) rather than generating from parameters alone. The more deterministic the grounding, the lower the hallucination rate.

Task Decomposition and Workflow Patterns

• Break complex tasks into phases with clear handoff points. Define success criteria for each phase so the model can self-check.
• Distinguish a workflow (LLM steps follow predefined code paths) from an agent (the model dynamically directs its own process and tool use). Workflows are predictable and cheaper; agents handle open-ended problems where the step count can't be known in advance. Prefer the simplest pattern that works — agents add cost and compounding-error risk.
• Five canonical patterns, pick deliberately rather than defaulting to one big agent:
  • Prompt chaining — sequential steps, each consuming the previous output, with programmatic gates between them. Best when subtasks are fixed and known.
  • Routing — classify the input, then dispatch to a specialized handler (and often a right-sized model). Best for heterogeneous inputs.
  • Parallelization — sectioning (independent subtasks run concurrently) or voting (same task run several times, results aggregated). Good for guardrails and review.
  • Orchestrator-workers — a lead model decomposes the task at runtime and delegates to workers. Use when subtasks can't be predefined.
  • Evaluator-optimizer — one model generates, another critiques against criteria, loop until it passes. Use when clear evaluation criteria exist and iteration adds value.
• Both GPT and Gemini perform better on focused prompts than bundled mega-prompts; use separate templates for distinct subtasks.

Agentic Systems

When designing multi-step or multi-agent workflows:

• The agent loop is gather context → act → verify → repeat. The verify step is load-bearing — pick the cheapest verifier that fits the output: rules/code first (linters, type-checks, validators, unit tests — the most reliable signal), a visual check second (screenshot-diff against a target), an LLM-as-judge last (least robust, highest latency — use only when the boost is worth it). This is the external signal the critic step needs (see Reducing Hallucinations).
• Subagent design — give each subagent a focused prompt and a minimal tool set. Choose whether to pass parent context based on the task: isolated subagents (no inherited context) prevent context pollution; context-aware subagents (with injected state) enable continuity. Either way, return a condensed summary (1-2K tokens) to the orchestrator, not raw exploration. Spell out four things in every delegation — objective, output format, tool/source guidance, and task boundaries; vague delegation ("research X") makes subagents duplicate work and leave gaps.
• State management — use structured JSON for trackable state (phase progress, scores, pass/fail) and free text for qualitative notes (findings, reasoning). Emit state updates the orchestrator can act on.
• Context across windows — when a task spans multiple context windows, start the new window with a structured summary of prior findings, not raw conversation history.
• Autonomy calibration — prompt says, harness enforces. Be explicit about what the agent MAY do autonomously vs. what requires confirmation (default: reads autonomous; write/delete and externally-visible operations require confirmation). But a system-prompt prohibition ("never do X") reduces, not eliminates the behavior, and a one-time assertion (identity, a pricing rule, a safety limit) decays over long context — so enforce load-bearing guardrails in the harness (least-privilege tools, human approval on irreversible actions, external memory/verification tools over recall), not in prose alone. (Models also misbehave somewhat more when they believe the situation is real rather than an eval.)
• Subagent spawning is model-version-dependent and steerable — some models over-spawn, some under-spawn. Don't hardcode an assumption; check the provider reference file and calibrate to observed behavior. State when delegation is and isn't warranted ("delegate for parallel or isolated workstreams; for simple lookups and single-file edits, work directly").
• Completeness contracts — for multi-deliverable tasks, instruct the agent to treat the task as incomplete until every requested item is covered or explicitly marked [blocked], maintaining an internal checklist. Prevents premature stopping, especially on GPT-5.4+.
• Reliability ≠ capability — design for consistency, not just a good single run. A tool-agent that passes ~half of tasks once passes all of k repeated trials far less often (τ-bench pass^8 <25%, arXiv:2406.12045), and models "get lost" in multi-turn — dribbling a task out across turns costs ~39% vs. one well-specified turn, because they commit to early assumptions and don't recover (arXiv:2505.06120). So: give a fully-specifiable task in ONE well-formed turn (or periodically re-state a consolidated spec on long runs); tell the agent to hold early assumptions as revisable and not finalize prematurely; move rule-checkable steps (eligibility, limits) into deterministic checks rather than free-form reasoning; and evaluate with repeated-trial consistency (pass^k), not a single pass.
• Empty-result recovery — when a lookup returns empty or narrow results, instruct the agent to try at least one fallback (alternate query wording, broader filter) before reporting "not found." Reduces false-negative reports across all providers.
• Search wide, then narrow — tell research/tool-using agents to start with short, broad queries to survey the space before drilling into specifics; they default to over-long, over-specific queries that return too little.
• Tool-use persistence — instruct the agent not to stop early when another tool call is likely to materially improve correctness or completeness. Keep calling tools until the task is done and verification passes.
• Token budgets — for workloads where the agent should scope its work to an allowance, some providers expose an advisory budget the model can see and pace against (distinct from a hard max_tokens cap). See the provider reference file.
• Multi-agent topology — when you do split into multiple agents, pick the coordination shape deliberately: supervisor (a central agent routes to and aggregates specialized workers — predictable, debuggable, the orchestrator-workers pattern) vs swarm (peers hand off control directly to one another — flexible, no bottleneck, harder to trace). Supervisor is the safe default; reach for swarm only when peer-to-peer handoff genuinely fits. Either way, give each agent a focused prompt + minimal tools, and decide explicitly what shared state crosses the handoff. The framework reference (${CLAUDE_SKILL_DIR}/references/langgraph.md) shows how these map to concrete primitives.
• Scale effort to the task, and budget the cost. Rough depth heuristics: a simple fact-find ≈ 1 agent / 3–10 tool calls; a comparison ≈ 2–4 subagents / 10–15 calls each; a complex task ≈ 10+ subagents with divided roles. Fan-out is expensive — an agent spends ~4× the tokens of a chat turn and a multi-agent system ~15× (token usage alone explained ~80% of performance variance in Anthropic's research), so reach for subagents only when the task's value justifies the spend.

Sampling Parameters and Determinism

Frontier models are moving away from caller-controlled sampling. Claude Opus 4.8/4.7, Sonnet 5, and Fable 5 return a 400 error if temperature, top_p, or top_k are set to non-default values; Gemini 3.x strongly recommends not setting them at all; GPT still accepts them (except Azure/Foundry reasoning models, which reject them) but the trend is the same. Two consequences:

• Don't reach for temperature to steer behavior — use explicit prompting, structured outputs, and the reasoning/effort knob instead.
• temperature = 0 never guaranteed identical outputs anyway. For determinism, constrain the output (structured outputs, enum fields, explicit format rules) rather than lowering temperature.

B. Tool Descriptions

Tool descriptions are the single most impactful quality factor for tool-use accuracy across all three providers. Write them like prompts — they are loaded into the agent's context and collectively steer tool-calling behavior.

Minimum Requirements

• Full models: 3-4 sentences minimum. Budget models: 5-6 sentences.
• Every tool description must cover:
  1. What it does — one clear sentence
  2. When to use it — specific triggers and conditions
  3. When NOT to use it — common mistakes and overlapping tools
  4. Parameters — type, constraints, valid values, format for each
  5. Return value — what comes back and what does NOT
  6. Caveats — rate limits, data freshness, error conditions
• Write for a capable newcomer to the domain: make implicit context explicit, define niche terminology and query formats, and name parameters unambiguously (user_id, not user).

Architecture

• Limit active tools to 10-20 for best accuracy on all providers. Curate a minimal set — if a human cannot definitively choose between two tools, the model cannot either.
• For larger sets, use tool search / dynamic loading so infrequently-used tools don't crowd context. For very large surfaces (hundreds to thousands of tools, e.g. many MCP servers), consider code execution — expose tools as a code API the agent imports on demand, runs loops and filtering against in a sandbox, and only returns distilled results. This keeps tool definitions and intermediate data out of context (Anthropic reports up to ~98% token reduction) at the cost of needing sandbox infrastructure.
• Build tools around workflows, not API wrappers. schedule_event (finds availability AND books) beats separate list_users + list_events + create_event. Fewer, higher-value tools outperform many narrow ones.
• Mind agent affordances — a tool that can dump unbounded data into context is a liability. Prefer search_contacts over list_contacts; add pagination, filtering, and limits.
• Apply poka-yoke — design parameters and signatures so misuse is structurally hard (required fields, enums, no ambiguous free-text where a constrained value would do).
• Use meaningful namespaced names in snake_case. Group related tools with prefixes — asana_search, asana_projects_search. Prefix- vs. suffix-based namespacing both have measurable accuracy impact; test both schemes on your tool set.
• All three providers support parallel tool calling — design tools to be independently callable.
• Iterate via evaluation: small description improvements yield dramatic gains. Create realistic multi-tool test cases, run programmatically, analyze transcripts. When a tool is misused, fix the description first — it's the highest-leverage fix. You can also have the model itself read transcripts and propose description/signature refactors.

Provider-Specific Tool Guidance

Effective Patterns from Production Systems

• Decision-tree routing: "Use X for Y. Do not use Z — use W instead." Direct, unambiguous tool selection.
• When to use / When NOT to use as first-class sections — put these at the top of the description, not buried after parameter docs. Include specific triggers, not just "when relevant."
• Name alternatives explicitly: "Do NOT use for searching employees — use search_employees instead." The model needs to know what to call instead.
• Safety constraints separated — mark irreversible or dangerous operations distinctly from functional description.
• Concrete thresholds — "3+ steps" not "complex tasks"; "at least 2 characters" not "enough text." Numeric where possible.

Input Examples

For complex tools with nested objects, optional parameters, format-sensitive inputs, or tools easily confused with each other — supply 1-5 valid example inputs. On Claude this is a first-class field on the tool definition, input_examples, not prose buried in the description; Anthropic's internal testing puts it at 72% → 90% on complex parameter handling (advanced tool use). They add tokens to every request, so they earn their place where the schema is genuinely hard to guess and not where it's self-evident.

Keep this distinct from examples that teach a model how or when to call a tool. For the Claude 5 generation Anthropic reports those constrain the model to the exploration space the examples imply — design an expressive interface instead. A status enum of pending/in_progress/completed conveys the state machine, and one line ("keep exactly one item in_progress") conveys the rule, with no example needed. input_examples answers "what does a valid input look like"; interface design answers "when do I reach for this."

See ${CLAUDE_SKILL_DIR}/templates/tool-description-template.md for the full structured format.

Tool Response Design

Tool responses are context — bloated responses waste tokens and degrade reasoning on subsequent steps.

• Return only high-signal information. Strip internal IDs, metadata, and fields the model will not use.
• Use semantic values over technical ones — return file_type: "spreadsheet" not mime_type: "application/vnd.openxmlformats...". Return status: "approved" not status_code: 3.
• Paginate large results with sensible defaults. Include total count and a guidance message: "Showing 20 of 487 results. Narrow your query or use offset for next page." — steer the model toward targeted searches.
• Truncate long text with a structural outline — return the first N lines plus an outline (headers, sections) so the model can request specific parts. Pick a concrete default ceiling (Claude Code truncates tool output at ~25k tokens) and include guidance text when you truncate.
• Explicit absence — state what is NOT included: "Does NOT include financial data — use get_project_details." This prevents hallucinated fields.
• Actionable errors — return specific, actionable error messages, not opaque codes. "No results for 'XYZ'. Try broader terms or check spelling." beats "Error 404".
• Response format parameter — expose a format parameter ("detailed" vs "concise") letting agents choose output verbosity. A concise response can be 3x fewer tokens than detailed, saving context for reasoning.

C. Provider Differences

For depth on any one provider — including current model versions and migration notes — read ${CLAUDE_SKILL_DIR}/references/{claude,gpt,gemini}.md. The tables below are the at-a-glance comparison; the reference files explain each column and track model releases.

System Prompt Role and Placement

Prompting Style

Reasoning and Thinking

…(truncated)