Length control sounds trivial until you run the same prompt a thousand times a day. Too long, and you pay for tokens nobody reads and your UI scrolls forever; too short, and the analysis your users needed got compressed away. Claude offers three distinct levers — max_tokens, the effort parameter, and the prompt itself — and they do different jobs. Confusing them is the most common length-control mistake.
Lever 1: max_tokens is a guillotine, not a request
max_tokens is a hard ceiling on how many tokens Claude may generate. It does not tell Claude to aim for that length — it truncates the response mid-sentence when the limit is reached, signaled by stop_reason: "max_tokens". Setting max_tokens: 200 to get short answers gets you amputated answers. Two facts make generous limits cheap insurance: you pay only for tokens actually generated, and output-token rate limits count real generation in real time — a high max_tokens has no rate-limit downside. One caution in the other direction: on models with thinking enabled, thinking tokens count toward max_tokens too, so a tight limit can starve the visible answer. Treat max_tokens as a safety net against runaways, and control target length elsewhere. Always check stop_reason in production; a truncated JSON payload or contract summary should be retried with a higher limit, not shipped.
Lever 2: effort sets the default appetite
The effort parameter (output_config: {"effort": ...}, levels low, medium, high — the default — xhigh, and max on supported models) is a behavioral signal that affects all response tokens: text, tool calls, and thinking. The official docs describe the effect directly: at lower effort Claude acts with less preamble and terser output; at higher effort it produces more detailed plans and summaries. For a high-volume endpoint whose answers should be brisk — status summaries, ticket tags, short replies — dropping to medium or low effort shortens output across the board without rewriting a single prompt. It's a dial, not a specification: for exact shapes you still need lever 3.
Lever 3: the prompt specifies the shape
Here's why "keep it under 150 words" disappoints: models generate token by token and don't reliably meter word counts, so a numeric target is treated as a vibe, not a contract. You'll get roughly 150 words — sometimes 90, sometimes 240. If rough is fine, a word count is fine. When length actually matters, specify structure instead — structural constraints are things Claude follows far more reliably than arithmetic:
- "Answer in one sentence." / "Exactly three bullet points, each under one line."
- "A summary paragraph, then a table of findings, then a one-line recommendation."
- For reports: name the sections. A skeleton of required headings produces a full document far more reliably than "be thorough."
Explain the constraint's purpose, too — the best-practices docs show Claude generalizes from reasons ("this appears in a mobile push notification, so it must fit in one short sentence"). And note that the old trick of prefilling the assistant's response to force brevity is gone: prefilled responses return a 400 error on current models. The documented replacements are direct "no preamble" instructions and structured outputs — a JSON schema with a description like "one-sentence summary" on a field is the strongest length constraint available for machine-read output.
max_tokens caps disasters, effort sets the default appetite, and the prompt specifies the shape. Use all three; expect none of them to do the others' job.Going deep on purpose
Getting genuinely long output — a full report rather than a page — is the same problem in reverse. Raise max_tokens well above the target so the ceiling never binds, keep effort at high or above, and make depth explicit and structural: enumerate the sections, require evidence per section, and ask Claude to continue through all of them before concluding. Explicitly requesting "above and beyond" behavior, rather than implying it, is documented best practice.
Where to go next
Length interacts with cost — see the input/output token split — and with format: output format control covers the structural toolkit in depth. The quickstart shows the parameters in a working call.