SPB Git

Repository Public

prompting-claude-fable-5-1.md 53.3 KB 899 lines markdown

1---2title: Prompting Claude Fable 5.13url: https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-14description: Behavioral differences and prompting patterns for Claude Fable 5.1 and Claude Mythos 5.1, covering effort, progress updates, tool-call batching, conversation history, writing style, formatting, task completion, compaction summaries, scope and test coverage, search triggering, safeguard false positives, file edits, long outputs, subagents, and vision.5---67For the model's capabilities, API changes, pricing, and availability, see [What's new in Claude Fable 5.1](https://platform.claude.com/docs/en/models/fable-5-1/whats-new-fable-5-1). For techniques that apply across Claude models, see [Prompting best practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices).89Your existing Claude Fable 5 prompts should perform well on Claude Fable 5.1 without changes, but a handful of behavioral differences are worth knowing about. Start with the section that matches what you observe:1011* Unsure which effort level to run, or latency and cost are higher than the task warrants: [Consider all effort levels](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#consider-all-effort-levels)12* Little or no text between tool calls: [Ask for user-facing progress updates](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#ask-for-user-facing-progress-updates)13* One tool call per turn in agent loops: [Batch independent tool calls in agent loops](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#batch-independent-tool-calls-in-agent-loops)14* Requests fail with `bound to a different conversation`, or your harness edits earlier turns between requests: [Keep the conversation history append-only](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#keep-the-conversation-history-append-only)15* Prose runs long and dense: [Writing density](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#writing-density)16* Chat replies carry less structure than the content needs: [Formatting in chat](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#formatting-in-chat)17* Summaries reproduce source wording without marking it as a quotation: [Quoting retrieved sources](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#quoting-retrieved-sources)18* Turn ends before the work is done, or the model asks permission for work you already requested: [Finish the whole task](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#finish-the-whole-task)19* Client-side compaction summaries drop constraints, decisions, or exact details: [Tell the model what to preserve in compaction summaries](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#tell-the-model-what-to-preserve-in-compaction-summaries)20* Unrequested fixes or extensions, or more committed test files than the task called for: [Keep changes and tests to what the task asks for](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#keep-changes-and-tests-to-what-the-task-asks-for)21* Answers from memory instead of searching at low effort: [Search triggering at low effort](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#search-triggering-at-low-effort)22* Benign coding requests return `stop_reason: "refusal"`: [Reduce safeguard false positives](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#reduce-safeguard-false-positives)23* Whole files rewritten for small changes: [Prefer targeted edits over whole-file rewrites](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#prefer-targeted-edits-over-whole-file-rewrites)24* Long deliverables at `xhigh` or `max` effort take a long time or hit `max_tokens`: [Leave room for long outputs at xhigh and max effort](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#leave-room-for-long-outputs-at-xhigh-and-max-effort)25* Lead agent idles while subagents run: [Let the lead agent keep working while subagents run](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#let-the-lead-agent-keep-working-while-subagents-run)26* Answers about charts and dense images miss detail: [Give vision work tools to crop and zoom](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#give-vision-work-tools-to-crop-and-zoom)2728<Note>29  Claude Fable 5.1 runs safety classifiers and can return `stop_reason: "refusal"`. See [Refusals, fallback, and billing](https://platform.claude.com/docs/en/models/fable-5-1/whats-new-fable-5-1#refusals-fallback-and-billing) and [Reduce safeguard false positives](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#reduce-safeguard-false-positives).30</Note>3132## Consider all effort levels3334Start at the default [effort](https://platform.claude.com/docs/en/build-with-claude/effort) level, `high`, then test the other levels (`low`, `medium`, `xhigh`, and `max`) against your own evals. Effort is the primary control for trading off intelligence, latency, and cost on Claude Fable 5.1. Re-run the sweep even if you already ran one on Claude Fable 5: effort level names don't correspond to the same amount of thinking across models.3536Claude Fable 5.1's capability gains over Claude Fable 5 show up across effort levels and are largest at the higher settings. At `medium`, results roughly match Claude Fable 5 at lower cost, so step down to `medium` or `low` where your evals show quality holds. At `low`, Claude Fable 5.1 is often competitive with Claude Opus and Claude Sonnet models on cost per task while scoring higher, so include it in the comparison wherever you'd otherwise run a smaller model at a higher effort level.3738Two effort-specific behaviors have their own sections: at `low`, Claude Fable 5.1 calls search and retrieval tools less often (see [Search triggering at low effort](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#search-triggering-at-low-effort)), and at `xhigh` and `max` it can think for longer before writing a long deliverable (see [Leave room for long outputs at xhigh and max effort](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#leave-room-for-long-outputs-at-xhigh-and-max-effort)).3940## Ask for user-facing progress updates4142Claude Fable 5.1's default behavior is to write fewer user-facing updates during long tool-calling turns than Claude Fable 5 does. This becomes more pronounced at higher effort and in longer tool chains. Users see the agent go quiet for minutes at a time, or a final message that covers only the last step rather than the whole task.4344First, check that your client receives progress updates at all. The model's short notes between tool calls, what it just found and what it's doing next, come back as [progress-update `thinking` blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#progress-updates), and those blocks are empty under the default `thinking.display` of `"omitted"`. Set `display: "updates"` (beta, `thinking-display-updates-2026-08-18` header) and render each non-empty `thinking` block as a status line, or set `"summarized"` to receive them along with summarized reasoning. If you aren't requesting them, the model's updates may simply not be reaching your users.4546Second, audit your prompt for instructions that suppress narration. Some earlier models were eager to give updates while working, which led to system prompt lines such as "hold all findings for the final response." Remove lines like that before adding anything.4748If you still want more updates, for example when pair programming or in other human-in-the-loop work, add a short system prompt line that says when you want user-facing text from the model and what each update should contain:4950```text wrap51Before you start, say in a line what you're about to do; brief updates while you work help the user follow along. Close with a short recap that stands on its own — what you found, what you did, and what's next — so a reader who only sees the last message has the full picture.52```5354If your product collapses or hides tool output, tell the model. Otherwise it may run commands to "show" the user output that your UI never displays. Deliver the note in a [turn-scoped system message](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#turn-scoped-system-messages) (`clear_at: "next_user_message"`, beta):5556```text wrap57Only you see that command's output — the user's terminal shows at most a few lines of it. If the user needs to read any of it, put it in your reply.58```5960## Batch independent tool calls in agent loops6162Claude Fable 5.1 usually issues parallel tool calls as expected: when a request names several things to fetch, it issues those calls in parallel. The exception is coding and computer-use loops where the next independent calls are implied by the task rather than explicitly requested (custom coding agents, bash-and-editor harnesses, computer use): there it may issue them one per turn instead. This doesn't affect answer quality, but each extra turn costs tokens, a round trip, and wall-clock time. A one-sentence nudge at the end of the current request addresses it:6364```text wrap65First privately list what you need next; then request every item that doesn't depend on another's result in this one response.66```6768Each time you send tool results back, append it after that user message as a [turn-scoped system message](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#turn-scoped-system-messages): a `role: "system"` entry in `messages` with `clear_at: "next_user_message"`. Once a later user message exists, the API clears the earlier copies, so the model reads only the newest one. Turn-scoped system messages are in beta and require the [beta header](https://platform.claude.com/docs/en/api/beta-headers) `mid-conversation-system-clear-at-2026-08-21`. Without the beta, place the sentence in a text block after the `tool_result` blocks in the same user message instead.6970Append a fresh copy each turn and leave the earlier copies where they are, byte-for-byte. They stay in the array, but once cleared the model doesn't see them and they cost no input tokens. Deleting or rewriting them is an edit to earlier turns: it restarts the [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) from that point and invalidates the thinking blocks that came after them (see [Keep the conversation history append-only](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#keep-the-conversation-history-append-only)).7172The following loop shows this placement. Each assistant turn goes back exactly as returned, each user turn carries only the tool results, and a fresh turn-scoped copy of the nudge follows it.7374<CodeGroup exclude="shell">75  ```python Python76  import anthropic77  from anthropic.types.beta import (78      BetaMessageParam,79      BetaToolParam,80      BetaToolResultBlockParam,81  )8283  client = anthropic.Anthropic()8485  BATCH_NUDGE = (86      "First privately list what you need next; then request every item "87      "that doesn't depend on another's result in this one response."88  )89  # In-memory files stand in for a working directory so the sample runs anywhere.90  FILES = {91      "pyproject.toml": """\92  [project]93  name = "demo"94  version = "0.1.0"95  description = "Demo project for the batching example"96  """,97      "README.md": """\98  # demo99100  A small demo project. Run `demo --help` for usage.101  """,102  }103  tools: list[BetaToolParam] = [104      {105          "name": "read_file",106          "description": "Read a UTF-8 text file from the working directory.",107          "input_schema": {108              "type": "object",109              "properties": {"path": {"type": "string"}},110              "required": ["path"],111          },112      }113  ]114  messages: list[BetaMessageParam] = [115      {"role": "user", "content": "Summarize pyproject.toml and README.md."}116  ]117118  while True:119      response = client.beta.messages.create(120          model="claude-fable-5-1",121          max_tokens=16000,122          betas=["mid-conversation-system-clear-at-2026-08-21"],123          tools=tools,124          messages=messages,125      )126      # Append the assistant turn exactly as returned, thinking blocks included.127      messages.append({"role": "assistant", "content": response.content})128      if response.stop_reason != "tool_use":129          break130      tool_results: list[BetaToolResultBlockParam] = []131      for block in response.content:132          if block.type == "tool_use":133              raw_path = block.input.get("path")134              path = raw_path if isinstance(raw_path, str) else ""135              if path in FILES:136                  tool_results.append(137                      {138                          "type": "tool_result",139                          "tool_use_id": block.id,140                          "content": FILES[path],141                      }142                  )143              else:144                  tool_results.append(145                      {146                          "type": "tool_result",147                          "tool_use_id": block.id,148                          "content": f"File not found: {path}",149                          "is_error": True,150                      }151                  )152      # Send the tool results as the user turn, then a fresh copy of the nudge as a153      # turn-scoped system message. Leave earlier copies in place: the API clears them,154      # so the model sees only the newest one.155      messages.append({"role": "user", "content": tool_results})156      messages.append(157          {"role": "system", "content": BATCH_NUDGE, "clear_at": "next_user_message"}158      )159160  print(next((block.text for block in response.content if block.type == "text"), ""))161  ```162163  ```typescript TypeScript164  import Anthropic from "@anthropic-ai/sdk";165166  const client = new Anthropic();167168  const BATCH_NUDGE =169    "First privately list what you need next; then request every item " +170    "that doesn't depend on another's result in this one response.";171  // In-memory files stand in for a working directory so the sample runs anywhere.172  const FILES = new Map<string, string>([173    [174      "pyproject.toml",175      `[project]176  name = "demo"177  version = "0.1.0"178  description = "Demo project for the batching example"179  `,180    ],181    [182      "README.md",183      `# demo184185  A small demo project. Run \`demo --help\` for usage.186  `,187    ],188  ]);189  const tools: Anthropic.Beta.Messages.BetaTool[] = [190    {191      name: "read_file",192      description: "Read a UTF-8 text file from the working directory.",193      input_schema: {194        type: "object",195        properties: { path: { type: "string" } },196        required: ["path"],197      },198    },199  ];200  const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [201    { role: "user", content: "Summarize pyproject.toml and README.md." },202  ];203204  let response: Anthropic.Beta.Messages.BetaMessage;205  while (true) {206    response = await client.beta.messages.create({207      model: "claude-fable-5-1",208      max_tokens: 16000,209      betas: ["mid-conversation-system-clear-at-2026-08-21"],210      tools,211      messages,212    });213    // Append the assistant turn exactly as returned, thinking blocks included.214    messages.push({ role: "assistant", content: response.content });215    if (response.stop_reason !== "tool_use") {216      break;217    }218    const toolResults: Anthropic.Beta.Messages.BetaToolResultBlockParam[] = [];219    for (const block of response.content) {220      if (block.type !== "tool_use") {221        continue;222      }223      const { input } = block;224      const path =225        typeof input === "object" &&226        input !== null &&227        "path" in input &&228        typeof input.path === "string"229          ? input.path230          : "";231      const text = FILES.get(path);232      if (text === undefined) {233        toolResults.push({234          type: "tool_result",235          tool_use_id: block.id,236          content: `File not found: ${path}`,237          is_error: true,238        });239        continue;240      }241      toolResults.push({242        type: "tool_result",243        tool_use_id: block.id,244        content: text,245      });246    }247    // Send the tool results as the user turn, then a fresh copy of the nudge as a248    // turn-scoped system message. Leave earlier copies in place: the API clears them,249    // so the model sees only the newest one.250    messages.push({ role: "user", content: toolResults });251    messages.push({252      role: "system",253      content: BATCH_NUDGE,254      clear_at: "next_user_message",255    });256  }257258  const finalText = response.content.find((block) => block.type === "text");259  console.log(finalText?.text ?? "");260  ```261262  ```csharp C#263  using System.Text.Json;264  using Anthropic;265  using Anthropic.Models.Beta.Messages;266267  AnthropicClient client = new();268269  const string BatchNudge =270      "First privately list what you need next; then request every item "271      + "that doesn't depend on another's result in this one response.";272273  // In-memory files stand in for a working directory so the sample runs anywhere.274  Dictionary<string, string> files = new()275  {276      ["pyproject.toml"] = """277          [project]278          name = "demo"279          version = "0.1.0"280          description = "Demo project for the batching example"281          """,282      ["README.md"] = """283          # demo284285          A small demo project. Run `demo --help` for usage.286          """,287  };288289  List<BetaToolUnion> tools =290  [291      new BetaTool292      {293          Name = "read_file",294          Description = "Read a UTF-8 text file from the working directory.",295          InputSchema = new InputSchema296          {297              Properties = new Dictionary<string, JsonElement>298              {299                  ["path"] = JsonSerializer.SerializeToElement(new { type = "string" }),300              },301              Required = ["path"],302          },303      },304  ];305306  List<BetaMessageParam> messages =307  [308      new() { Role = Role.User, Content = "Summarize pyproject.toml and README.md." },309  ];310311  BetaMessage response;312  while (true)313  {314      response = await client.Beta.Messages.Create(new MessageCreateParams315      {316          Model = "claude-fable-5-1",317          MaxTokens = 16000,318          Betas = ["mid-conversation-system-clear-at-2026-08-21"],319          Tools = tools,320          Messages = messages,321      });322      // Append the assistant turn exactly as returned, thinking blocks included.323      messages.Add(new()324      {325          Role = Role.Assistant,326          Content = response.Content.Select(block => new BetaContentBlockParam(block.Json)).ToList(),327      });328      if (response.StopReason != BetaStopReason.ToolUse)329      {330          break;331      }332      List<BetaContentBlockParam> toolResults = [];333      foreach (var block in response.Content)334      {335          if (block.TryPickToolUse(out var toolUse))336          {337              var path = toolUse.Input.TryGetValue("path", out var pathValue)338                  && pathValue.ValueKind == JsonValueKind.String339                  ? pathValue.GetString()!340                  : "";341              if (files.TryGetValue(path, out var fileText))342              {343                  toolResults.Add(new BetaToolResultBlockParam { ToolUseID = toolUse.ID, Content = fileText });344              }345              else346              {347                  toolResults.Add(new BetaToolResultBlockParam348                  {349                      ToolUseID = toolUse.ID,350                      Content = $"File not found: {path}",351                      IsError = true,352                  });353              }354          }355      }356      // Send the tool results as the user turn, then a fresh copy of the nudge as a357      // turn-scoped system message. Leave earlier copies in place: the API clears them,358      // so the model sees only the newest one.359      messages.Add(new() { Role = Role.User, Content = toolResults });360      messages.Add(new()361      {362          Role = Role.System,363          Content = BatchNudge,364          ClearAt = ClearAt.NextUserMessage,365      });366  }367368  foreach (var block in response.Content)369  {370      if (block.TryPickText(out var text))371      {372          Console.WriteLine(text.Text);373          break;374      }375  }376  ```377378  ```go Go379  package main380381  import (382  	"context"383  	"encoding/json"384  	"fmt"385  	"log"386387  	"github.com/anthropics/anthropic-sdk-go"388  )389390  const batchNudge = "First privately list what you need next; then request every item " +391  	"that doesn't depend on another's result in this one response."392393  // In-memory files stand in for a working directory so the sample runs anywhere.394  var files = map[string]string{395  	"pyproject.toml": `[project]396  name = "demo"397  version = "0.1.0"398  description = "Demo project for the batching example"399  `,400  	"README.md": `# demo401402  A small demo project. Run "demo --help" for usage.403  `,404  }405406  func main() {407  	client := anthropic.NewClient()408  	ctx := context.Background()409410  	tools := []anthropic.BetaToolUnionParam{411  		{OfTool: &anthropic.BetaToolParam{412  			Name:        "read_file",413  			Description: anthropic.String("Read a UTF-8 text file from the working directory."),414  			InputSchema: anthropic.BetaToolInputSchemaParam{415  				Properties: map[string]any{416  					"path": map[string]any{"type": "string"},417  				},418  				Required: []string{"path"},419  			},420  		}},421  	}422  	messages := []anthropic.BetaMessageParam{423  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Summarize pyproject.toml and README.md.")),424  	}425426  	var response *anthropic.BetaMessage427  	for {428  		var err error429  		response, err = client.Beta.Messages.New(ctx, anthropic.BetaMessageNewParams{430  			Model:     "claude-fable-5-1",431  			MaxTokens: 16000,432  			Betas:     []anthropic.AnthropicBeta{"mid-conversation-system-clear-at-2026-08-21"},433  			Tools:     tools,434  			Messages:  messages,435  		})436  		if err != nil {437  			log.Fatal(err)438  		}439  		// Append the assistant turn exactly as returned, thinking blocks included.440  		messages = append(messages, response.ToParam())441  		if response.StopReason != anthropic.BetaStopReasonToolUse {442  			break443  		}444  		var toolResults []anthropic.BetaContentBlockParamUnion445  		for _, block := range response.Content {446  			toolUse, ok := block.AsAny().(anthropic.BetaToolUseBlock)447  			if !ok {448  				continue449  			}450  			var input struct {451  				Path string `json:"path"`452  			}453  			// A missing or non-string path leaves input.Path empty, which takes the error-result branch.454  			if err := json.Unmarshal([]byte(toolUse.JSON.Input.Raw()), &input); err != nil {455  				input.Path = ""456  			}457  			text, found := files[input.Path]458  			if !found {459  				text = "File not found: " + input.Path460  			}461  			toolResults = append(toolResults, anthropic.NewBetaToolResultBlock(toolUse.ID, text, !found))462  		}463  		// Send the tool results as the user turn, then a fresh copy of the nudge as a464  		// turn-scoped system message. Leave earlier copies in place: the API clears them,465  		// so the model sees only the newest one.466  		messages = append(messages, anthropic.NewBetaUserMessage(toolResults...))467  		messages = append(messages, anthropic.BetaMessageParam{468  			Role:    anthropic.BetaMessageParamRoleSystem,469  			Content: []anthropic.BetaContentBlockParamUnion{anthropic.NewBetaTextBlock(batchNudge)},470  			ClearAt: anthropic.BetaMessageParamClearAtNextUserMessage,471  		})472  	}473474  	for _, block := range response.Content {475  		if textBlock, ok := block.AsAny().(anthropic.BetaTextBlock); ok {476  			fmt.Println(textBlock.Text)477  			break478  		}479  	}480  }481  ```482483  ```java Java484  import com.anthropic.client.AnthropicClient;485  import com.anthropic.client.okhttp.AnthropicOkHttpClient;486  import com.anthropic.core.JsonValue;487  import com.anthropic.models.beta.messages.BetaContentBlockParam;488  import com.anthropic.models.beta.messages.BetaMessage;489  import com.anthropic.models.beta.messages.BetaMessageParam;490  import com.anthropic.models.beta.messages.BetaStopReason;491  import com.anthropic.models.beta.messages.BetaTool;492  import com.anthropic.models.beta.messages.BetaTool.InputSchema;493  import com.anthropic.models.beta.messages.BetaToolResultBlockParam;494  import com.anthropic.models.beta.messages.BetaToolUseBlock;495  import com.anthropic.models.beta.messages.MessageCreateParams;496497  static final String BATCH_NUDGE =498      "First privately list what you need next; then request every item "499          + "that doesn't depend on another's result in this one response.";500501  // In-memory files stand in for a working directory so the sample runs anywhere.502  static final Map<String, String> FILES = Map.of(503      "pyproject.toml", """504          [project]505          name = "demo"506          version = "0.1.0"507          description = "Demo project for the batching example"508          """,509      "README.md", """510          # demo511512          A small demo project. Run `demo --help` for usage.513          """);514515  void main() {516      AnthropicClient client = AnthropicOkHttpClient.fromEnv();517518      BetaTool readFileTool = BetaTool.builder()519          .name("read_file")520          .description("Read a UTF-8 text file from the working directory.")521          .inputSchema(InputSchema.builder()522              .properties(JsonValue.from(Map.of("path", Map.of("type", "string"))))523              .required(List.of("path"))524              .build())525          .build();526      List<BetaMessageParam> messages = new ArrayList<>();527      messages.add(BetaMessageParam.builder()528          .role(BetaMessageParam.Role.USER)529          .content("Summarize pyproject.toml and README.md.")530          .build());531532      BetaMessage response;533      while (true) {534          response = client.beta().messages().create(MessageCreateParams.builder()535              .model("claude-fable-5-1")536              .maxTokens(16000)537              .addBeta("mid-conversation-system-clear-at-2026-08-21")538              .addTool(readFileTool)539              .messages(messages)540              .build());541          // Append the assistant turn exactly as returned, thinking blocks included.542          messages.add(response.toParam());543          boolean requestedTools = response.stopReason()544              .map(BetaStopReason.TOOL_USE::equals)545              .orElse(false);546          if (!requestedTools) {547              break;548          }549          List<BetaToolUseBlock> toolUses = response.content().stream()550              .flatMap(block -> block.toolUse().stream())551              .toList();552          List<BetaContentBlockParam> toolResults = new ArrayList<>();553          for (BetaToolUseBlock toolUse : toolUses) {554              Map<String, JsonValue> input =555                  (Map<String, JsonValue>) toolUse._input().asObject().orElseThrow();556              JsonValue pathValue = input.get("path");557              String path = pathValue != null && pathValue.asString().isPresent()558                  ? pathValue.asStringOrThrow()559                  : "";560              String fileText = FILES.get(path);561              BetaToolResultBlockParam.Builder result = BetaToolResultBlockParam.builder()562                  .toolUseId(toolUse.id());563              if (fileText != null) {564                  result.content(fileText);565              } else {566                  result.content("File not found: " + path).isError(true);567              }568              toolResults.add(BetaContentBlockParam.ofToolResult(result.build()));569          }570          // Send the tool results as the user turn, then a fresh copy of the nudge as a571          // turn-scoped system message. Leave earlier copies in place: the API clears them,572          // so the model sees only the newest one.573          messages.add(BetaMessageParam.builder()574              .role(BetaMessageParam.Role.USER)575              .contentOfBetaContentBlockParams(toolResults)576              .build());577          messages.add(BetaMessageParam.builder()578              .role(BetaMessageParam.Role.SYSTEM)579              .content(BATCH_NUDGE)580              .clearAt(BetaMessageParam.ClearAt.NEXT_USER_MESSAGE)581              .build());582      }583584      String finalText = response.content().stream()585          .flatMap(block -> block.text().stream())586          .map(textBlock -> textBlock.text())587          .findFirst()588          .orElse("");589      IO.println(finalText);590  }591  ```592593  ```php PHP594  <?php595596  use Anthropic\Beta\Messages\BetaStopReason;597  use Anthropic\Client;598599  $client = new Client();600601  const BATCH_NUDGE = 'First privately list what you need next; then request every item '602      . "that doesn't depend on another's result in this one response.";603  // In-memory files stand in for a working directory so the sample runs anywhere.604  const FILES = [605      'pyproject.toml' => <<<'TOML'606          [project]607          name = "demo"608          version = "0.1.0"609          description = "Demo project for the batching example"610          TOML,611      'README.md' => <<<'MD'612          # demo613614          A small demo project. Run `demo --help` for usage.615          MD,616  ];617  $tools = [618      [619          'name' => 'read_file',620          'description' => 'Read a UTF-8 text file from the working directory.',621          'input_schema' => [622              'type' => 'object',623              'properties' => ['path' => ['type' => 'string']],624              'required' => ['path'],625          ],626      ],627  ];628  $messages = [629      ['role' => 'user', 'content' => 'Summarize pyproject.toml and README.md.'],630  ];631632  while (true) {633      $response = $client->beta->messages->create(634          model: 'claude-fable-5-1',635          maxTokens: 16000,636          betas: ['mid-conversation-system-clear-at-2026-08-21'],637          tools: $tools,638          messages: $messages,639      );640      // Append the assistant turn exactly as returned, thinking blocks included.641      $messages[] = ['role' => 'assistant', 'content' => $response->content];642      if ($response->stopReason !== BetaStopReason::TOOL_USE->value) {643          break;644      }645      $toolResults = [];646      foreach ($response->content as $block) {647          if ($block->type === 'tool_use') {648              $path = is_string($block->input['path'] ?? null) ? $block->input['path'] : '';649              if (array_key_exists($path, FILES)) {650                  $toolResults[] = [651                      'type' => 'tool_result',652                      'tool_use_id' => $block->id,653                      'content' => FILES[$path],654                  ];655              } else {656                  $toolResults[] = [657                      'type' => 'tool_result',658                      'tool_use_id' => $block->id,659                      'content' => "File not found: {$path}",660                      'is_error' => true,661                  ];662              }663          }664      }665      // Send the tool results as the user turn, then a fresh copy of the nudge as a666      // turn-scoped system message. Leave earlier copies in place: the API clears them,667      // so the model sees only the newest one.668      $messages[] = ['role' => 'user', 'content' => $toolResults];669      $messages[] = [670          'role' => 'system',671          'content' => BATCH_NUDGE,672          'clear_at' => 'next_user_message',673      ];674  }675676  $textBlock = array_find($response->content, fn ($block) => $block->type === 'text');677  echo $textBlock?->text ?? '', PHP_EOL;678  ```679680  ```ruby Ruby681  require "anthropic"682683  client = Anthropic::Client.new684685  BATCH_NUDGE =686    "First privately list what you need next; then request every item " \687    "that doesn't depend on another's result in this one response."688  # In-memory files stand in for a working directory so the sample runs anywhere.689  FILES = {690    "pyproject.toml" => <<~TOML,691      [project]692      name = "demo"693      version = "0.1.0"694      description = "Demo project for the batching example"695    TOML696    "README.md" => <<~MD697      # demo698699      A small demo project. Run `demo --help` for usage.700    MD701  }702  tools = [703    {704      name: "read_file",705      description: "Read a UTF-8 text file from the working directory.",706      input_schema: {707        type: "object",708        properties: {path: {type: "string"}},709        required: ["path"]710      }711    }712  ]713  messages = [{role: "user", content: "Summarize pyproject.toml and README.md."}]714715  response = nil716  loop do717    response = client.beta.messages.create(718      model: "claude-fable-5-1",719      max_tokens: 16000,720      betas: ["mid-conversation-system-clear-at-2026-08-21"],721      tools: tools,722      messages: messages723    )724    # Append the assistant turn exactly as returned, thinking blocks included.725    messages << {role: "assistant", content: response.content}726    break unless response.stop_reason == :tool_use727728    tool_results = response.content.filter_map do |block|729      next unless block.type == :tool_use730731      path = block.input[:path]732      if FILES.key?(path)733        {type: "tool_result", tool_use_id: block.id, content: FILES[path]}734      else735        {736          type: "tool_result",737          tool_use_id: block.id,738          content: "File not found: #{path}",739          is_error: true740        }741      end742    end743    # Send the tool results as the user turn, then a fresh copy of the nudge as a744    # turn-scoped system message. Leave earlier copies in place: the API clears them,745    # so the model sees only the newest one.746    messages << {role: "user", content: tool_results}747    messages << {role: "system", content: BATCH_NUDGE, clear_at: "next_user_message"}748  end749750  puts response.content.find { it.type == :text }&.text751  ```752</CodeGroup>753754## Keep the conversation history append-only755756Append each assistant turn to the history exactly as the API returned it, thinking blocks included, and don't edit earlier turns between requests. For new accounts created on or after August 31, 2026, Claude Fable 5.1's thinking blocks are valid [only in the exact conversation that produced them](https://platform.claude.com/docs/en/build-with-claude/thinking#preserved-in-conversation): a request that replays a thinking block after its prefix (the system prompt, the tool list, or any earlier message) has changed returns a 400, or drops the affected blocks if you set `thinking.block_binding.prefix_mismatch_behavior: "drop_block"` (beta, `thinking-binding-controls-2026-08-01` header). Future models are expected to enforce this check for all accounts, so adopt the pattern now even if yours isn't enforced today.757758The history edits that trip the check are the same ones that restart the [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching): injecting and removing per-turn reminders, summarizing older turns in place, or changing the system prompt mid-session. Send per-turn reminders as [turn-scoped system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#turn-scoped-system-messages), change instructions or tools with a [mid-conversation system message](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages) instead of rewriting `system` or `tools`, and let server-side [compaction](https://platform.claude.com/docs/en/build-with-claude/compaction) or [context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing) do any trimming. If you compact on the client, the simplest shape is to replace the whole history with one summary message plus the new user turn and replay nothing else: no thinking blocks carry over, so nothing fails, and the model thinks afresh on the compacted conversation (see [Custom compaction on the client](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#custom-compaction-on-the-client)). Because cache reads are now cheaper (see [Pricing](https://platform.claude.com/docs/en/models/fable-5-1/whats-new-fable-5-1#pricing)), compacting early to save cost may no longer be the right cost-intelligence tradeoff on Claude Fable 5.1, so experiment with later compaction points.759760To find edits your harness already makes, run a session with `prefix_mismatch_behavior: "drop_block"` and log `input_transformations`, as described in [How to tell whether your integration is impacted](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#how-to-tell-whether-your-integration-is-impacted), or capture the exact requests it sends over a few normal turns and confirm that consecutive requests are byte-identical up to the appended turns.761762## Writing density763764Claude Fable 5.1's writing is generally a step up from earlier Claude models, with fewer stock phrases and less unexplained jargon. In some cases, though, its prose is denser than Claude Fable 5's: sentences run longer and there are fewer paragraph breaks. An instruction that defines the anti-pattern, mannered prose, helps. Add it to a user message (preferred) or the system prompt:765766```text wrap767Mannered prose substitutes metaphor and flourish for direct statement. Instead of "a parameter worth varying," the mannered writer produces "a dial worth turning." Instead of "this point still matters," they write "this point earns its keep." The phrases exist to display the writer, not to convey the idea, and readers can tell. That is why mannered prose irritates: it makes the reader work harder so the writer can perform. It is also imprecise. Metaphors drag in connotations the writer did not choose and cannot control. The fix is to say what you mean. When a literal phrase is available, use it.768```769770The short version also tends to work:771772```text wrap773Please remove all mannered prose.774```775776## Formatting in chat777778Earlier models overused bullets and bold in chat, and many prompts carry anti-formatting rules written to hold that down. Claude Fable 5.1 leans the other way: it uses bold less and is less likely to reach for headers, lists, or quotation marks. If your prompt contains anti-formatting language, remove it or replace it with a rule that says when specific formatting is appropriate, such as the following:779780```text wrap781Use lists and bullet points when asked to, or when the content is multifaceted enough that they help with clarity. If the person explicitly requests minimal formatting, always format your responses without bullet points, headers, lists, or bold emphasis, as requested. In conversational, personal, or emotional exchanges, keep to plain prose.782```783784## Quoting retrieved sources785786When summarizing documents, Claude Fable 5.1 is more likely than Claude Fable 5 to reproduce passages of the source text without marking them as quotations. To address this, add one complete example of a correct response to the system prompt: the user's request, the response, and a sentence explaining why the response is correct.787788```text wrap789<example>790<user>look up how the Riverton Ledger and the Coast Dispatch each covered the Harbor Bridge closure and compare their reporting</user>791<response>792[web_search: Harbor Bridge closure Riverton Ledger]793[web_search: Harbor Bridge closure Coast Dispatch]794Both outlets agree on the basics: the bridge closed on March 3 after inspectors found cracked welds, and the state expects repairs to take about eight months. Where they differ is emphasis. The Ledger treats it as a local-economy story. The Dispatch frames it as a funding failure; its editorial calls the closure "entirely foreseeable." Read together, the Ledger explains who is affected now and the Dispatch explains how it came to this — neither account alone gives the whole picture.795</response>796<rationale>CORRECT: The response is organized around where the two outlets agree and differ, not as a walk through either article. Each outlet's reporting is conveyed in one or two sentences of the assistant's own indirect speech. One short marked phrase from one source; every other claim is reworded. The response is still specific and complete.</rationale>797</example>798```799800Replace the two `[web_search: ...]` lines with your own tool's name, so the model reads them as templated tool output rather than literal text to emit.801802## Finish the whole task803804Claude Fable 5.1 can execute very long tasks without much guidance on methodology, especially when the goal is clear. On complex asynchronous workloads, though, nudge it not to end its turn before the work is done. Without the nudge, the model sometimes describes what it would do next instead of doing it ("Next, I'll …") or stops to ask permission for a step the original request already covered ("Shall I apply this?"). Users have to reply "continue" or "go ahead," which suits pair programming and other human-in-the-loop work but doesn't use the model's full long-horizon capability.805806Two system prompt additions together mitigate this. Apply both. If you need to limit prompt length, use only the first, which keeps most of the effect. The first tells the model not to ask about work already requested and to carry out the next steps it has stated:807808```text wrap809You are operating autonomously. The user is not watching in real time and cannot answer questions mid-task, so asking 'Want me to…?' or 'Shall I…?' will block the work. For reversible actions that follow from the original request, proceed without asking. Stop only for destructive actions or genuine scope changes the user must decide. Offering follow-ups after the task is done is fine; asking permission before doing the work is not.810811Exception: when the user is describing a problem, asking a question, or thinking out loud rather than requesting a change, the deliverable is your assessment. Report your findings and stop. Don't apply a fix until they ask for one.812813Before ending your turn, check your last paragraph. If it is a plan, an analysis, a question, a list of next steps, or a promise about work you have not done ('I'll…', 'let me know when…'), do that work now with tool calls. That includes retrying after errors and gathering missing information yourself. Do not stop because the context or session is long. End your turn only when the task is complete or you are blocked on input only the user can provide.814815Before running a command that changes system state (such as restarts, deletes, or config edits), check that the evidence actually supports that specific action. A signal that pattern-matches to a known failure may have a different cause.816```817818The opening sentence, which tells the model the user isn't watching, carries much of the effect. Keep it as written. If your product needs the model to stop for specific confirmations, add a sentence after it listing them. This block can also make the model less likely to ask about ambiguous requests, so check that trade-off on your own tasks.819820The second defines the user's request as the scope of the deliverable:821822```text wrap823# Delivering work824The user's request — or the plan they approved — sets the scope, and the scope is the deliverable: don't quietly narrow, widen, or swap it. Read ambiguity the way a careful colleague would: make routine judgment calls yourself, and check in only when different readings would lead to materially different work. If you see a real problem with the task as specified, say so in a sentence or two and keep building under stated assumptions; if the user hears the concern and reaffirms, that is their decision, so deliver the full request.825826If a question comes up partway, first do everything that doesn't depend on the answer; then state the assumption you made, or — when going ahead on a wrong guess would be unsafe or would make the work useless — put the question at the end of a turn that also delivers that progress. If one part turns out to be blocked, complete every other part in full and say exactly what you left out and why — the whole task is the deliverable, and scaling it down is the user's call, not yours. A step you have decided on is something to run, not to announce: describing the next step and ending the turn leaves it undone until the user replies.827828Keep changes to what the request needs. Something else you notice worth doing — cleanup or documentation the task didn't call for, a change to a file the task didn't require — is a suggestion to make at the end, not a change to make; actions clearly beyond what the ask implies, and risky or destructive ones, still need the user's go-ahead.829```830831## Tell the model what to preserve in compaction summaries832833Claude Fable 5.1 responds well to being told explicitly what its summary must retain when a long conversation is compacted. Server-side [compaction](https://platform.claude.com/docs/en/build-with-claude/compaction) already does this. If you compact on the client side, use the following summarization instruction:834835```text wrap836Summarize the transcript inside <summary></summary> tags. Include relevant information in the summary such that this conversation will be continued by a new context window without needing to redo work or be reprovided with relevant constraints or context. Be sure to preserve: (1) any difficulties or problems that came up, and how they were handled or resolved; (2) any possibilities, options, or approaches that were raised, tried, or set aside, and why; (3) anything that was asked for, decided, agreed, ruled out, or established as a preference, constraint, or boundary — stated exactly; (4) exactly where things stand now — what has been covered, settled, or completed so far; (5) anything still open, unresolved, promised, or expected to happen next; (6) specific details that would be hard to reconstruct — names, numbers, dates, exact wording, links or references — kept exactly. Be complete on these even at the cost of length; keep everything else concise. Weight the two voices differently: keep what the user said, asked for, shared, or established carefully and close to their own words; your own explanations and reasoning can be condensed much further, to what they concluded or produced — as long as nothing in the six items above is dropped.837```838839## Keep changes and tests to what the task asks for840841When asked to implement an open-ended feature, Claude Fable 5.1 delivers what's asked for and sometimes more: it may fix nearby code, extend behavior the task didn't mention, or commit more test files than the change warrants. It responds well to explicit instructions about what to leave out. With the following instruction, unrequested additions and committed test code drop substantially with no measurable change in task success:842843```text wrap844If, while working or testing, you find a pre-existing bug, a performance concern, or behavior the task doesn't mention, don't fix, optimize or extend it in this change unless the requested behavior cannot work without it; report it as a follow-up in your summary. Where the task is ambiguous, implement the reading its wording and the surrounding code most directly support, state that assumption in your summary, and don't build for the other readings as well. Verify your work however you like; scratch scripts and quick checks need not be kept. Commit tests only where the task asks for them or this repository already keeps tests for this kind of change, sized like the neighboring test files — roughly one focused test per stated behavior — and don't turn scratch checks into additional permanent test files. This is about extras only: implement every behavior the task asks for, completely.845```846847## Search triggering at low effort848849At `low` effort, Claude Fable 5.1 is less likely than Claude Fable 5 to call a search or retrieval tool, and more likely to answer from memory. In some cases the simplest fix is to raise effort for the affected turns rather than the whole conversation. See [Change effort mid-conversation](https://platform.claude.com/docs/en/build-with-claude/effort#changing-effort-mid-conversation).850851In other cases, a prompt nudge toward verification helps. In the system prompt, say that recognizing a name isn't the same as knowing its current state, and that such names should be searched as the user wrote them:852853```text wrap854When a query centers on a name you do not confidently recognize, or recognize from a fast-moving area like AI models and developer tools where the landscape shifts within months, the name itself is the thing to verify: search before answering, and include the name as the user wrote it in at least one query alongside any reformulations. This holds even when you have some background on it — partial background is exactly what makes an out-of-date answer sound authoritative, so familiarity is not a reason to skip the search.855```856857## Reduce safeguard false positives858859Claude Fable 5.1's safety classifiers produce fewer false positives than Claude Fable 5's did at launch, and finding vulnerabilities in source code is permitted. False positives still occur, and a blocked request returns `stop_reason: "refusal"` (see [Refusals, fallback, and billing](https://platform.claude.com/docs/en/models/fable-5-1/whats-new-fable-5-1#refusals-fallback-and-billing)). Three situations make them more likely:860861* **Compile-check phrasing:** Instead of "Does this program compile without errors?", ask "Are there any bugs in this program?"862* **Lesser-known programming languages:** Give the model context about what the language is and how it works, for example by giving it access to the language's documentation.863* **Base64 in tool output:** Tools that return base64-encoded data into the model's context can trigger false positives, so removing them is the recommended fix.864865## Prefer targeted edits over whole-file rewrites866867If Claude Fable 5.1 rewrites whole files for small changes, append the following instruction to the system prompt or the first user message. Claude Fable 5.1 is more likely than Claude Fable 5 to rewrite an entire text file rather than make a targeted edit. The resulting file is usually the same, but unless the file is short or most of it is changing, a rewrite costs more output tokens and time. The instruction brings Claude Fable 5.1 back in line with Claude Fable 5 for small and medium changes.868869```text wrap870The number of tokens used to edit files is best minimized, all else being equal. Therefore, when it will not affect the end result, try to surgically edit a file rather than rewrite the entire thing.871```872873## Leave room for long outputs at xhigh and max effort874875At `xhigh` and especially `max` effort, Claude Fable 5.1 can think for longer before it starts writing its reply. When a single request asks for a long deliverable, such as a full rewrite of a long document, it may draft much of that deliverable in its thinking and then write it out again as the reply, which means a longer wait and more output tokens. The simplest approach is to run requests like these at `high`, the recommended starting point, and move to `xhigh` or `max` only where you've measured a quality gain (see [Consider all effort levels](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#consider-all-effort-levels)). If you do run them at `xhigh` or `max`:876877* Set `max_tokens` to leave room for the thinking and the reply, not just the reply length you expect.878* Append the following note to the end of the user message. It makes the thinking much shorter on prose and code requests. Replace `[max_tokens]` with the request's actual `max_tokens` value, for example 64,000.879880```text wrap881Everything produced in one reply, including any reasoning or drafting done before the reply, counts toward a single limit of about [max_tokens] tokens. If that limit is reached before the reply is finished, the person receives a cut-off response and has to start over. Composing an entire output or deliverable in full as reasoning and then again as a reply would double the length of the turn without improving the result, so don't do that.882883Instead, when the person has asked for a long or effort-intensive deliverable such as a multi-section document, a large table or dataset, or a complete code file, spend extra effort on understanding the request, checking the inputs the answer depends on, settling the structure and other difficult decisions, and otherwise using the reasoning space to reason and the output space to write an output. Usually it is not needed to draft an output multiple times.884```885886## Let the lead agent keep working while subagents run887888If your coding agent lets Claude Fable 5.1 delegate work to subagents, don't force the lead agent to stop and wait for each one. On coding tasks, letting the lead continue while subagents run lowers average time to completion at similar quality, token usage, and cost. To set this up:889890* Have the tool that starts a subagent return immediately.891* Pass each subagent's result back to the lead in a later `user` message once it's ready.892* Give the lead a separate tool it can call when it wants to wait for a result.893894The model still often chooses to wait. The time savings come from the runs where it carries on with other work.895896## Give vision work tools to crop and zoom897898Claude Fable 5.1 has better vision capabilities out of the box, and on complex visual inputs such as dense charts it does its best work when it can iteratively analyze, crop, and visually verify what it sees. To get the full benefit, run the model as an agent with access to a container that holds the raw images or videos and has basic image-processing libraries (such as PIL and OpenCV) pre-installed. If running a container is too much overhead, an image-cropping tool alone delivers most of the uplift: a tool that returns a chosen region of the image, cropped and enlarged, lets the model examine specific details in more depth and scales test-time compute with image tokens. The [crop tool recipe](https://platform.claude.com/cookbook/multimodal-crop-tool) has a working definition.899
Files main
Menu

Theme