Gemini 3.8 prompting guide: thinking levels, long context, media and grounding

If you are prompting Gemini 3.8, most of the gains come from what you stop doing: stop lowering temperature, stop asking for visible step-by-step reasoning, and stop pasting media at full resolution. Then do four things on purpose: pick a thinking_level, put the question after the context, set media_resolution per item, and validate structured output in code.

This guide is built from Google's own Gemini API pages, all read on 2026-10-09 (links in each section). I did not call the API, so there are no measured outputs about model quality here. The two things I ran are small scripts that use numbers printed on those pages, and their real output is pasted. For picking between 3.8 Flash and Flash-Lite, see Gemini 3.8 Flash vs 3.5 Flash-Lite; the older Gemini 2.5 Pro guide covers the previous generation's thinking_budget style.

Which Gemini 3 model are we talking about?

Google's models page lists Gemini 3.8 Flash as the newest text model (gemini-3.8-flash, stable). The Pro option on that page is still gemini-3.1-pro-preview. One trap: a sample on Google's thinking page uses the ID gemini-3.8-pro, but that ID does not appear on the models page, so do not copy it.

Prices are from the pricing page, paid tier, standard processing, output including thinking tokens. The step-up date matters: any budget for 3.8 Flash that runs past 31 December 2026 should use the doubled rates. 3.8 Flash takes up to 1,048,576 input tokens and 65,536 output tokens, per its model page.

A privacy note from the same pricing page: on the free tier, "used to improve our products" is Yes; on the paid tier it is No. Do not send customer data through a free key.

How does the current request shape look?

Google's current docs teach the Interactions API (client.interactions.create) rather than generateContent. Two details change how you write prompts. First, system_instruction, tools and generation_config are interaction-scoped: with previous_interaction_id only the conversation history carries over, so you must resend your system instruction and settings on every turn. Second, interactions are stored by default (store=true), retained 55 days on the paid tier and 1 day on the free tier; set store=false if that is not acceptable, which also disables previous_interaction_id.

Unrun sketch, with the structure taken from Google's examples:

from google import genai

client = genai.Client()
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    system_instruction="Answer from the supplied context only. Be concise.",
    input="<context>...your documents...</context>\n\nBased on the information above, list the renewal dates.",
    generation_config={"thinking_level": "low"},
    store=False,
)
print(interaction.output_text)

The system_instruction argument name comes from the interaction-scoped list on Google's page; check the SDK reference for the exact call signature before you rely on it. If you manage history yourself in stateless mode, resend the model's thought blocks exactly as received, because they carry the signatures Gemini needs to continue its reasoning.

How do I choose a thinking level?

thinking_level replaces the old token-budget thinking dial. Google's guidance: minimal or low for fact retrieval and classification, the default for comparisons and moderate reasoning, and the highest setting for advanced coding, math or multi-step planning. Two sharp edges:

• max_output_tokens includes thinking tokens and is a hard cutoff. If the model hits it while reasoning, the response ends with status incomplete and truncated or empty output, and you are still billed for the thinking. Google's advice is to lower thinking_level rather than set a small cap.
• Thought summaries are off unless you ask (thinking_summaries: "auto"), and a thought step can arrive with a signature but no summary, so your code must tolerate an empty summary.

Here is the config linter I wrote from those rules, run on a config that looks like it was ported from an older model. Real output, 2026-10-09:

ported from a 2.5-era config
  ERROR thinking_level 'minimal' is not listed for gemini-3.8-flash
  WARN  temperature below 1.0 on Gemini 3.x: Google says keep defaults (looping, degraded reasoning)
  WARN  'top_p' set: Google recommends leaving sampling parameters at defaults on Gemini 3.x
  WARN  small max_output_tokens counts thinking tokens too; truncation returns status 'incomplete'. Lower thinking_level instead

clean
  OK    nothing flagged

Flash-Lite minimal
  OK    nothing flagged

The linter is about 30 lines: a dictionary of levels per model from the thinking page, plus three if checks. It only knows what the pages say; extend the dictionary for the models you use.

How should I write instructions for Gemini 3?

Google's prompt design page says Gemini 3 responds best to prompts that are direct, well structured and clear about the task and constraints. Concretely:

1. Be precise, drop the persuasion. State the goal once. Google says to avoid unnecessary or overly persuasive language.
2. Pick one delimiter style. XML-style tags (context, task) or Markdown headings both work; mix neither within a prompt.
3. Put the must-haves up top. Role, behavioural constraints and output format go in the system instruction or at the very start of the user prompt.
4. Ask for verbosity. By default Gemini 3 gives direct, efficient answers. If you want a conversational or detailed reply, say so.
5. Show, don't only tell. Google recommends always including few-shot examples, and says that clear examples can let you remove instructions. Keep example formatting identical across examples.
6. Do not script the reasoning. The model thinks internally, so you rarely need it to plan in the visible answer. For hard problems, a plain "think very hard before answering" can help, at the cost of thinking tokens, per Google.

An untested template following those rules:

