Use Flash well

Two roles, one discipline

Primary. Flash answers, writes, transforms, and proposes inside one conversation. Everything the model emits is a proposal until your harness or you act on it.

Executor. Flash runs bounded tasks under supervision — often many independent ones concurrently. The role split is the point: you keep product choices, architecture, shared contracts, dependency ordering, and final acceptance; Flash executes settled slices with a written packet (goal, inputs, ownership, constraints, acceptance checks, budget, return contract). The

flash-executor workflow skill is the canonical protocol for this; the role rules below are the summary.

Supervision is not optional: give each task an observable acceptance test, verify the produced artifact yourself, and never mark a task done because the model said it was. A raw completion cannot read your repository, run your tests, or edit your files unless your harness supplies and authorizes that loop.

Streaming and tool execution

Streaming ("stream": true) delivers the completion as incremental chunks over the same authenticated route; nothing about trust changes because bytes arrived earlier.

Tool execution follows one invariant: the model requests, the trusted harness executes. You send a tools array (advertised capability: check capabilities.tools from discovery). Flash may return tool-call requests in the assistant message. Your harness decides whether to run them, runs them with its own permissions, and returns role: "tool" results for the next turn. Flash never touches your machine directly; treat tool calls and patches as proposals to validate, and never execute response text blindly as shell commands.

Context: C, I, Omax, O — compute, don't guess

Discovery (GET /v1/models) returns three numbers per model. Name them:

• C = context_length — the total context window.
• I = max_input_tokens — the input ceiling.
• Omax = max_output_tokens — the output ceiling (also the default max_tokens when you omit it).

Your request then chooses an output reservation O (the max_tokens value you send), which is distinct from the ceiling Omax. The admission rule:

1 <= O <= Omax            (O = your max_tokens; Omax = advertised output ceiling)
O  <  C                   (the reservation must leave context for input)
rendered input tokens     <=  min(I, C - O)

Practical consequences:

• Reserve before you fill. Choose your output budget O first, then budget prompt content against C - O. If your reservation leaves too little input room for the prompt, lower O before dispatch — a request that violates the rule is rejected with a 400 and no completion is dispatched.
• Everything non-output is input. System prompt, tool definitions, skill text, and conversation history all count against the input room. Compaction history helps; it is not free.
• Use the advertised numbers, not remembered ones. Limits can change with the policy revision returned by discovery. These docs deliberately publish no hard token ceilings — discovery is the authority, and any stale number here would be a wrong promise.

Reasoning

Reasoning support is whatever discovery reports. If capabilities.reasoning.efforts is present, reasoning_effort accepts only the listed values (plus the disable value when disable_supported is true). Unsupported values are rejected with a 400 before dispatch. Do not assume effort names — read them from the response.

Concurrency without self-inflicted wounds

Concurrency is governed by your account plan and its current allowance, not by a number published in docs. Observed 429 responses are a reliable signal that pressure exceeds allowance, but they are not the only source of truth about your allowance — plan state matters too (Limits and billing). Start at one request when headroom is unknown, ramp based on observed responses, and if you get rate/concurrency rejections, reduce pressure and honor Retry-After. Handle failures the way Troubleshooting describes — uncertain dispatch is reconciled, not blindly replayed.