System instruction:
Role: contract analyst for a small business.
Rules: use only the supplied context; if a fact is not stated, write "not stated".
Output: a Markdown table with columns Clause, Page, Risk (low/medium/high), Reason.
Length: terse. One line per row.

User prompt:
<context>
[contract text]
</context>
<task>
List every clause that lets the vendor change price. Based on the information above.
</task>

Google also publishes grounding and current-date clauses for Gemini 3 Flash in the same page (a strictly-grounded system prompt, and a reminder of the current year for time-sensitive search queries). Copy them from the source rather than from a blog; the wording is theirs.

What order should long context go in?

Context first, question last. Google's guidance for long inputs is to supply all documents or code first, put your specific instructions at the very end, and bridge with a phrase like "Based on the information above...". The long-context page agrees: for long prompts, the query at the end of the prompt generally performs better.

Three honest limits from that page. Retrieval of one fact is far more reliable than retrieval of many: Google notes that with multiple "needles" accuracy is not the same and varies widely. Passing tokens you do not need is not free in latency or money. And if you reuse the same big context across questions, context caching is the lever; Google describes cached input as roughly 4x cheaper than standard for Flash. On 3.8 Flash the page lists a cache read price of $0.075 per 1M tokens through 2026-12-31 plus a storage fee of $0.50 per 1M tokens per hour, so a cache sitting idle is not free. When the corpus is huge or changes constantly, RAG versus long context versus compaction is the better frame, and context rot explains why more tokens can hurt.

How do I control media cost with media_resolution?

On Gemini 3 you can set media_resolution per content item, so a dense diagram gets high and a decorative screenshot gets low in the same request. Google's page gives these approximate token counts for Gemini 3 models:

Google recommends high for most image work, medium for PDFs (quality typically saturates there, and high rarely improves OCR on standard documents), low or medium for general video, and high for video only when you need to read dense text in frames. I turned the table into a budget calculator. For 200 images on gemini-3.8-flash, real output:

Input tokens and cost for 200 images, gemini-3.8-flash
  low           56,000 tokens   $0.0420 now   $0.0840 from 2027-01-01
  medium       112,000 tokens   $0.0840 now   $0.1680 from 2027-01-01
  high         224,000 tokens   $0.1680 now   $0.3360 from 2027-01-01
  ultra_high   448,000 tokens   $0.3360 now   $0.6720 from 2027-01-01

One hour of audio = 90,000 tokens at 25/s

The arithmetic is trivial: tokens times the input price. The point is the habit. Before you send a batch, multiply images by the tokens per image and compare with the window. Measure quality at low and medium on a sample before you pay for high.

What does grounding cost, and can I combine tools with structured output?

Grounding with Google Search lets the model cite live web sources and returns inline url_citation annotations you can render. On Gemini 3 you are billed for each search query the model decides to run, so one prompt that triggers two searches counts as two. The pricing page lists 5,000 free search requests per month shared across Gemini 3.x models, then $14 per 1,000. Turn it on when the answer may depend on recent or obscure facts, and leave it off for tasks answerable from your own context.

Structured outputs take a JSON Schema in response_format (with mime_type set to application/json). Google says the output is syntactically valid but you must validate the values yourself, that only a subset of JSON Schema is supported, and that very large or deeply nested schemas can be rejected. On Gemini 3 only, in preview, you can combine structured output with built-in tools such as Google Search and URL context and with function calling. See structured outputs across providers for how this compares with OpenAI and Claude.

For function calling, tool_choice in generation_config takes auto (default), any, none or validated. Google's best practices are practical: descriptive function names without spaces, specific types and enums, a clear description per parameter, and no more than 10 to 20 active tools. One documented quirk: if your prompt forces the model to emit structured text such as XML immediately before a tool call, the call can occasionally fail with Malformed_Function_Call, and the page lists workarounds.

Gemini 2.x to 3.8 migration checklist

1. Delete temperature, top_p and top_k from ported configs; tune with thinking_level and clearer instructions.
2. Replace thinking budgets with a level your model supports. minimal errors on 3.8 Flash.
3. Remove "think step by step" scaffolding from visible output unless you need the reasoning displayed.
4. Move the question to the end of long prompts and add the bridge sentence.
5. Resend system_instruction, tools and generation_config on every interaction.
6. Decide on store, and in stateless mode resend thought blocks unmodified.
7. Set media_resolution per item and budget images with the table above.
8. Add few-shot examples with identical formatting.
9. Validate every structured field in code; treat schema-valid as not the same as correct.
10. Re-run your eval set. Google's pages are the starting point; your tasks decide. For a vendor-neutral process, see migrating prompts to new models, and for the dial names across vendors, reasoning effort controls explained.

What I could not verify

I did not call the Gemini API, so no claim about answer quality, latency or the exact error text is measured. The SDK call in the sketch is unrun and its argument names should be checked against the SDK reference. Google's pages were read as plain text extracted from HTML, so a nuance in a table may have been lost; recheck the model and pricing pages before you commit a budget, because the Flash price change on 2027-01-01 is already scheduled.