Home Docs Claude Developer Platform

One capture · api

One read of Claude Developer Platformapi-20261027T185806Z

260 pages moved out of 821 read.

Pages moved 260 significant first

Pages read 821 in this capture

Captured 27 Oct 2026 18:58 UTC

Corpus hash 23cb04cc4921 corpus-hash

What this read moved

1-25 of 260, page 1 of 11

This capture is too large to show at once. Changes 1-25 of 260 are below, significant first; the rest are on the following screens.

about-claude/api-credits-for-subscribers Changed · +19 / -19 lines

from line 4

44description: Claim the monthly Claude Platform credits included with Claude Max and Team plans, and learn what they cover.

55---

7Claude Max and Team plans include monthly credits for the Claude API. To claim them, you link a [Claude Console](https://platform.claude.com/) organization to your plan. Credits then arrive in that organization each billing cycle (or monthly for annual plans), and you can use them to build and run your own applications and agents. You don't need to add a payment method to Claude Platform.

7Claude Max and Team plans include monthly credits for the Claude API. To claim them, you link a [Claude Console](https://platform.claude.com/) organization to your plan. Credits then arrive in that organization each billing cycle (or monthly for annual plans), and you can use them to build and run your own applications and agents. You don’t need to add a payment method to Claude Platform.

99<Note>

10 Claude Platform on AWS, Amazon Bedrock, Google Cloud, and Microsoft Foundry: These credits apply only to the Claude API in the Claude Console. They can't be used on other platforms.

10 Claude Platform on AWS, Amazon Bedrock, Google Cloud, and Microsoft Foundry: These credits apply only to the Claude API in the Claude Console. They can’t be used on other platforms.

1111</Note>

1212

1313## Summary

from line 17

1717| **Eligible plans** | Max 5x, Max 20x, and Team, including discounted Team plans |

1818| **Monthly amount** | $100 USD (Max 5x), $200 USD (Max 20x), up to $500 USD (Team, pooled\*) |

1919| **Covers** | Claude API, Claude Managed Agents, the Claude Agent SDK, and playground |

20| **Doesn't cover** | Claude Code, extra usage in the Claude apps |

20| **Doesn’t cover** | Claude Code, extra usage in the Claude apps |

2121| **Refresh** | Each billing cycle (or monthly for annual plans) |

2222| **Expiry** | End of each billing cycle (or monthly for annual plans), with no rollover |

2323| **Payment method for Claude Platform** | Not required |

from line 32

3232| Team, Premium seat | $100 USD per seat\* |

3333| Discounted Team plans (Nonprofit, Scientists) | Same as Team: $20 USD per Standard seat, $100 USD per Premium seat\* |

3434

35\*On Team plans, credits for all seats are pooled into one monthly balance, capped at $500 USD. Each monthly credit, including the first, is based on the seats on your plan at the start of that billing month. For example, a team with three Standard seats and two Premium seats receives $260 USD a month. Adding another Premium seat raises the next month's credit to $360 USD.

3636

3737## Eligibility

3838

from line 39

3939* Your eligible plan must be active and in good standing.

4040* New subscribers can claim credits after 7 days on an eligible plan.

4141* Plans purchased through Claude for iOS or Claude for Android are eligible. Claim your credits on [claude.ai](https://claude.ai) in a web browser.

42* Free, Pro, and Enterprise plans aren't eligible.

42* Free, Pro, and Enterprise plans aren’t eligible.

4343

4444## Claim your credits

4545

from line 52

5252| **Claude plan** | Max: the subscriber<br />Team: Primary Owner, Owner |

5353| **Claude Console organization** | Owner, Admin, or Billing |

5454

55If you don't have a Claude Console organization, create one in the Console at [platform.claude.com](https://platform.claude.com/) first, or create one during the claim flow.

55If you don’t have a Claude Console organization, create one in the Console at [platform.claude.com](https://platform.claude.com/) first, or create one during the claim flow.

5656

5757### Steps

5858

from line 71

7171</Steps>

7272

7373<Warning>

74 Each plan links to one Console organization, and each Console organization can receive credits from one plan. You can't change the linked organization yourself, so link the organization you plan to build in. To change it later, [contact support](https://support.claude.com/en/articles/9015913-how-to-get-support).

74 Each plan links to one Console organization, and each Console organization can receive credits from one plan. You can’t change the linked organization yourself, so link the organization you plan to build in. To change it later, [contact support](https://support.claude.com/en/articles/9015913-how-to-get-support).

7575</Warning>

7676

77Subscribers who aren't eligible don't see API credits in their settings page. If you think you should be eligible but don't see the API credits, [contact support](https://support.claude.com/en/articles/9015913-how-to-get-support).

77Subscribers who aren’t eligible don’t see API credits in their settings page. If you think you should be eligible but don’t see the API credits, [contact support](https://support.claude.com/en/articles/9015913-how-to-get-support).

7878

7979## What the credits cover

8080

from line 93

9393## How credits are applied

9494

9595* **Timing.** Credits arrive each billing cycle, shortly after your plan payment is processed. On annual plans, credits arrive monthly.

96* **Order.** Included credits are spent first, then any credits you've purchased. Auto-reload is based only on your purchased balance. It reloads when that balance reaches your threshold, even if included credits remain.

97* **Expiry.** Unused credits expire at the end of each billing cycle (or monthly for annual plans) and don't roll over.

98* **Sharing.** Every API key and workspace in the linked organization draws from the same balance. To cap spending on a project, give it its own workspace and set that workspace's [spend limit](https://platform.claude.com/docs/en/manage-claude/workspaces#setting-workspace-limits).

96* **Order.** Included credits are spent first, then any credits you’ve purchased. Auto-reload is based only on your purchased balance. It reloads when that balance reaches your threshold, even if included credits remain.

97* **Expiry.** Unused credits expire at the end of each billing cycle (or monthly for annual plans) and don’t roll over.

98* **Sharing.** Every API key and workspace in the linked organization draws from the same balance. To cap spending on a project, give it its own workspace and set that workspace’s [spend limit](https://platform.claude.com/docs/en/manage-claude/workspaces#setting-workspace-limits).

9999* **Visibility.** Your credits appear in the **Promotional credits** section of the [Billing](https://platform.claude.com/settings/billing) page (`platform.claude.com/settings/billing`) in the Console, with the amount and expiry date.

100* **Your Claude plan.** Credits don't change your usage limits in Claude or Claude Code.

100* **Your Claude plan.** Credits don’t change your usage limits in Claude or Claude Code.

101101

102102## Spend limits and rate limits

103103

104Credits don't change how [rate limits and spend limits](https://platform.claude.com/docs/en/api/rate-limits) work:

104Credits don’t change how [rate limits and spend limits](https://platform.claude.com/docs/en/api/rate-limits) work:

105105

106* Usage paid with credits counts toward your organization's [monthly spend cap](https://platform.claude.com/docs/en/api/rate-limits#spend-limits). Spend caps reset on the first of each calendar month, whereas credits refresh on your billing cycle (or monthly for annual plans).

106* Usage paid with credits counts toward your organization’s [monthly spend cap](https://platform.claude.com/docs/en/api/rate-limits#spend-limits). Spend caps reset on the first of each calendar month, whereas credits refresh on your billing cycle (or monthly for annual plans).

107107* Organizations linked to an eligible plan move up to at least the Start tier. If their monthly credits are over $200 USD, they move up to at least the Build tier.

108* Claiming credits doesn't otherwise change your [usage tier](https://platform.claude.com/docs/en/api/rate-limits#about-rate-limits), and these credits don't count toward moving to a higher tier.

108* Claiming credits doesn’t otherwise change your [usage tier](https://platform.claude.com/docs/en/api/rate-limits#about-rate-limits), and these credits don’t count toward moving to a higher tier.

109109

110110### When credits run out

111111

112* **If the organization has other credits**, requests continue using purchased credits. Auto-reload, if it's turned on, adds credits to the purchased balance.

112* **If the organization has other credits**, requests continue using purchased credits. Auto-reload, if it’s turned on, adds credits to the purchased balance.

113113* **If the organization has no credits left**, API requests stop until your next monthly API credits arrive. Usage is never charged to your Claude plan. To keep building, purchase credits or turn on auto-reload on the [Billing](https://platform.claude.com/settings/billing) page (`platform.claude.com/settings/billing`) in the Console.

114114* **If your organization is invoiced through Anthropic sales**, usage beyond the API credits is billed as usual.

115115

from line 119

119119Your credit balance is too low to access the Anthropic API. Please go to Plans & Billing to upgrade or purchase credits.

120120```

121121

122If an organization holds only these credits and sends a request they don't cover, such as a Claude Code session, Claude Code displays:

122If an organization holds only these credits and sends a request they don’t cover, such as a Claude Code session, Claude Code displays:

123123

124124```text wrap

125125Credit balance too low · Add funds: https://platform.claude.com/settings/billing

from line 132

132132| Cancel, downgrade to an ineligible plan, or refund | New credits stop when your plan ends. Credits you already have stay usable until they expire. |

133133| Upgrade from Max 5x to Max 20x | You receive prorated API credits right away, then $200 USD each billing cycle. If you subscribe through Google Play, the $200 USD credit arrives later, by your next renewal at the latest. |

134134| Upgrade from Max to Team | The Max link ends. A Team owner can claim the team's credits after the Team plan has been active for 7 days. |

135| Add or remove Team seats | Seats added to your plan count from the next billing month's credit. Seats you remove stay on your plan until it renews, so the credit might be lower after that. The pool stays capped at $500 USD. |

135| Add or remove Team seats | Seats added to your plan count from the next billing month’s credit. Seats you remove stay on your plan until it renews, so the credit might be lower after that. The pool stays capped at $500 USD. |

136136

137137## Use your credits efficiently

138138

from line 140

140140

141141* Choose a model that fits each task. To learn how, see [Choosing the right model](https://platform.claude.com/docs/en/about-claude/models/choosing-a-model).

142142* Use [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for repeated context.

143* Use the [Message Batches API](https://platform.claude.com/docs/en/build-with-claude/batch-processing) for work that doesn't need an immediate response. It costs 50 percent less.

143* Use the [Message Batches API](https://platform.claude.com/docs/en/build-with-claude/batch-processing) for work that doesn’t need an immediate response. It costs 50 percent less.

144144* Check [pricing](https://platform.claude.com/docs/en/about-claude/pricing) and track spend on the [Cost](https://platform.claude.com/cost) page in the Claude Console.

145145

146146## Related

about-claude/glossary Changed · +10 / -10 lines

from line 6

77## Context window

9The "context window" refers to the amount of text a language model can look back on and reference when generating new text. This is different from the large corpus of data the language model was trained on, and instead represents a "working memory" for the model. A larger context window allows the model to process and respond to more complex and lengthy prompts, whereas a smaller context window might limit the model's ability to handle longer prompts or maintain coherence over extended conversations.

9The “context window” refers to the amount of text a language model can look back on and reference when generating new text. This is different from the large corpus of data the language model was trained on, and instead represents a “working memory” for the model. A larger context window allows the model to process and respond to more complex and lengthy prompts, whereas a smaller context window might limit the model’s ability to handle longer prompts or maintain coherence over extended conversations.

1010

1111See the [guide to understanding context windows](https://platform.claude.com/docs/en/build-with-claude/context-windows) to learn more.

1212

1313## Fine-tuning

1414

15Fine-tuning is the process of further training a pretrained language model using additional data. This causes the model to start representing and mimicking the patterns and characteristics of the fine-tuning dataset. Claude is not a bare language model; it has already been fine-tuned to be a helpful assistant. The Claude API does not currently offer fine-tuning, but ask your Anthropic contact if you are interested in exploring this option. Fine-tuning can be useful for adapting a language model to a specific domain, task, or writing style, but it requires careful consideration of the fine-tuning data and the potential impact on the model's performance and biases.

1616

1717## HHH

1818

19HHH (helpful, honest, harmless) is a research framework that informs how Claude is trained to be beneficial to society. It is distinct from the Claude product tagline, "AI assistant for life and work."

19HHH (helpful, honest, harmless) is a research framework that informs how Claude is trained to be beneficial to society. It is distinct from the Claude product tagline, “AI assistant for life and work.”

2020

2121* A **helpful** AI will attempt to perform the task or answer the question posed to the best of its abilities, providing relevant and useful information.

2222* An **honest** AI will give accurate information, and not hallucinate or confabulate. It will acknowledge its limitations and uncertainties when appropriate.

from line 40

4040

4141## Pretraining

4242

43Pretraining is the initial process of training language models on a large unlabeled corpus of text. In Claude's case, autoregressive language models (such as Claude's underlying model) are pretrained to predict the next word, given the previous context of text in the document. These pretrained models are not inherently good at answering questions or following instructions, and often require deep skill in prompt engineering to elicit the behaviors you want. Fine-tuning and RLHF are used to refine these pretrained models, making them more useful for a wide range of tasks.

43Pretraining is the initial process of training language models on a large unlabeled corpus of text. In Claude’s case, autoregressive language models (such as Claude’s underlying model) are pretrained to predict the next word, given the previous context of text in the document. These pretrained models are not inherently good at answering questions or following instructions, and often require deep skill in prompt engineering to elicit the behaviors you want. Fine-tuning and RLHF are used to refine these pretrained models, making them more useful for a wide range of tasks.

4444

4545## RAG (retrieval augmented generation)

4646

47Retrieval augmented generation (RAG) is a technique that combines information retrieval with language model generation to improve the accuracy and relevance of the generated text, and to better ground the model's response in evidence. In RAG, a language model is augmented with an external knowledge base or a set of documents that is passed into the context window. The data is retrieved at runtime when a query is sent to the model, although the model itself does not necessarily retrieve the data (but can with [tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) and a retrieval function). When generating text, relevant information first must be retrieved from the knowledge base based on the input prompt, and then passed to the model along with the original query. The model uses this information to guide the output it generates. This allows the model to access and use information beyond its training data, reducing the reliance on memorization and improving the factual accuracy of the generated text. RAG can be particularly useful for tasks that require up-to-date information, domain-specific knowledge, or explicit citation of sources. However, the effectiveness of RAG depends on the quality and relevance of the external knowledge base and the knowledge that is retrieved at runtime.

47Retrieval augmented generation (RAG) is a technique that combines information retrieval with language model generation to improve the accuracy and relevance of the generated text, and to better ground the model’s response in evidence. In RAG, a language model is augmented with an external knowledge base or a set of documents that is passed into the context window. The data is retrieved at runtime when a query is sent to the model, although the model itself does not necessarily retrieve the data (but can with [tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) and a retrieval function). When generating text, relevant information first must be retrieved from the knowledge base based on the input prompt, and then passed to the model along with the original query. The model uses this information to guide the output it generates. This allows the model to access and use information beyond its training data, reducing the reliance on memorization and improving the factual accuracy of the generated text. RAG can be particularly useful for tasks that require up-to-date information, domain-specific knowledge, or explicit citation of sources. However, the effectiveness of RAG depends on the quality and relevance of the external knowledge base and the knowledge that is retrieved at runtime.

4848

4949## RLHF

5050

51Reinforcement learning from human feedback (RLHF) is a technique used to train a pretrained language model to behave in ways that are consistent with human preferences. This can include helping the model follow instructions more effectively or act more like a chatbot. Human feedback consists of ranking a set of two or more example texts, and the reinforcement learning process encourages the model to prefer outputs that are similar to the higher-ranked ones. Claude has been trained using RLHF to be a more helpful assistant. For more details, you can read Anthropic's [paper on RLHF](https://arxiv.org/abs/2204.05862).

51Reinforcement learning from human feedback (RLHF) is a technique used to train a pretrained language model to behave in ways that are consistent with human preferences. This can include helping the model follow instructions more effectively or act more like a chatbot. Human feedback consists of ranking a set of two or more example texts, and the reinforcement learning process encourages the model to prefer outputs that are similar to the higher-ranked ones. Claude has been trained using RLHF to be a more helpful assistant. For more details, you can read Anthropic’s [paper on RLHF](https://arxiv.org/abs/2204.05862).

5252

5353## Temperature

5454

55Temperature is a parameter that controls the randomness of a model's predictions during text generation. Higher temperatures lead to more creative and diverse outputs, allowing for multiple variations in phrasing and, in the case of fiction, variation in answers as well. Lower temperatures result in more conservative and deterministic outputs that stick to the most probable phrasing and answers. Adjusting the temperature allows users to encourage a language model to explore rare, uncommon, or surprising word choices and sequences, rather than only selecting the most likely predictions.

55Temperature is a parameter that controls the randomness of a model’s predictions during text generation. Higher temperatures lead to more creative and diverse outputs, allowing for multiple variations in phrasing and, in the case of fiction, variation in answers as well. Lower temperatures result in more conservative and deterministic outputs that stick to the most probable phrasing and answers. Adjusting the temperature allows users to encourage a language model to explore rare, uncommon, or surprising word choices and sequences, rather than only selecting the most likely predictions.

5656

57Users might encounter non-determinism in APIs. Even with temperature set to 0, the results will not be fully deterministic, and identical inputs might produce different outputs across API calls. This applies both to Anthropic's first-party inference service and to inference through third-party cloud providers.

57Users might encounter non-determinism in APIs. Even with temperature set to 0, the results will not be fully deterministic, and identical inputs might produce different outputs across API calls. This applies both to Anthropic’s first-party inference service and to inference through third-party cloud providers.

5858

5959## TTFT (time to first token)

6060

61Time to first token (TTFT) is a performance metric that measures the time it takes for a language model to generate the first token of its output after receiving a prompt. It is an important indicator of the model's responsiveness and is particularly relevant for interactive applications, chatbots, and real-time systems where users expect quick initial feedback. A lower TTFT indicates that the model can start generating a response faster, providing a more seamless and engaging user experience. Factors that can influence TTFT include model size, hardware capabilities, network conditions, and the complexity of the prompt.

61Time to first token (TTFT) is a performance metric that measures the time it takes for a language model to generate the first token of its output after receiving a prompt. It is an important indicator of the model’s responsiveness and is particularly relevant for interactive applications, chatbots, and real-time systems where users expect quick initial feedback. A lower TTFT indicates that the model can start generating a response faster, providing a more seamless and engaging user experience. Factors that can influence TTFT include model size, hardware capabilities, network conditions, and the complexity of the prompt.

6262

6363## Tokens

6464

65Tokens are the smallest individual units of a language model, and can correspond to words, subwords, characters, or even bytes (in the case of Unicode). For Claude, the number of characters a token represents depends on the model and the language. Claude 4.7 and later models and Claude Mythos Preview use a newer tokenizer that produces approximately 30 percent more tokens for the same text than earlier models, on which a token represents approximately 3.5 English characters. To get exact counts, use [token counting](https://platform.claude.com/docs/en/build-with-claude/token-counting) with the model you plan to use. Tokens are typically hidden when interacting with language models at the "text" level but become relevant when examining the exact inputs and outputs of a language model. When Claude is provided with text to evaluate, the text (consisting of a series of characters) is encoded into a series of tokens for the model to process. Larger tokens improve data efficiency during inference and pretraining (and are used when possible), whereas smaller tokens allow a model to handle uncommon or never-before-seen words. The choice of tokenization method can impact the model's performance, vocabulary size, and ability to handle out-of-vocabulary words.

65Tokens are the smallest individual units of a language model, and can correspond to words, subwords, characters, or even bytes (in the case of Unicode). For Claude, the number of characters a token represents depends on the model and the language. Claude 4.7 and later models and Claude Mythos Preview use a newer tokenizer that produces approximately 30 percent more tokens for the same text than earlier models, on which a token represents approximately 3.5 English characters. To get exact counts, use [token counting](https://platform.claude.com/docs/en/build-with-claude/token-counting) with the model you plan to use. Tokens are typically hidden when interacting with language models at the “text” level but become relevant when examining the exact inputs and outputs of a language model. When Claude is provided with text to evaluate, the text (consisting of a series of characters) is encoded into a series of tokens for the model to process. Larger tokens improve data efficiency during inference and pretraining (and are used when possible), whereas smaller tokens allow a model to handle uncommon or never-before-seen words. The choice of tokenization method can impact the model’s performance, vocabulary size, and ability to handle out-of-vocabulary words.

6666

about-claude/models/choosing-a-model Changed · +6 / -6 lines

from line 10

1010

1111* **Capabilities:** What specific features or capabilities will you need the model to have to meet your needs?

1212* **Speed:** How quickly does the model need to respond in your application? [Fast mode](https://platform.claude.com/docs/en/build-with-claude/fast-mode) delivers up to 2.5x higher output speed at premium pricing on [supported models](https://platform.claude.com/docs/en/build-with-claude/fast-mode#supported-models).

13* **Cost:** What's your budget for both development and production usage?

13* **Cost:** What’s your budget for both development and production usage?

1414* **Effort:** Several Claude models support an [effort parameter](https://platform.claude.com/docs/en/build-with-claude/effort) that trades intelligence for latency and cost within a single model. Tuning effort is often a better lever than switching models. On Claude Fable 5.1, Claude Opus 5, and Claude Sonnet 5.5, start with the default (`high`) and adjust up or down based on your evals. On Claude Opus 5.5 and Claude Haiku 5.5 the default is `medium`; start there and adjust the same way. On Claude Opus 4.8 and Claude Opus 4.7, the `xhigh` effort level, between `high` and `max`, is the best setting for most coding and agentic use cases.

1515

1616***

from line 55

5555

5656**Claude Opus 5.5** (`claude-opus-5-5`) is built for long-running agentic coding and knowledge work, with [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) always on. If your integration forces tool use (`tool_choice` of type `any` or `tool`), turns thinking off, or uses the `computer_20251124` computer use tool, see [Breaking changes](https://platform.claude.com/docs/en/models/opus-5-5/whats-new-opus-5-5#breaking-changes) before switching.

5757

58**Claude Fable 5.1** (`claude-fable-5-1`) is Anthropic's most capable model open to all customers. It extends Claude Fable 5 with stronger long-running agentic coding, knowledge work, and research at the same input and output prices, with cache reads at a quarter of the cost. **Claude Mythos 5.1** (`claude-mythos-5-1`) offers the same capabilities only to organizations verified through Anthropic's verification programs, such as the [Cyber Verification Program](https://support.claude.com/en/articles/14604842). Both models use always-on [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking). 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 details.

58**Claude Fable 5.1** (`claude-fable-5-1`) is Anthropic’s most capable model open to all customers. It extends Claude Fable 5 with stronger long-running agentic coding, knowledge work, and research at the same input and output prices, with cache reads at a quarter of the cost. **Claude Mythos 5.1** (`claude-mythos-5-1`) offers the same capabilities only to organizations verified through Anthropic’s verification programs, such as the [Cyber Verification Program](https://support.claude.com/en/articles/14604842). Both models use always-on [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking). 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 details.

5959

6060For context windows, output limits, and prices, see the [model comparison table](https://platform.claude.com/docs/en/models/overview#latest-models-comparison).

6161

from line 99

9999 See detailed specifications and pricing for the latest Claude models

100100 </Card>

101101

102 <Card title="What's new in Claude Fable 5.1" icon="sparkle" href="https://platform.claude.com/docs/en/models/fable-5-1/whats-new-fable-5-1">

102 <Card title="What’s new in Claude Fable 5.1" icon="sparkle" href="https://platform.claude.com/docs/en/models/fable-5-1/whats-new-fable-5-1">

103103 Built for demanding reasoning and long-horizon agentic work

104104 </Card>

105105

106 <Card title="What's new in Claude Opus 5.5" icon="sparkle" href="https://platform.claude.com/docs/en/models/opus-5-5/whats-new-opus-5-5">

106 <Card title="What’s new in Claude Opus 5.5" icon="sparkle" href="https://platform.claude.com/docs/en/models/opus-5-5/whats-new-opus-5-5">

107107 The latest Opus model: breaking changes, new features, and behavior differences

108108 </Card>

109109

110 <Card title="What's new in Claude Sonnet 5.5" icon="sparkle" href="https://platform.claude.com/docs/en/models/sonnet-5-5/whats-new-sonnet-5-5">

110 <Card title="What’s new in Claude Sonnet 5.5" icon="sparkle" href="https://platform.claude.com/docs/en/models/sonnet-5-5/whats-new-sonnet-5-5">

111111 The latest Sonnet model: breaking changes, new features, and behavior differences

112112 </Card>

113113

114 <Card title="What's new in Claude Haiku 5.5" icon="sparkle" href="https://platform.claude.com/docs/en/models/haiku-5-5/whats-new-haiku-5-5">

114 <Card title="What’s new in Claude Haiku 5.5" icon="sparkle" href="https://platform.claude.com/docs/en/models/haiku-5-5/whats-new-haiku-5-5">

115115 The latest Haiku model: breaking changes, new features, and behavior differences

116116 </Card>

117117

about-claude/models/optimizing-for-cost-and-intelligence Changed · +186 / -186 lines

from line 17

1717* **Free wins** cut spend without touching quality: prompt caching, token hygiene, a prompt audit against the model you are running, [batch processing](https://platform.claude.com/docs/en/build-with-claude/batch-processing) at 50% off for work that can wait up to 24 hours, and [workspace spend limits](https://platform.claude.com/docs/en/api/rate-limits#setting-lower-limits-for-workspaces) as the backstop.

1818* **Tradeoffs** exchange cost for intelligence: model choice, effort, output caps and session budgets, an elapsed-time clock, and multi-model architectures.

1919

20Each lever comes with measured results and the rule for when it pays. In Anthropic's measurements, prompt caching was usually the largest lever. The multi-model levers are narrower; a second model was measured in two shapes, an advisor and an orchestrator.

20Each lever comes with measured results and the rule for when it pays. In Anthropic’s measurements, prompt caching was usually the largest lever. The multi-model levers are narrower; a second model was measured in two shapes, an advisor and an orchestrator.

2121

2222## Start here

2323

from line 28

2828| Any workload, any model | Turn on prompt caching and trim unneeded tokens; both are free | [Cache repeated context](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#cache-repeated-context) · [Trim tokens](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#trim-input-and-context-tokens) |

2929| A person waits between turns | Count the gaps between your requests, then pick the cache duration from the table in that section | [Pick the cache duration](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#pick-the-cache-duration) |

3030| Costs are too high; quality is fine | Try lower effort on the model you use now | [Tune effort](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#tune-effort) |

31| You are not on the latest model | Upgrade; in Anthropic's measurements each newer model solved at least as many tasks as the one before it, usually for less per solved task | [Upgrade the model](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#upgrade-the-model) |

31| You are not on the latest model | Upgrade; in Anthropic’s measurements each newer model solved at least as many tasks as the one before it, usually for less per solved task | [Upgrade the model](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#upgrade-the-model) |

3232| You are choosing or switching models | Compare on cost per completed task, not per token | [Compare models](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#compare-models-on-cost-per-task) |

3333| High-volume work with outputs you can check | Try Claude Haiku 5.5 first | [Compare models](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#compare-models-on-cost-per-task) |

34| Quality isn't good enough | If you lowered effort, restore it; otherwise try the next tier up at its default effort | [Tune effort](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#tune-effort) · [Compare models](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#compare-models-on-cost-per-task) |

35| Attempts end with `stop_reason: max_tokens` | Raise `max_tokens` to 64,000: in Anthropic's tests only 2 of about 14,000 turns were longer, and cost per solved task stayed about the same | [Set budgets](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#set-budgets-and-output-caps) |

36| You can check outputs (tests, a verifier) | Run at `low` effort and re-run failures at `high`: in Anthropic's tests, about 40% lower cost than everything at `high`, at the same pass rate | [Re-run failures](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#re-run-failures-at-higher-effort) |

34| Quality isn’t good enough | If you lowered effort, restore it; otherwise try the next tier up at its default effort | [Tune effort](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#tune-effort) · [Compare models](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#compare-models-on-cost-per-task) |

35| Attempts end with `stop_reason: max_tokens` | Raise `max_tokens` to 64,000: in Anthropic’s tests only 2 of about 14,000 turns were longer, and cost per solved task stayed about the same | [Set budgets](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#set-budgets-and-output-caps) |

36| You can check outputs (tests, a verifier) | Run at `low` effort and re-run failures at `high`: in Anthropic’s tests, about 40% lower cost than everything at `high`, at the same pass rate | [Re-run failures](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#re-run-failures-at-higher-effort) |

3737| Agent loops with a few very costly runs | Set a Claude Managed Agents session budget and a workspace spend limit | [Set budgets](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#set-budgets-and-output-caps) |

38| You want agent runs to finish sooner | Tell the model time matters and show it the elapsed time: 7% to 47% less time in Anthropic's tests, for a few points of score | [Show the model elapsed time](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#show-the-model-elapsed-time) |

38| You want agent runs to finish sooner | Tell the model time matters and show it the elapsed time: 7% to 47% less time in Anthropic’s tests, for a few points of score | [Show the model elapsed time](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#show-the-model-elapsed-time) |

3939| A lower-cost model stalls only on hard decisions | Try an advisor. It can help only when your model consults it; first price its model alone at low effort and measure the consult rate | [Advisor strategy](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#advisor-strategy-escalate-hard-decisions) |

4040| The work exceeds one context window | Split the work and hand the parts to lower-cost models | [Orchestrator strategy](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#orchestrator-strategy-delegate-bulk-work) |

4141

from line 67

6767 ![Chart, DeepResearch Bench II: caching cuts Fable 5.1 from $37.94 USD to $6.89 USD per task; Sonnet 5, $3.20 USD to $1.18 USD](https://platform.claude.com/docs/images/cost-intel/caching-repriced.svg)

6868</Frame>

6969

70The cache's default lifetime is 5 minutes and an agent loop's turns are seconds apart, so the discount applies to most tokens on every turn. The caching chart's runs read 84% to 90% of their input tokens from the cache.

70The cache’s default lifetime is 5 minutes and an agent loop’s turns are seconds apart, so the discount applies to most tokens on every turn. The caching chart’s runs read 84% to 90% of their input tokens from the cache.

7171

72Pricing other runs' recorded token counts the same way, each model at its default effort, gives the average token cost per task without caching:

72Pricing other runs’ recorded token counts the same way, each model at its default effort, gives the average token cost per task without caching:

7373

7474| Benchmark | Model | Without caching |

7575| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ------------------------------- |

from line 83

8383<Note>

8484 With Claude Haiku 5.5 on the Messages API, [compact a long conversation](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#manage-the-context-lifecycle) between tasks, before its prompt passes 100,000 tokens. Past that, every token of the request costs 5 times as much, output included. Cache reads and writes count toward the 100,000 (see [Long context pricing](https://platform.claude.com/docs/en/about-claude/pricing#long-context-pricing)).

8585

86 If you use [compaction at a token threshold](https://platform.claude.com/docs/en/build-with-claude/compaction-threshold#parameters) instead, set its `trigger` a little below 100,000 minus your prompt's largest growth between requests (the default is 150,000). In Anthropic's test with 10,000-token turns, a trigger of 90,000 cost 70% less per request than the default[18](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs).

86 If you use [compaction at a token threshold](https://platform.claude.com/docs/en/build-with-claude/compaction-threshold#parameters) instead, set its `trigger` a little below 100,000 minus your prompt’s largest growth between requests (the default is 150,000). In Anthropic’s test with 10,000-token turns, a trigger of 90,000 cost 70% less per request than the default[18](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs).

8787</Note>

8888

8989#### Pick the cache duration

from line 92

9292

9393The 1-hour duration costs more to write (2x the input price instead of 1.25x). A miss on either duration bills the whole prefix at the write price instead of the read price.

9494

95Choose the cache duration when a conversation starts. In Anthropic's test, the first turn added at 1 hour to a conversation cached at 5 minutes wrote the whole prompt again, once: $0.80 USD at 100,000 tokens on Claude Opus 5.5, compared with $0.02 USD of input for a turn that read the cache[16](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs).

95Choose the cache duration when a conversation starts. In Anthropic’s test, the first turn added at 1 hour to a conversation cached at 5 minutes wrote the whole prompt again, once: $0.80 USD at 100,000 tokens on Claude Opus 5.5, compared with $0.02 USD of input for a turn that read the cache[16](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs).

9696

97Anthropic measured a small agent that triages bug reports ([Trim input and context tokens](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#trim-input-and-context-tokens)) with pauses inserted before some turns to simulate a person's delay[16](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs). Accuracy stayed within run-to-run noise at every setting measured. Anthropic also measured extra requests that keep the 5-minute cache warm (keep-alive requests).

97Anthropic measured a small agent that triages bug reports ([Trim input and context tokens](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#trim-input-and-context-tokens)) with pauses inserted before some turns to simulate a person’s delay[16](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs). Accuracy stayed within run-to-run noise at every setting measured. Anthropic also measured extra requests that keep the 5-minute cache warm (keep-alive requests).

9898

9999To decide, count the gaps between consecutive requests in a conversation, and find your row in the following table:

100100

from line 108

108108| Pauses run for minutes | Claude Fable 5.1 | 5-minute cache kept warm, instead of the 1-hour duration |

109109| Pauses run toward an hour | Claude Fable 5.1 | 1-hour duration |

110110

111On Claude Haiku 5.5, use the "Any" rows: it reads the cache at the standard 0.1x the input price, twice the 0.05x of Claude Opus 5.5 and Claude Sonnet 5.5, so by list prices each keep-alive request costs twice as much relative to the input price. A `max_tokens: 0` request refreshed its cache in a separate test (reference 16).

111On Claude Haiku 5.5, use the “Any” rows: it reads the cache at the standard 0.1x the input price, twice the 0.05x of Claude Opus 5.5 and Claude Sonnet 5.5, so by list prices each keep-alive request costs twice as much relative to the input price. A `max_tokens: 0` request refreshed its cache in a separate test (reference 16).

112112

113113**Why, row by row.**

114114

from line 149

149149To keep the cache warm:

150150

1511511. Take the previous request, set `max_tokens` to 0, and drop `stream` if it was set. Do not change a byte of the prefix.

1522. Re-send the request's headers with its body. Without the original request's `anthropic-beta` header, the beta-gated fields in the replayed body are rejected.

1533. Send it within 4 minutes of the previous request's start, and every 4 minutes after that, until the next turn arrives or the session ends. Count from the request's start, because the [cache's 5-minute lifetime](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#how-prompt-caching-works) runs from there.

1522. Re-send the request’s headers with its body. Without the original request’s `anthropic-beta` header, the beta-gated fields in the replayed body are rejected.

1533. Send it within 4 minutes of the previous request’s start, and every 4 minutes after that, until the next turn arrives or the session ends. Count from the request’s start, because the [cache’s 5-minute lifetime](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#how-prompt-caching-works) runs from there.

154154

155That is the [pre-warming request](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pre-warming-the-cache): it refreshes the cache's lifetime, returns no output, and costs little more than the cache read. Once the cache has expired, the next request, keep-alive or not, re-writes the prefix at the cache write price[16](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs).

155That is the [pre-warming request](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pre-warming-the-cache): it refreshes the cache’s lifetime, returns no output, and costs little more than the cache read. Once the cache has expired, the next request, keep-alive or not, re-writes the prefix at the cache write price[16](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs).

156156

157157A `max_tokens: 0` request is rejected in the following cases:

158158

159159* The request sets `thinking.type: "enabled"` (the default adaptive thinking on Claude Fable 5.1 is fine), structured outputs, or a forced tool choice ([its limitations](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#limitations)). On those workloads, buy the 1-hour duration instead.

160* The request carries the top-level `compaction` parameter, so don't re-send a compaction request from [compaction on demand](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand) as a keep-alive request.

160* The request carries the top-level `compaction` parameter, so don’t re-send a compaction request from [compaction on demand](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand) as a keep-alive request.

161161

162162<CodeGroup exclude="shell:CLI, python, typescript, csharp, go, java, php, ruby">

163163 ```bash cURL

from line 190

190190

191191Keep per-request text in the newest user turn, after the last cache breakpoint, and make every cache-invalidating change at a natural break, such as the first request after a compaction. The cache is a byte-exact prefix match over the request in order (tools, then system prompt, then messages), so a change anywhere invalidates everything after it.

192192

193When something must change mid-conversation, send it in the form that keeps the cache, where the model supports it. In Anthropic's test on Claude Fable 5.1, Claude Opus 5.5, and Claude Sonnet 5.5, on a cached conversation of about 100,000 tokens, editing the system prompt cost about 25 to 50 times what the same text cost as a mid-conversation system message. Changing effort at the top level cost 20 to 40 times what it cost per message[18](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs):

193When something must change mid-conversation, send it in the form that keeps the cache, where the model supports it. In Anthropic’s test on Claude Fable 5.1, Claude Opus 5.5, and Claude Sonnet 5.5, on a cached conversation of about 100,000 tokens, editing the system prompt cost about 25 to 50 times what the same text cost as a mid-conversation system message. Changing effort at the top level cost 20 to 40 times what it cost per message[18](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs):

194194

195195<Frame>

196196 ![Bar chart: system prompt edit up to $1.26 USD, top-level effort change up to $1.02 USD, either in a message up to $0.026 USD](https://platform.claude.com/docs/images/cost-intel/cache-break-cost.svg)

197197</Frame>

198198

199At list prices, the stakes are highest on Claude Fable 5.1 and Claude Mythos 5.1, where a break re-writes the prefix at 1.25x the input price instead of reading it at 0.025x. On Claude Haiku 5.5 a system prompt edit costs 12.5 times an unchanged request. The edit re-wrote the whole conversation. By default, newer accounts get a 400 error instead, except on Claude Mythos 5.1[18](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs). The top-level effort change, in a conversation that held the model's first reply with its thinking, re-wrote all but the system prompt. These figures are from the Messages API.

199At list prices, the stakes are highest on Claude Fable 5.1 and Claude Mythos 5.1, where a break re-writes the prefix at 1.25x the input price instead of reading it at 0.025x. On Claude Haiku 5.5 a system prompt edit costs 12.5 times an unchanged request. The edit re-wrote the whole conversation. By default, newer accounts get a 400 error instead, except on Claude Mythos 5.1[18](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs). The top-level effort change, in a conversation that held the model’s first reply with its thinking, re-wrote all but the system prompt. These figures are from the Messages API.

200200

201201**What to do.**

202202

203* Put nothing that changes per request, such as a timestamp or a queue position, ahead of the stable prefix: it turns every request into a full cache write. In Anthropic's test, a 25-token status line at the front of the system prompt made each request write the whole conversation; moved to the end of the newest user turn, it left the cache read intact[18](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs).

203* Put nothing that changes per request, such as a timestamp or a queue position, ahead of the stable prefix: it turns every request into a full cache write. In Anthropic’s test, a 25-token status line at the front of the system prompt made each request write the whole conversation; moved to the end of the newest user turn, it left the cache read intact[18](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs).

204204* The [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#what-invalidates-the-cache) page lists the changes that invalidate the cache, such as a change to [`effort`](https://platform.claude.com/docs/en/build-with-claude/effort), the thinking configuration, the [`speed`](https://platform.claude.com/docs/en/build-with-claude/fast-mode) setting, the system prompt, or a tool definition. Changing the output format invalidates the cache for that conversation (see [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs#prompt-modification-and-token-costs)).

205205* Check which models support each form: [mid-conversation system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages), and [per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort#changing-effort-mid-conversation), which is in beta.

206206* After a cache-invalidating change, confirm cache reads have not dropped; if they have, [cache diagnostics](https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics) shows where the prefix diverged.

207207

208On an earlier model, Anthropic measured when to make such a change, on the triage agent's long sessions[18](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs). An effort change and an added tool cost more mid-session, or on the request that triggered the compaction, than on the first request after compaction. Accuracy was within run-to-run noise. The sessions with no changes cost more than those changed after compaction for another reason: they ran at the default effort throughout, and two of them compacted a second time, while the others started at low effort:

208On an earlier model, Anthropic measured when to make such a change, on the triage agent’s long sessions[18](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs). An effort change and an added tool cost more mid-session, or on the request that triggered the compaction, than on the first request after compaction. Accuracy was within run-to-run noise. The sessions with no changes cost more than those changed after compaction for another reason: they ran at the default effort throughout, and two of them compacted a second time, while the others started at low effort:

209209

210210<Frame>

211211 ![Bar chart, cost per triage session: $0.81 USD no changes, $0.95 USD mid-session, $0.92 USD at compaction, $0.75 USD after](https://platform.claude.com/docs/images/cost-intel/compaction-timing.svg)

from line 243

243243* With tool search, the run cost stayed flat at every catalog size.

244244* Accuracy was in the same range either way, and the model never called a wrong tool, so at this scale unused definitions cost money, not correctness.

245245* [Keep your 3 to 5 most used tools loaded](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool#deferred-tool-loading), so Claude can call them without searching first.

246* On the same earlier model, deferring a public GitHub MCP server's toolset (`default_config: {defer_loading: true}` on the [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector)) cut the run cost at the same accuracy. With no tool search tool in the request, no run then called the server's tools.

246* On the same earlier model, deferring a public GitHub MCP server’s toolset (`default_config: {defer_loading: true}` on the [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector)) cut the run cost at the same accuracy. With no tool search tool in the request, no run then called the server’s tools.

247247

248248#### Keep data files out of the prompt

249249

from line 272

272272* Run-wide, the prune and context editing cache about equally well. If you use context editing, [clear in a few large batches](https://platform.claude.com/docs/en/build-with-claude/context-editing#context-editing-and-prompt-caching).

273273

274274<Note>

275 On Claude Fable 5.1, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5, rewriting an earlier tool result [invalidates every thinking block after it](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#prefix-check), so use compaction instead. The prune was measured on an earlier model without [preserved thinking](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking); on these four models, [context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing) and [compaction](https://platform.claude.com/docs/en/build-with-claude/compaction) run on the server and don't invalidate thinking blocks. [Send assistant turns back exactly as returned](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#append-assistant-turns-exactly-as-returned): dropping their thinking blocks costs output tokens on every turn, because Claude [re-creates the reasoning](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#drop-block-cost).

275 On Claude Fable 5.1, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5, rewriting an earlier tool result [invalidates every thinking block after it](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#prefix-check), so use compaction instead. The prune was measured on an earlier model without [preserved thinking](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking); on these four models, [context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing) and [compaction](https://platform.claude.com/docs/en/build-with-claude/compaction) run on the server and don’t invalidate thinking blocks. [Send assistant turns back exactly as returned](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#append-assistant-turns-exactly-as-returned): dropping their thinking blocks costs output tokens on every turn, because Claude [re-creates the reasoning](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#drop-block-cost).

276276</Note>

277277

278The prune, adapted from the triage agent's code:

278The prune, adapted from the triage agent’s code:

279279

280280```python

281281import re

from line 319

319319Audit prompts against the model you run now, and again whenever you change models: it is a free win.

320320

321321* Each model generation responds to prompts differently, so a prompt accumulates text written for a model you no longer use.

322* The usual case is over-specific instruction added to compensate for an older model: "verify twice," "be maximally thorough," a mandatory step-by-step procedure, or a hand-rolled reasoning scratchpad.

322* The usual case is over-specific instruction added to compensate for an older model: “verify twice,” “be maximally thorough,” a mandatory step-by-step procedure, or a hand-rolled reasoning scratchpad.

323323* A newer model follows such instructions to the letter, producing extra tool rounds and extra writing that you pay for with no gain in accuracy.

324324

325The audit is one command. The [Claude API skill](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/claude-api-skill) that ships with Claude Code has a `prompt-audit` command that reads a project's prompts and request code and reports what was written for a different model:

325The audit is one command. The [Claude API skill](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/claude-api-skill) that ships with Claude Code has a `prompt-audit` command that reads a project’s prompts and request code and reports what was written for a different model:

326326

327327Let Claude Code audit your prompts for you

328328

from line 375

375375 ![Bar charts per legacy pattern: over-obeyed instructions cost money; broken settings and contradictory rules cost accuracy](https://platform.claude.com/docs/images/cost-intel/prompt-audit-patterns.svg)

376376</Frame>

377377

378* Instructions the new model follows too literally cost money: removing "verify twice" cut Claude Opus 5's cost per ticket, and removing "be maximally thorough" cut it almost as much.

379* Text that no longer fits the model costs accuracy instead: a retired thinking setting, contradictory rules, and a hand-rolled scratchpad that conflicts with the model's own thinking each restored accuracy on Claude Opus 5 when removed.

378* Instructions the new model follows too literally cost money: removing “verify twice” cut Claude Opus 5’s cost per ticket, and removing “be maximally thorough” cut it almost as much.

379* Text that no longer fits the model costs accuracy instead: a retired thinking setting, contradictory rules, and a hand-rolled scratchpad that conflicts with the model’s own thinking each restored accuracy on Claude Opus 5 when removed.

380380

381381The same patterns tend to appear in tool descriptions and skills, which are worth auditing too.

382382

from line 404

407| GPQA Diamond[9](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs) | Claude Haiku 5.5 | `medium` (default) | 85% accuracy, compared with 91% for each of Claude Opus 5.5 and Claude Sonnet 5.5 | About a twentieth of Claude Opus 5.5's cost per correct answer and about a tenth of Claude Sonnet 5.5's |

407| GPQA Diamond[9](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs) | Claude Haiku 5.5 | `medium` (default) | 85% accuracy, compared with 91% for each of Claude Opus 5.5 and Claude Sonnet 5.5 | About a twentieth of Claude Opus 5.5’s cost per correct answer and about a tenth of Claude Sonnet 5.5’s |

409409

410410**What to do.**

from line 411

411411

412412* Start with Claude Opus 5.5 at its default effort: on the SWE-bench Pro subset it matched Claude Fable 5.1 at its default, inside run-to-run noise, for about a fifth of the cost per solved task. Opus 5.5 and Fable 5.1 both largely saturate the SWE-bench Pro subset. Use Claude Fable 5.1 for demanding reasoning and long-horizon agentic work, or when your evals on Claude Opus 5.5 at higher effort still fall short.

413413* At the other end, Claude Haiku 5.5 suits high-volume and latency-sensitive work with checkable outputs.

414* Price every candidate in cost per completed task on your own traffic, including Claude Opus 5.5 at its default effort and the frontier model at reduced effort. Each of Claude Opus 5.5's token prices, cache reads included, is twice Claude Sonnet 5.5's, but on the SWE-bench Pro subset Opus 5.5 at `low` solved about the same share of tasks as Sonnet 5.5 at its default, inside run-to-run noise, for about 7% more per solved task.

414* Price every candidate in cost per completed task on your own traffic, including Claude Opus 5.5 at its default effort and the frontier model at reduced effort. Each of Claude Opus 5.5’s token prices, cache reads included, is twice Claude Sonnet 5.5’s, but on the SWE-bench Pro subset Opus 5.5 at `low` solved about the same share of tasks as Sonnet 5.5 at its default, inside run-to-run noise, for about 7% more per solved task.

415415* The ranking flips by workload, and no price list tells you which way, so measure it on your own workload. On long research loops, Claude Fable 5.1 can do more work, not less, and so cost more per task (DeepResearch Bench II[7](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs)).

416416* Price the tail of your workload, not the median: compare models on the hardest tenth of your tasks, not the typical one.

417417

from line 425

425425

426426### Upgrade the model

427427

428If you are a model or two behind, the cheapest lever is the model string. In Anthropic's measurements, each newer model solved at least as many tasks as the one before it, usually for less per solved task. The chart plots recent Claude models on two benchmarks in which an agent works alone on one written task and tests check the result: the SWE-bench Pro[3](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs) subset, where every model ran through the same test setup, and Terminal-Bench 3[20](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs). The table lists what each upgrade changed:

428If you are a model or two behind, the cheapest lever is the model string. In Anthropic’s measurements, each newer model solved at least as many tasks as the one before it, usually for less per solved task. The chart plots recent Claude models on two benchmarks in which an agent works alone on one written task and tests check the result: the SWE-bench Pro[3](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs) subset, where every model ran through the same test setup, and Terminal-Bench 3[20](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs). The table lists what each upgrade changed:

429429

430430<Frame>

431431 ![Charts: on SWE-bench Pro, Opus 5.5 and Sonnet 5.5 cut cost per solved task most; on Terminal-Bench 3, Opus drops to $28 USD](https://platform.claude.com/docs/images/cost-intel/upgrade-ladder-sonnet-5-5.svg)

from line 434

435435| ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | --------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |

440440| DeepResearch Bench II[7](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs) | Claude Fable 5 to Claude Fable 5.1 | `high` | 2 to 3 more points on the 21 tasks where no attempt was cut short | 46% more per task on all 50 tasks |

from line 455

455455

456456Sweep effort on your own workload before you add a second model. Lower effort costs less and is often faster, and how much accuracy it gives up depends on the task: on long-horizon coding, effort bought accuracy, and on research tasks it bought a lot in one measurement and nothing in another. The [`effort`](https://platform.claude.com/docs/en/build-with-claude/effort) parameter governs how much thinking, tool calling, and self-verification the model does; `high` is the default on most models, and `medium` on Claude Opus 5.5 and Claude Haiku 5.5.

457457

458The following table lists Anthropic's measurements on two benchmarks with current models; scores and costs are not comparable between the two benchmarks. Costs are per task, not per solved task as in [Compare models on cost per task](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#compare-models-on-cost-per-task). Each score pools two runs on SWE-bench Pro and three on DeepResearch Bench II, unless its cell says otherwise:

458The following table lists Anthropic’s measurements on two benchmarks with current models; scores and costs are not comparable between the two benchmarks. Costs are per task, not per solved task as in [Compare models on cost per task](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#compare-models-on-cost-per-task). Each score pools two runs on SWE-bench Pro and three on DeepResearch Bench II, unless its cell says otherwise:

459459

461461| --------------------------------------------------------------------------------------------------------------------------- | ---------------- | ------------------ | ------------------------------------ | ------------- |

from line 482

482482

483483* Sweep two or three effort levels on a sample of your own traffic, each in a separate session: changing top-level effort mid-session [invalidates the cache](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#cache-repeated-context) and distorts the comparison. The curve is the baseline any multi-model strategy must beat ([step 2 of measuring on your own workload](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#measure-on-your-own-workload)).

484484* On long-horizon coding, effort is a real tradeoff, which [re-running failures at higher effort](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#re-run-failures-at-higher-effort) turns back into a saving. At `medium`, Claude Sonnet 5.5 scored about 7 points lower than at its default, `high`, on the SWE-bench Pro[3](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs) subset for about 59% of the cost per task (2 runs each), and scored 62.7% compared with 77.8% on the internal agentic-coding benchmark[11](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs) (1 attempt per task).

485* At `xhigh` and `max`, Claude Sonnet 5.5 can start its own rounds of review after it finishes a task, which takes more time and tokens. To keep that work on the task, add the prompt under "Thoroughness at `xhigh` and `max` effort" in [Prompting Claude Sonnet 5.5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5#steer-initiative-and-scope) to your system prompt.

485* At `xhigh` and `max`, Claude Sonnet 5.5 can start its own rounds of review after it finishes a task, which takes more time and tokens. To keep that work on the task, add the prompt under “Thoroughness at `xhigh` and `max` effort” in [Prompting Claude Sonnet 5.5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5#steer-initiative-and-scope) to your system prompt.

486486* On research tasks, measure the model you ship. Claude Fable 5.1 scored nearly the same from `low` to `high` on DeepResearch Bench II; Claude Opus 5.5 scored 13.3 points lower at `low` than at `medium` on DRACO[21](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs). The two results come from different models on different benchmarks, so they show that the answer varies, not why.

487* At `low`, Claude Opus 5.5's typical task took 84% less time than at `medium` on DRACO[21](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs), 30% less on HLE[22](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs), and 47% less on an internal set of physics problems[23](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs), and it scored 13.3, 3.4, and 14.0 points lower (3, 3, and 4 attempts per task).

487* At `low`, Claude Opus 5.5’s typical task took 84% less time than at `medium` on DRACO[21](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs), 30% less on HLE[22](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs), and 47% less on an internal set of physics problems[23](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs), and it scored 13.3, 3.4, and 14.0 points lower (3, 3, and 4 attempts per task).

488488* On an internal defect-search benchmark for work larger than one context window[8](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs), Claude Fable 5.1 took 15.2, 17.5, and 19.9 hours per run at `low`, `medium`, and `high` (3 runs each). To save time, also compare lower effort with the two changes in [Show the model elapsed time](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#show-the-model-elapsed-time): `low` effort saved more time, and the changes kept more of the score.

489489

490490### Re-run failures at higher effort

491491

492When a task's outcome is checkable, the cheapest policy on the effort curve is not a fixed setting: run every task at a low setting and re-run only the failures at a higher one.

492When a task’s outcome is checkable, the cheapest policy on the effort curve is not a fixed setting: run every task at a low setting and re-run only the failures at a higher one.

493493

494494Anthropic computed this policy task by task from the Claude Opus 5.5 effort runs on the SWE-bench Pro[3](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs) subset in [Tune effort](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#tune-effort):

495495

from line 508

508508* At `low`, 13% of tasks failed. With those re-run at `high`, the pass rate was slightly higher than with everything at `high`, for a little over half the cost.

509509* Use this policy for the saving, not the lift. Most of the small lift is the second attempt: re-running the failures of one `high` run at `high` scores about the same, for more money.

510510

511Two conditions apply. First, you need a failure signal (here, the benchmark's own tests); a checker that passes bad work lets those failures through. Second, every first-pass failure takes two runs' worth of wall-clock time, so the saving is paid for in latency on the failures.

511Two conditions apply. First, you need a failure signal (here, the benchmark’s own tests); a checker that passes bad work lets those failures through. Second, every first-pass failure takes two runs’ worth of wall-clock time, so the saving is paid for in latency on the failures.

512512

513513### Set budgets and output caps

514514

515515Two controls do two different jobs: a session budget caps what one Claude Managed Agents session can spend, and `max_tokens` caps the length of one response. Set each where it applies, with a [workspace spend limit](https://platform.claude.com/docs/en/api/rate-limits#setting-lower-limits-for-workspaces) as the final backstop.

516516

517* **Session budgets on Claude Managed Agents** are a hard stop on spend. A [session budget](https://platform.claude.com/docs/en/managed-agents/budgets) is a dollar cap on one session's [list cost](https://platform.claude.com/docs/en/managed-agents/budgets#how-list-cost-is-measured), which the platform meters for tokens, web searches, and session running time.

517* **Session budgets on Claude Managed Agents** are a hard stop on spend. A [session budget](https://platform.claude.com/docs/en/managed-agents/budgets) is a dollar cap on one session’s [list cost](https://platform.claude.com/docs/en/managed-agents/budgets#how-list-cost-is-measured), which the platform meters for tokens, web searches, and session running time.

518518* At the cap, or a fraction past it, the session pauses with `stop_reason: budget_reached`; raising the budget resumes it. It is platform-enforced and works on any model with a list price. Deployments apply the same budget to each session they start.

519519* **`max_tokens`** caps a single response, invisibly to the model, so lowering it does not make the model economize. The turns that needed the room are discarded and still billed. Retrying capped attempts rarely helps: at the same cap most of them fail again, and at a higher one you also pay for the wasted attempt.

520520* Set `max_tokens` to 64,000 for agentic work, or to 128,000, the maximum, when a single cut-off attempt is costly. [Stream responses](https://platform.claude.com/docs/en/build-with-claude/streaming) that large, treat [`stop_reason: max_tokens`](https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons#max-tokens) as a failure, and save money with effort, which the model can see.

from line 559

559559

560560### Show the model elapsed time

561561

562To make an agent finish sooner and cost less, tell it that time matters, and show it the elapsed time on every request. In Anthropic's measurement, the two changes cut the time of a single Claude Opus 5.5 agent at `medium` effort by 47% and its cost by 60% on the typical (median) DRACO[21](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs) research task, and its average score was 4.1 points lower.

562To make an agent finish sooner and cost less, tell it that time matters, and show it the elapsed time on every request. In Anthropic’s measurement, the two changes cut the time of a single Claude Opus 5.5 agent at `medium` effort by 47% and its cost by 60% on the typical (median) DRACO[21](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs) research task, and its average score was 4.1 points lower.

563563

564564On HLE[22](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs) and an internal physics set[23](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs), the typical task took 14% and 7% less time, and the physics score was 3.0 points lower. Lowering effort to `low` saved more time and cost than the changes did, and lost more score (reference 21). Check the score on your own tasks before you adopt the changes.

565565

from line 575

575575

576576## Combine models

577577

578Tune one model before you add a second: sweep effort on your current model first, because most workloads end there, and if the sweep shows a gap, price the stronger model alone at low effort. Build a pairing only if it beats the single model's whole curve of score against spend. The multi-model results on this page were judged against the same model at lower effort and against the next model down running alone, which is the comparison to run on your own workload.

578Tune one model before you add a second: sweep effort on your current model first, because most workloads end there, and if the sweep shows a gap, price the stronger model alone at low effort. Build a pairing only if it beats the single model’s whole curve of score against spend. The multi-model results on this page were judged against the same model at lower effort and against the next model down running alone, which is the comparison to run on your own workload.

579579

580580The following table compares the two strategies:

581581

583583| ---------------- | ----------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |

585585| **Orchestrator** | Frontier model runs the loop, delegates the bulk work | Plans, dispatches, and synthesizes | Work that fans out across genuinely independent files, documents, or cases, especially more than one context window of it | How hard the pieces are to coordinate |

586586

587587### Advisor strategy: escalate hard decisions

from line 588

588588

589589An advisor can help only when the executor consults it.

590590

591In Anthropic's measurements on current models, the one pairing whose executor consulted often, on a coding benchmark, scored 1.7 points higher than the executor alone at the same effort, at the edge of run-to-run noise, for about 2.1 times the cost. Where the executor rarely or never consulted, the pairing scored within run-to-run noise of the executor alone, or lower.

591In Anthropic’s measurements on current models, the one pairing whose executor consulted often, on a coding benchmark, scored 1.7 points higher than the executor alone at the same effort, at the edge of run-to-run noise, for about 2.1 times the cost. Where the executor rarely or never consulted, the pairing scored within run-to-run noise of the executor alone, or lower.

592592

593593To turn it on, add the [advisor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool), a beta feature, to your request. On Claude Managed Agents, [give the session an advisor](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#give-the-session-an-advisor). For Claude Code, see [escalating hard decisions with the advisor tool](https://code.claude.com/docs/en/advisor).

594594

from line 605

605605| Chartography[13](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs) | 61.7, 7 points below the executor alone and beyond run-to-run noise | About the same as the executor alone | On 1 of 300 tasks |

606606

607607* **Internal agentic-coding benchmark.** Claude Opus 5.5 at `high`, with a Claude Fable 5.1 advisor.

608* **GPQA Diamond.** Claude Haiku 5.5 or Claude Sonnet 5.5 at each model's default (`medium` and `high`), with a Claude Opus 5.5 advisor.

608* **GPQA Diamond.** Claude Haiku 5.5 or Claude Sonnet 5.5 at each model’s default (`medium` and `high`), with a Claude Opus 5.5 advisor.

609609* **Chartography.** Claude Opus 5.5 at `low`, with a Claude Fable 5.1 advisor.

610610

611The advisor can only hand over capability the executor lacks: on GPQA Diamond, Claude Sonnet 5.5 alone tied Claude Opus 5.5 alone at 91% with refusals counted as wrong, but only because Opus 5.5 refused six biology questions per run compared with Sonnet 5.5's one. On the questions each answered, Opus 5.5 led by about 2 points.

611The advisor can only hand over capability the executor lacks: on GPQA Diamond, Claude Sonnet 5.5 alone tied Claude Opus 5.5 alone at 91% with refusals counted as wrong, but only because Opus 5.5 refused six biology questions per run compared with Sonnet 5.5’s one. On the questions each answered, Opus 5.5 led by about 2 points.

612612

613On the coding benchmark, the pairing's gain is at the edge of run-to-run noise, and it lands about on Claude Opus 5.5's own effort curve, so the advisor bought about what more effort does. The following chart plots the pairing against that curve and Claude Fable 5.1's from August:

613On the coding benchmark, the pairing’s gain is at the edge of run-to-run noise, and it lands about on Claude Opus 5.5’s own effort curve, so the advisor bought about what more effort does. The following chart plots the pairing against that curve and Claude Fable 5.1’s from August:

614614

615615<Frame>

616616 ![Coding benchmark: Opus 5.5 at high with a Fable 5.1 advisor gains 1.7 points for 2.1 times the cost, near its effort curve](https://platform.claude.com/docs/images/cost-intel/internal-coding-advisor-opus-5-5.svg)

from line 618

618618

619619**What to do.**

620620

621* Measure the consult rate on your own tasks. The advisor tool's definition, about 1,000 prompt tokens per request, adds cost even when the executor never consults. With [prompt caching](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#cache-repeated-context), a multi-turn agent loop pays for the definition at the cache-read price after the first request, so this overhead matters most for short, single-request tasks.

621* Measure the consult rate on your own tasks. The advisor tool’s definition, about 1,000 prompt tokens per request, adds cost even when the executor never consults. With [prompt caching](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#cache-repeated-context), a multi-turn agent loop pays for the definition at the cache-read price after the first request, so this overhead matters most for short, single-request tasks.

622622* If the executor rarely consults, see [Prompting for coding and agent tasks](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#prompting-for-coding-and-agent-tasks) for system prompts that ask for consultations, and measure again after you add one. On 20 SWE-bench Pro[3](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs) problems, the suggested prompt made no clear difference for Claude Sonnet 5.5.

623* Restore the executor's effort if the consult rate collapses. In measurements on earlier models, one pairing that consulted on most tasks at the default effort consulted on few when effort was lowered, and then scored below the executor alone at its default effort (SWE-bench Pro[3](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs)).

623* Restore the executor’s effort if the consult rate collapses. In measurements on earlier models, one pairing that consulted on most tasks at the default effort consulted on few when effort was lowered, and then scored below the executor alone at its default effort (SWE-bench Pro[3](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs)).

624624* Recheck at every model release, because releases move both the capability gap and the price ratio.

625625

626626### Orchestrator strategy: delegate bulk work

from line 630

630630* Routine work with a long cost tail (an easy slice of BrowseComp[4](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs))

631631* Work larger than one context window (an internal defect-search benchmark[8](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs))

632632

633When the work is one dependent chain, or fits in a single context without a long cost tail, the orchestrator's model alone at lower effort came out ahead in every case measured, also on earlier models (the harder BrowseComp set and DeepWideSearch[6](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs)); independent external work reports the same pattern[5](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs).

633When the work is one dependent chain, or fits in a single context without a long cost tail, the orchestrator’s model alone at lower effort came out ahead in every case measured, also on earlier models (the harder BrowseComp set and DeepWideSearch[6](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs)); independent external work reports the same pattern[5](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs).

634634

635635To build an orchestrator, use [multiagent orchestration](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration) in Claude Managed Agents: configure an orchestrator agent and worker agents that it can call, each with its own model.

636636

from line 640

640640

641641The [Model selection matrix](https://platform.claude.com/docs/en/about-claude/models/choosing-a-model#model-selection-matrix) lists Claude Haiku 5.5 for sub-agent tasks; before you use it as a worker, [measure it on your own workload](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#measure-on-your-own-workload).

642642

643The following chart plots the defect-search benchmark's configurations by cost and score:

643The following chart plots the defect-search benchmark’s configurations by cost and score:

644644

645645<Frame>

646646 ![Chart, defect-search benchmark: the orchestrator costs about half of Fable 5.1 alone at any effort and scores 10 to 12 points below](https://platform.claude.com/docs/images/cost-intel/corpus-pareto.svg)

from line 656

656656Measure on your own workload: the numbers on this page reflect list prices at the time of measurement and will drift as models and prices change, and your escalation rate, how cleanly tasks split, and transcript length move them too. The method stays the same:

657657

6586581. Pull a few tasks from production logs, weighted like real traffic, and [write outcome checks](https://platform.claude.com/docs/en/test-and-evaluate/develop-tests) for each: tests pass, ticket closed, row count correct. Record cost per task beside the score.

6592. Baseline the model tiers across effort levels, not only the default, and plot score against spend. A multi-model configuration must beat the single model's whole curve.

6603. If the curve shows a gap effort can't close, add the multi-model strategy that fits and re-run the suite.

6592. Baseline the model tiers across effort levels, not only the default, and plot score against spend. A multi-model configuration must beat the single model’s whole curve.

6603. If the curve shows a gap effort can’t close, add the multi-model strategy that fits and re-run the suite.

6616614. Run the winner in shadow on a traffic slice before cutover, then keep the suite running.

662662

663**How to price a task.** Price each of the five token counts in a response's `usage` at its own rate: uncached input, 5-minute and 1-hour cache writes at 1.25x and 2x the input price, cache reads, and output. Sum them across the task's requests (the [Usage and Cost API](https://platform.claude.com/docs/en/manage-claude/usage-cost-api) reports the aggregate). On Claude Haiku 5.5, use the rates for each request's prompt length, counting cache reads and writes (see [Long context pricing](https://platform.claude.com/docs/en/about-claude/pricing#long-context-pricing)). When `usage.speed` is `"fast"`, use the [fast mode rates](https://platform.claude.com/docs/en/about-claude/pricing#fast-mode-pricing).

663**How to price a task.** Price each of the five token counts in a response’s `usage` at its own rate: uncached input, 5-minute and 1-hour cache writes at 1.25x and 2x the input price, cache reads, and output. Sum them across the task’s requests (the [Usage and Cost API](https://platform.claude.com/docs/en/manage-claude/usage-cost-api) reports the aggregate). On Claude Haiku 5.5, use the rates for each request’s prompt length, counting cache reads and writes (see [Long context pricing](https://platform.claude.com/docs/en/about-claude/pricing#long-context-pricing)). When `usage.speed` is `"fast"`, use the [fast mode rates](https://platform.claude.com/docs/en/about-claude/pricing#fast-mode-pricing).

664664

665The following example computes one request's cost at Claude Opus 5.5's list prices. Change the three prices for another model:

665The following example computes one request’s cost at Claude Opus 5.5’s list prices. Change the three prices for another model:

666666

667667<CodeGroup exclude="shell:cURL, shell:CLI">

668668 <CodeGroupItem language="cURL">

from line 852

852852**What to check.**

853853

854854* **Cache-read share.** In agent loops most input tokens should be cache reads. If `cache_read_input_tokens` is small next to `input_tokens` plus `cache_creation_input_tokens`, check that caching is engaged and that the prefix stays the same between requests.

855* **Advisor tool and compaction.** When the [advisor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#usage-and-billing) or [compaction](https://platform.claude.com/docs/en/build-with-claude/compaction-threshold#understanding-usage) is enabled, some tokens are reported only in `usage.iterations` and not in the top-level totals. Sum over `usage.iterations` instead, and price `advisor_message` entries at the advisor model's rates.

856856

857The following table lists the levers in the order to try them. The figures come from Anthropic's tests, launch posts, and published prices and speeds:

857The following table lists the levers in the order to try them. The figures come from Anthropic’s tests, launch posts, and published prices and speeds:

858858

860860| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

861861| Prompt caching | Cost cut by a factor of 2.7 to 5.5 on a research agent, and by 83% to 86% on a small triage agent | None | Faster | [Cache repeated context](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#cache-repeated-context) |

862862| 1-hour cache duration | With 1 turn in 10 after a pause, the 5-minute default cost 54% more; with 1 in 20, about the same | None | On earlier models, stayed warm after a pause[16](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs) | [Pick the cache duration](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#pick-the-cache-duration) |

863| Input trimming | A further 21% to 26% off a small triage agent's bill | With tool search, accuracy in the same range as without[27](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs) | Neutral | [Trim input and context tokens](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#trim-input-and-context-tokens) |

864| Tool search | 45% with 500 tool definitions attached; 20% from deferring a GitHub MCP server's toolset | None for tools the task never needs | Neutral | [Trim input and context tokens](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#trim-input-and-context-tokens) |

863| Input trimming | A further 21% to 26% off a small triage agent’s bill | With tool search, accuracy in the same range as without[27](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs) | Neutral | [Trim input and context tokens](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#trim-input-and-context-tokens) |

864| Tool search | 45% with 500 tool definitions attached; 20% from deferring a GitHub MCP server’s toolset | None for tools the task never needs | Neutral | [Trim input and context tokens](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#trim-input-and-context-tokens) |

865865| Data files through code execution | 92% on a data task of 25 questions, with prompt caching off | A gain: 25 of 25 correct instead of 7 | Faster | [Trim input and context tokens](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#trim-input-and-context-tokens) |

867867| Prompt audit against the current model | 14% on both model upgrades tested | None; a gain on one | Faster (fewer tool rounds) | [Audit prompts against the current model](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#audit-prompts-against-the-current-model) |

from line 871

872872| Raising `max_tokens` | None: cost per solved task stayed about the same | A gain: up to 22 points more tasks solved on one coding benchmark; none on another | Neutral | [Set budgets and output caps](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#set-budgets-and-output-caps) |

873873| Advisor | None: about 2.1 times the cost of the model alone, on a coding benchmark | On coding, a small gain that may be chance; on chart reading, a loss | About 1.4 extra calls per attempt, on coding | [Advisor strategy](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#advisor-strategy-escalate-hard-decisions) |

874| Orchestrator | About half the cost of the orchestrator's model alone, on work larger than one context window; on routine work, measure first | 10 to 12 points lower on that work | Much faster on that work | [Orchestrator strategy](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#orchestrator-strategy-delegate-bulk-work) |

874| Orchestrator | About half the cost of the orchestrator’s model alone, on work larger than one context window; on routine work, measure first | 10 to 12 points lower on that work | Much faster on that work | [Orchestrator strategy](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#orchestrator-strategy-delegate-bulk-work) |

875875| Fast mode | None: twice the standard token prices | None | Up to 2.5x higher output tokens per second | [Show the model elapsed time](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#show-the-model-elapsed-time) |

876876

877877### Automate the search with the Claude API skill

878878

879Run the [Claude API skill](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/claude-api-skill)'s `cost-optimize` command before you search for savings. It profiles where your tokens go and applies the levers in order, caching first:

879Run the [Claude API skill](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/claude-api-skill)’s `cost-optimize` command before you search for savings. It profiles where your tokens go and applies the levers in order, caching first:

880880

881881Let Claude Code find savings for you

882882

from line 902

902902 ![Scatter chart, tau2-bench retail: each search step from Claude Opus 5; Sonnet 5 at low is 61% cheaper within 2 points](https://platform.claude.com/docs/images/cost-intel/hillclimb.svg)

903903</Frame>

904904

905Two settings determine whether you can trust the search's answer:

905Two settings determine whether you can trust the search’s answer:

906906

907907* **Hold out a split the search never reads.** The search judges adoption there, so confirmation catches a change that fits only the tasks the search saw, as it did the prompt edits (reference 24).

908* **Repeat the baseline before the first change.** Identical runs of one starting configuration differed by several tasks in these measurements (reference 24). The repeats give the search's adoption gate a noise bar.

909909

910910## Benchmarks referenced

911911

912Except where a reference says otherwise, measurements are Anthropic-internal runs of these benchmarks. Unless noted, costs are USD at the list prices in effect when each benchmark ran; Claude Sonnet 5 figures use $2 USD and $10 USD per million input and output tokens. Claude Sonnet 5.5 figures from the September 24, 2026, runs use the same input and output prices and its current cache-read price, $0.10 USD per million tokens, rather than its launch price of $0.20 USD, applied to each run's recorded token counts. Those runs used a pre-release build of Claude Sonnet 5.5, and no attempt in them was answered by a fallback model. Charts labeled "notional USD" price each request's token counts at those rates rather than reporting invoices.

912Except where a reference says otherwise, measurements are Anthropic-internal runs of these benchmarks. Unless noted, costs are USD at the list prices in effect when each benchmark ran; Claude Sonnet 5 figures use $2 USD and $10 USD per million input and output tokens. Claude Sonnet 5.5 figures from the September 24, 2026, runs use the same input and output prices and its current cache-read price, $0.10 USD per million tokens, rather than its launch price of $0.20 USD, applied to each run’s recorded token counts. Those runs used a pre-release build of Claude Sonnet 5.5, and no attempt in them was answered by a fallback model. Charts labeled “notional USD” price each request’s token counts at those rates rather than reporting invoices.

913913

9141. **WideSearch:** Wong et al., "WideSearch: Benchmarking Agentic Broad Info-Seeking," arXiv:2508.07999, 2025. Broad web-research tasks graded on a many-row table's completeness and accuracy; 200 problems, 3 runs per configuration, run August 1 to 2, 2026. With Claude Fable 5 on this benchmark, DeepWideSearch (reference 6), BrowseComp (reference 4), and GDPval (reference 2), `low` effort gave up 1 to 3 points for a third to a half off the cost per task, `medium` matched the default's accuracy at about 70% to 87% of its cost, and the default bought nothing measurable over `medium` on any of the four. The cost-concentration chart is a separate 20-problem run, 3 runs per problem, run August 3 to 4, 2026, costed from per-request billing records. It covers 59 of the 60 runs. The sixtieth, billed $10.91 USD of the $432.31 USD total, has no cost recorded with its result and is not included.

9141. **WideSearch:** Wong et al., “WideSearch: Benchmarking Agentic Broad Info-Seeking,” arXiv:2508.07999, 2025. Broad web-research tasks graded on a many-row table’s completeness and accuracy; 200 problems, 3 runs per configuration, run August 1 to 2, 2026. With Claude Fable 5 on this benchmark, DeepWideSearch (reference 6), BrowseComp (reference 4), and GDPval (reference 2), `low` effort gave up 1 to 3 points for a third to a half off the cost per task, `medium` matched the default’s accuracy at about 70% to 87% of its cost, and the default bought nothing measurable over `medium` on any of the four. The cost-concentration chart is a separate 20-problem run, 3 runs per problem, run August 3 to 4, 2026, costed from per-request billing records. It covers 59 of the 60 runs. The sixtieth, billed $10.91 USD of the $432.31 USD total, has no cost recorded with its result and is not included.

915915

9162. **GDPval:** OpenAI, "GDPval: Evaluating AI Model Performance on Real-World Economically Valuable Tasks," 2025. Knowledge-work deliverables graded against task rubrics; a 210-task run of the released gold set, one attempt per task, run August 2, 2026. A Claude model grades, so absolute scores may differ from published results.

9162. **GDPval:** OpenAI, “GDPval: Evaluating AI Model Performance on Real-World Economically Valuable Tasks,” 2025. Knowledge-work deliverables graded against task rubrics; a 210-task run of the released gold set, one attempt per task, run August 2, 2026. A Claude model grades, so absolute scores may differ from published results.

917917

9183. **SWE-bench Pro:** Scale AI, "SWE-Bench Pro: Can AI Agents Solve Long-Horizon Software Engineering Tasks?", 2025.

9183. **SWE-bench Pro:** Scale AI, “SWE-Bench Pro: Can AI Agents Solve Long-Horizon Software Engineering Tasks?”, 2025.

919919

920 * **What was measured:** A 482-problem subset selected for compatibility with Anthropic's evaluation harness; scores are not comparable to the public leaderboard. They are also not comparable to the SWE-bench Pro results in the Claude Opus 5.5 system card, which come from runs at `max` effort on a different problem set.

921 * **How priced:** Costs on this subset are priced as a customer's organization is metered: each request's prior prompt as a cache read and its new tokens as a 5-minute cache write, from the runs' own usage records, checked against a customer ledger.

920 * **What was measured:** A 482-problem subset selected for compatibility with Anthropic’s evaluation harness; scores are not comparable to the public leaderboard. They are also not comparable to the SWE-bench Pro results in the Claude Opus 5.5 system card, which come from runs at `max` effort on a different problem set.

921 * **How priced:** Costs on this subset are priced as a customer’s organization is metered: each request’s prior prompt as a cache read and its new tokens as a 5-minute cache write, from the runs’ own usage records, checked against a customer ledger.

922922 * **Claude Opus 5.5 runs:** Claude Opus 5.5 figures average two runs at `low`, `medium` (its default), and `high`, and use one run at `xhigh`, all run September 19 to 20, 2026, with the same 16,384-token cap per turn as the August Claude Opus 5 runs; the cap cut off 2 `xhigh` attempts and none at other settings. Measured against `high`, Claude Opus 5.5 scored about 2.5 points lower at its default, `medium`, for about 70% of the cost per task, and about 8 points lower at `low` for about a third of the cost; `xhigh` scored about 1.4 points higher for 2.5 times the cost of `high`. The ratios come from unrounded costs.

923923 * **The 478 problems:** The Opus 5.5 runs used a version of the benchmark whose grading containers can reach only internal package mirrors. That version drops one problem whose test needs a live website, and on three more the reference solution fails there, so Opus 5.5 comparisons, and the Claude Fable 5.1 figures set beside them, use the remaining 478 problems.

924924 * **Claude Sonnet 5.5 runs:** Claude Sonnet 5.5 ran the same version of the benchmark: two runs at its default, `high`, and two at `medium`, all on September 24, 2026, with the same 16,384-token cap per turn, which cut off none of its attempts. Its figures use the 478 problems, and so do the Claude Sonnet 5 figures set beside them, counted over those problems from their August runs.

925925 * **Claude Opus 5 runs:** The Claude Opus 5 SWE-bench Pro figures in [Upgrade the model](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#upgrade-the-model) and in this reference average two runs at its default effort and use one run at `low`, all run August 4, 2026.

926926 * **Advisor, Claude Sonnet 5 pairings:** The Claude Sonnet 5 executor pairings with a Claude Opus 5 advisor behind the consult-rate examples in [Advisor strategy](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#advisor-strategy-escalate-hard-decisions) ran on this subset through the same test setup: the pairing at the default effort was run twice (August 7 and August 8, 2026, a run and an exact replication), the low-effort pairing once (August 8, 2026), and, ten days later, Claude Sonnet 5 alone twice at its default effort (77.4%, the baseline for both pairings).

927 * **Advisor, Claude Sonnet 5.5 consult check:** The Claude Sonnet 5.5 consult check cited in [Advisor strategy](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#advisor-strategy-escalate-hard-decisions) ran one attempt on each of 20 of the 478 problems, on September 24, 2026, with a Claude Opus 5.5 advisor through the advisor tool. Four configurations ran: `high` and `xhigh`, each with and without the advisor tool documentation's suggested system prompt for coding tasks. At its default effort, `high`, Claude Sonnet 5.5 did not consult the advisor on any of the 20 problems, with or without the prompt. At `xhigh`, it consulted on 3 of the 20 problems without the prompt and 4 with it, each time on its attempts with the most turns.

927 * **Advisor, Claude Sonnet 5.5 consult check:** The Claude Sonnet 5.5 consult check cited in [Advisor strategy](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#advisor-strategy-escalate-hard-decisions) ran one attempt on each of 20 of the 478 problems, on September 24, 2026, with a Claude Opus 5.5 advisor through the advisor tool. Four configurations ran: `high` and `xhigh`, each with and without the advisor tool documentation’s suggested system prompt for coding tasks. At its default effort, `high`, Claude Sonnet 5.5 did not consult the advisor on any of the 20 problems, with or without the prompt. At `xhigh`, it consulted on 3 of the 20 problems without the prompt and 4 with it, each time on its attempts with the most turns.

928928 * **Escalation figures:** Escalation figures come task by task from the Opus 5.5 runs: `low` first, then `high` on its failures, solved 96.4% to 97.5% across run pairings for about $0.17 USD; `medium` first, 96.0% to 97.1% for about $0.24 USD; `high` re-run on its own failures, 96.9% for $0.31 USD; everything at `high`, 94.8% to 95.8% for $0.29 USD.

929 * **Compare models:** The Claude Fable 5.1 figure in [Compare models](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#compare-models-on-cost-per-task) comes from one run on the same subset at the default effort, run August 26, 2026: counted over the 478 problems, it solved 92.3% for $1.19 USD per solved task. That section's chart and its Claude Opus 5.5 and Claude Sonnet 5.5 figures pool the two runs at each setting plotted, all counted over the 478 problems: Claude Opus 5.5 at `low`, `medium`, and `high`, and Claude Sonnet 5.5 at `medium` and `high`.

930 * **Compare models, work per task:** In those figures, Claude Opus 5.5 at `low` did less work on each task than Claude Sonnet 5.5 at its default: a little over half of Sonnet 5.5's output tokens and a little over a third of its cache reads. At their defaults, Opus 5.5 at `medium` solved about 5 percentage points more than Sonnet 5.5 for about twice the cost. At that setting it did slightly more work per task than Sonnet 5.5.

931 * **Upgrade the model, runs:** The Claude Fable 5 point in Upgrade the model pools three runs at the default effort, run August 26, 2026, priced as a customer's organization is metered. The upgrade ladder counts every model over the 478 problems, each at its shipped defaults. It uses one run per model except Opus 5, Opus 5.5, Sonnet 5, and Sonnet 5.5 (two runs each) and Fable 5 (the three runs described above). The Opus 4.7, Opus 4.8, Sonnet 4.6, and Sonnet 5 runs ran August 17 to 19, 2026, and the Opus 5 runs on August 4, all in one harness and organization; the Opus 5.5 and Sonnet 5.5 runs are the ones described earlier in this reference.

932 * **Upgrade the model, cost per solved task:** Claude Opus 5 costs 21% more per solved task than Claude Opus 4.8 when those Claude Opus 5 runs are compared with one Claude Opus 4.8 run at its shipped defaults from the August 17 to 19 series, counted over the same 478 problems; the chart's SWE-bench Pro panel shows neither Claude Opus 4.7 nor Claude Opus 4.8. In the same measurements, priced as a customer is billed, Claude Opus 5 solves 12 more points of tasks than Claude Opus 4.8 at that 21% more per solved task, Claude Opus 4.8 solves the same share of tasks as Claude Opus 4.7 for 14% less per solved task, and Claude Opus 5 at `low` effort beats Claude Opus 4.8's default on this benchmark for about 30% of its cost per solved task.

933 * **Upgrade the model, prices:** Claude Sonnet 5's saving over Claude Sonnet 4.6 in Upgrade the model comes from its lower per-token price, which more than offsets the extra tokens it uses per task. Claude Sonnet 5.5 charges the same as Claude Sonnet 5 for everything but cache reads, which cost half as much. Claude Opus 5.5's token prices are lower than Claude Opus 5's, most of all for cache reads. Like Claude Sonnet 5, the frontier tier gained through price: most of Claude Fable 5.1's saving is the lower cache-read price.

929 * **Compare models:** The Claude Fable 5.1 figure in [Compare models](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#compare-models-on-cost-per-task) comes from one run on the same subset at the default effort, run August 26, 2026: counted over the 478 problems, it solved 92.3% for $1.19 USD per solved task. That section’s chart and its Claude Opus 5.5 and Claude Sonnet 5.5 figures pool the two runs at each setting plotted, all counted over the 478 problems: Claude Opus 5.5 at `low`, `medium`, and `high`, and Claude Sonnet 5.5 at `medium` and `high`.

930 * **Compare models, work per task:** In those figures, Claude Opus 5.5 at `low` did less work on each task than Claude Sonnet 5.5 at its default: a little over half of Sonnet 5.5’s output tokens and a little over a third of its cache reads. At their defaults, Opus 5.5 at `medium` solved about 5 percentage points more than Sonnet 5.5 for about twice the cost. At that setting it did slightly more work per task than Sonnet 5.5.

931 * **Upgrade the model, runs:** The Claude Fable 5 point in Upgrade the model pools three runs at the default effort, run August 26, 2026, priced as a customer’s organization is metered. The upgrade ladder counts every model over the 478 problems, each at its shipped defaults. It uses one run per model except Opus 5, Opus 5.5, Sonnet 5, and Sonnet 5.5 (two runs each) and Fable 5 (the three runs described above). The Opus 4.7, Opus 4.8, Sonnet 4.6, and Sonnet 5 runs ran August 17 to 19, 2026, and the Opus 5 runs on August 4, all in one harness and organization; the Opus 5.5 and Sonnet 5.5 runs are the ones described earlier in this reference.

932 * **Upgrade the model, cost per solved task:** Claude Opus 5 costs 21% more per solved task than Claude Opus 4.8 when those Claude Opus 5 runs are compared with one Claude Opus 4.8 run at its shipped defaults from the August 17 to 19 series, counted over the same 478 problems; the chart’s SWE-bench Pro panel shows neither Claude Opus 4.7 nor Claude Opus 4.8. In the same measurements, priced as a customer is billed, Claude Opus 5 solves 12 more points of tasks than Claude Opus 4.8 at that 21% more per solved task, Claude Opus 4.8 solves the same share of tasks as Claude Opus 4.7 for 14% less per solved task, and Claude Opus 5 at `low` effort beats Claude Opus 4.8’s default on this benchmark for about 30% of its cost per solved task.

933 * **Upgrade the model, prices:** Claude Sonnet 5’s saving over Claude Sonnet 4.6 in Upgrade the model comes from its lower per-token price, which more than offsets the extra tokens it uses per task. Claude Sonnet 5.5 charges the same as Claude Sonnet 5 for everything but cache reads, which cost half as much. Claude Opus 5.5’s token prices are lower than Claude Opus 5’s, most of all for cache reads. Like Claude Sonnet 5, the frontier tier gained through price: most of Claude Fable 5.1’s saving is the lower cache-read price.

934934 * **Cost without caching, priced from recorded token counts:** Anthropic re-priced the recorded token counts of the Claude Opus 5.5 and Claude Sonnet 5.5 runs, over the 478 problems, for the caching factors in [Why caching comes first](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#why-caching-comes-first).

935 * **The factors, by model:** Each factor is the token cost with every input token at the input price, output tokens unchanged, divided by the cost priced as a customer's organization is metered: for Claude Opus 5.5, 3.3 at `medium`, 2.4 at `low`, 3.8 at `high`, and 5.4 at `xhigh` (one run); for Claude Sonnet 5.5, with cache reads at $0.10 USD per million tokens, 3.1 at `high` and 2.4 at `medium`, or 2.8 at `high` at the launch price of $0.20 USD. Unlike the caching chart's runs, these incurred no web-search fees, and a task's first request is priced as a cache write.

935 * **The factors, by model:** Each factor is the token cost with every input token at the input price, output tokens unchanged, divided by the cost priced as a customer’s organization is metered: for Claude Opus 5.5, 3.3 at `medium`, 2.4 at `low`, 3.8 at `high`, and 5.4 at `xhigh` (one run); for Claude Sonnet 5.5, with cache reads at $0.10 USD per million tokens, 3.1 at `high` and 2.4 at `medium`, or 2.8 at `high` at the launch price of $0.20 USD. Unlike the caching chart’s runs, these incurred no web-search fees, and a task’s first request is priced as a cache write.

936936

9374. **BrowseComp:** Wei et al., "BrowseComp: A Simple Yet Challenging Benchmark for Browsing Agents," OpenAI, 2025. Effort figures use a 500-problem cut, one to three runs per setting, run August 3, 2026, with the default point pooling two runs from July 26 to 27, 2026. The measurement of routine work with a long cost tail in [Orchestrator strategy](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#orchestrator-strategy-delegate-bulk-work) uses 10 problems that the model reliably solved on its own when the protocol was fixed, from a 26-problem slice, 50 delegated runs (5 per problem; August 1 to 2, 2026) and 70 runs of the model alone (50 from August 2 to 3, 2026; 20 archived from July 12 to 13 and August 1, 2026), $6.45 USD compared with $11.99 USD per run in expectation; delegated figures carry a measurement band of about 20%. The 10 problems are those on which the delegated configuration, a Claude Fable 5 orchestrator with one Claude Sonnet 5 worker, was right in all 5 runs and Claude Fable 5 alone in both archived runs; the delegated runs are those same runs, and only Claude Fable 5 alone was run again on the ten. Over its 70 runs, archived and new, Claude Fable 5 alone was right in 68. On those problems the delegated configuration cost about half as much as Claude Fable 5 alone on average (the $6.45 USD and $11.99 USD given earlier) and about a third as much at the 90th percentile ($12 USD compared with $33 USD per run), and its most expensive run cost $42 USD compared with $84 USD; that $84 USD run was also wrong. On the full, harder BrowseComp set, Claude Fable 5 alone reached the accuracy of the orchestrator configuration measured on that set at 22% to 30% lower cost.

9374. **BrowseComp:** Wei et al., “BrowseComp: A Simple Yet Challenging Benchmark for Browsing Agents,” OpenAI, 2025. Effort figures use a 500-problem cut, one to three runs per setting, run August 3, 2026, with the default point pooling two runs from July 26 to 27, 2026. The measurement of routine work with a long cost tail in [Orchestrator strategy](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#orchestrator-strategy-delegate-bulk-work) uses 10 problems that the model reliably solved on its own when the protocol was fixed, from a 26-problem slice, 50 delegated runs (5 per problem; August 1 to 2, 2026) and 70 runs of the model alone (50 from August 2 to 3, 2026; 20 archived from July 12 to 13 and August 1, 2026), $6.45 USD compared with $11.99 USD per run in expectation; delegated figures carry a measurement band of about 20%. The 10 problems are those on which the delegated configuration, a Claude Fable 5 orchestrator with one Claude Sonnet 5 worker, was right in all 5 runs and Claude Fable 5 alone in both archived runs; the delegated runs are those same runs, and only Claude Fable 5 alone was run again on the ten. Over its 70 runs, archived and new, Claude Fable 5 alone was right in 68. On those problems the delegated configuration cost about half as much as Claude Fable 5 alone on average (the $6.45 USD and $11.99 USD given earlier) and about a third as much at the 90th percentile ($12 USD compared with $33 USD per run), and its most expensive run cost $42 USD compared with $84 USD; that $84 USD run was also wrong. On the full, harder BrowseComp set, Claude Fable 5 alone reached the accuracy of the orchestrator configuration measured on that set at 22% to 30% lower cost.

938938

9395. **Agent-architecture scaling:** Kim et al., "Towards a Science of Scaling Agent Systems," arXiv:2512.08296, 2025. Independent external study, cited only for the direction of the finding on when delegation does not pay, not for any figure.

9395. **Agent-architecture scaling:** Kim et al., “Towards a Science of Scaling Agent Systems,” arXiv:2512.08296, 2025. Independent external study, cited only for the direction of the finding on when delegation does not pay, not for any figure.

940940

9416. **DeepWideSearch:** "DeepWideSearch: Benchmarking Depth and Width in Agentic Information Seeking," arXiv:2510.20168, 2025. The 220 questions span 15 domains, each combining many-row collection with multi-hop retrieval; measured on the benchmark's standing row set, 3 runs per configuration, run August 2, 2026 (the single-worker team point ran July 26 to 27, 2026). With Claude Fable 5, `low` effort matched an orchestrator with a Claude Sonnet 5 worker at 29% lower cost, and took 4.5 minutes per problem, compared with 7.9 minutes at the default.

9416. **DeepWideSearch:** “DeepWideSearch: Benchmarking Depth and Width in Agentic Information Seeking,” arXiv:2510.20168, 2025. The 220 questions span 15 domains, each combining many-row collection with multi-hop retrieval; measured on the benchmark’s standing row set, 3 runs per configuration, run August 2, 2026 (the single-worker team point ran July 26 to 27, 2026). With Claude Fable 5, `low` effort matched an orchestrator with a Claude Sonnet 5 worker at 29% lower cost, and took 4.5 minutes per problem, compared with 7.9 minutes at the default.

942942

9437. **DeepResearch Bench II:** Li et al., "DeepResearch Bench II: Diagnosing Deep Research Agents via Rubrics from Expert Report," arXiv:2601.08536, 2026.

9437. **DeepResearch Bench II:** Li et al., “DeepResearch Bench II: Diagnosing Deep Research Agents via Rubrics from Expert Report,” arXiv:2601.08536, 2026.

944944

945 * **What was measured:** Its 132 research tasks across 22 domains are graded against expert-derived binary rubrics. Measured on a 50-task subset stratified across all themes, one attempt per task, 3 runs per setting, on [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) with the platform's own web search and fetch tools (August 26 to 27, 2026).

946 * **How scored:** Scored on the 33 tasks no configuration refused, with attempts the production safety classifiers cut short removed. Claude Opus 4.6 judges under the benchmark's rubric protocol; the original uses a different judge, and an Anthropic judge may favor the house style.

947 * **Scores:** Scores are each model's mean on the 33-task basis with its own pre-empted tasks removed; on the 21 of the 33 tasks where no configuration had an attempt cut short, Claude Fable 5.1 holds a 2-to-3-point lead over Claude Fable 5 at every effort level and both models are flat across effort.

948 * **How priced:** Costs are priced as a customer's organization is metered: each request's prior prompt as a cache read and its new tokens as a 5-minute cache write, a session's first request keeping the cache read it got, from the runs' own usage records, plus the platform's web-search fees. Each cost per task is a 50-task run's cost divided by 50, with the attempts that were cut short included, averaged over the three runs.

945 * **What was measured:** Its 132 research tasks across 22 domains are graded against expert-derived binary rubrics. Measured on a 50-task subset stratified across all themes, one attempt per task, 3 runs per setting, on [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) with the platform’s own web search and fetch tools (August 26 to 27, 2026).

946 * **How scored:** Scored on the 33 tasks no configuration refused, with attempts the production safety classifiers cut short removed. Claude Opus 4.6 judges under the benchmark’s rubric protocol; the original uses a different judge, and an Anthropic judge may favor the house style.

947 * **Scores:** Scores are each model’s mean on the 33-task basis with its own pre-empted tasks removed; on the 21 of the 33 tasks where no configuration had an attempt cut short, Claude Fable 5.1 holds a 2-to-3-point lead over Claude Fable 5 at every effort level and both models are flat across effort.

948 * **How priced:** Costs are priced as a customer’s organization is metered: each request’s prior prompt as a cache read and its new tokens as a 5-minute cache write, a session’s first request keeping the cache read it got, from the runs’ own usage records, plus the platform’s web-search fees. Each cost per task is a 50-task run’s cost divided by 50, with the attempts that were cut short included, averaged over the three runs.

949949 * **Results, Claude Fable 5:** Claude Fable 5 cost $2.30 USD per task at `low` and $4.71 USD at `high`, priced the same way; the percentages in [Upgrade the model](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#upgrade-the-model) come from unrounded costs.

950950 * **Results, Claude Opus 5:** Claude Opus 5 at its default effort ran on the same surface and subset, three runs, on August 28, 2026: 68.8% on the raw 50 tasks, 70.8% on the 33-task basis, and 71.1% on the 21-task set, at $6.28 USD per task ($23.72 USD without caching); none of its attempts was cut short by the safety classifiers, under a safeguards deployment newer than the one the other models ran under.

951951 * **Compare models:** The research comparison in [Compare models](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#compare-models-on-cost-per-task) rests on these figures: Claude Fable 5.1 at `low` scored 10 points above Claude Sonnet 5 on the 33-task basis (66% against 56%) at about four times the cost per task over all 50 tasks ($4.48 USD against $1.18 USD); Claude Opus 5 at its default, whose scores and cost are given earlier in this reference, scored above Claude Fable 5.1 at its default, which scored 65% on the 33-task basis and cost $6.89 USD per task over all 50 tasks, so on research, Claude Fable 5.1 earns its price only at `low`.

952952 * **Caching chart:** The caching chart re-prices the same requests with every input token at the uncached rate.

953953

9548. **Corpus defect sweep:** Anthropic-internal, for work larger than one context window: a 21.6-million-token corpus from 14 public Python package sources with 130 planted defects and deterministic grading; protocol fixed before the runs and internally reviewed; three runs per configuration. Every configuration ran on Claude Managed Agents. The charted team configuration is one in which the Claude Fable 5.1 orchestrator ran the whole sweep inside the platform at its documented limit of 25 concurrent Claude Sonnet 5 workers, run August 30, 2026; its three runs scored F1 0.764, 0.825, and 0.791 after the extras audit (raw 0.751, 0.821, and 0.781) for $225 USD, $234 USD, and $283 USD. The team configuration cost about half as much as Claude Fable 5.1 alone at `low`, `medium`, or `high` (47% to 55% less), scored 10 to 12 points below it, and took about 2.3 hours per run, compared with 15 to 20 hours. The team configuration read about 560 million cached tokens per run, nearly all of them at Claude Sonnet 5's cache-read rate. That is about one and a half times the roughly 365 million that Claude Fable 5.1 read alone. Claude Fable 5.1 alone at `high` effort still holds peak accuracy, at about 2.2 times the team configuration's cost, so delegation here buys most of the accuracy, not all of it. The configuration with Claude Sonnet 5 alone ran August 3 to 4, 2026; the configurations with Claude Fable 5.1 alone ran August 24 to 25, 2026, under the platform's launch serving settings, three seeds per effort setting, on the same corpus build. The sandbox image carried installed copies of part of the corpus, and Claude Fable 5.1's final assembly step compared against them in 7 of 9 runs; re-grading without those additions moved the affected seeds by up to 3 points. Absolute F1 is specific to this corpus build, not comparable across benchmarks; configuration comparisons are like for like.

9548. **Corpus defect sweep:** Anthropic-internal, for work larger than one context window: a 21.6-million-token corpus from 14 public Python package sources with 130 planted defects and deterministic grading; protocol fixed before the runs and internally reviewed; three runs per configuration. Every configuration ran on Claude Managed Agents. The charted team configuration is one in which the Claude Fable 5.1 orchestrator ran the whole sweep inside the platform at its documented limit of 25 concurrent Claude Sonnet 5 workers, run August 30, 2026; its three runs scored F1 0.764, 0.825, and 0.791 after the extras audit (raw 0.751, 0.821, and 0.781) for $225 USD, $234 USD, and $283 USD. The team configuration cost about half as much as Claude Fable 5.1 alone at `low`, `medium`, or `high` (47% to 55% less), scored 10 to 12 points below it, and took about 2.3 hours per run, compared with 15 to 20 hours. The team configuration read about 560 million cached tokens per run, nearly all of them at Claude Sonnet 5’s cache-read rate. That is about one and a half times the roughly 365 million that Claude Fable 5.1 read alone. Claude Fable 5.1 alone at `high` effort still holds peak accuracy, at about 2.2 times the team configuration’s cost, so delegation here buys most of the accuracy, not all of it. The configuration with Claude Sonnet 5 alone ran August 3 to 4, 2026; the configurations with Claude Fable 5.1 alone ran August 24 to 25, 2026, under the platform’s launch serving settings, three seeds per effort setting, on the same corpus build. The sandbox image carried installed copies of part of the corpus, and Claude Fable 5.1’s final assembly step compared against them in 7 of 9 runs; re-grading without those additions moved the affected seeds by up to 3 points. Absolute F1 is specific to this corpus build, not comparable across benchmarks; configuration comparisons are like for like.

955955

9569. **GPQA Diamond:** Rein et al., "GPQA: A Graduate-Level Google-Proof Q\&A Benchmark," 2023. The 198-question Diamond subset, model-graded against reference answers, advisor tokens metered per request. Claude Haiku 5.5 and Claude Sonnet 5.5, each alone and with a Claude Opus 5.5 advisor, and Claude Opus 5.5 alone ran two runs per configuration on October 7, 2026, all with [server-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#server-side-fallback) off, at each model's default effort, and with refusals counted as wrong. A platform safety check refused one biology question per run on Claude Haiku 5.5 and Claude Sonnet 5.5 alone, one in two runs on Haiku 5.5 with the advisor, none on Sonnet 5.5 with the advisor, and six per run on Opus 5.5, which scored 91% with them counted as wrong and 93.5% on the questions it answered. Claude Haiku 5.5 alone scored 85%, 6 points below Opus 5.5. The advisor configurations added the tool without a prompt asking for consultations, and neither executor called the advisor on any question. The pairings scored 0.5 points (Claude Haiku 5.5) and 1.0 points (Claude Sonnet 5.5) above the executor alone, both within run-to-run noise.

9569. **GPQA Diamond:** Rein et al., “GPQA: A Graduate-Level Google-Proof Q\&A Benchmark,” 2023. The 198-question Diamond subset, model-graded against reference answers, advisor tokens metered per request. Claude Haiku 5.5 and Claude Sonnet 5.5, each alone and with a Claude Opus 5.5 advisor, and Claude Opus 5.5 alone ran two runs per configuration on October 7, 2026, all with [server-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#server-side-fallback) off, at each model’s default effort, and with refusals counted as wrong. A platform safety check refused one biology question per run on Claude Haiku 5.5 and Claude Sonnet 5.5 alone, one in two runs on Haiku 5.5 with the advisor, none on Sonnet 5.5 with the advisor, and six per run on Opus 5.5, which scored 91% with them counted as wrong and 93.5% on the questions it answered. Claude Haiku 5.5 alone scored 85%, 6 points below Opus 5.5. The advisor configurations added the tool without a prompt asking for consultations, and neither executor called the advisor on any question. The pairings scored 0.5 points (Claude Haiku 5.5) and 1.0 points (Claude Sonnet 5.5) above the executor alone, both within run-to-run noise.

957957

95810. **DeepSWE:** Datacurve, "DeepSWE: Measuring Frontier Coding Agents on Original, Long-Horizon Engineering Tasks," arXiv:2607.07946, 2026. The set has 113 original tasks across five languages with program-based verifiers. Pairings are two runs each, run August 7, 2026, with advisor tokens metered per request, and used a client-side advisor loop rather than the advisor tool, with identical accounting. Single-model effort sweeps are single runs priced from token counts, a cache-aware approximation. Costs per task are run totals divided by 113. On this benchmark a low-effort Claude Sonnet 5 executor with an advisor scored 23 points above the same executor alone.

95810. **DeepSWE:** Datacurve, “DeepSWE: Measuring Frontier Coding Agents on Original, Long-Horizon Engineering Tasks,” arXiv:2607.07946, 2026. The set has 113 original tasks across five languages with program-based verifiers. Pairings are two runs each, run August 7, 2026, with advisor tokens metered per request, and used a client-side advisor loop rather than the advisor tool, with identical accounting. Single-model effort sweeps are single runs priced from token counts, a cache-aware approximation. Costs per task are run totals divided by 113. On this benchmark a low-effort Claude Sonnet 5 executor with an advisor scored 23 points above the same executor alone.

959959

96096011. **Internal agentic-coding benchmark:**

961961

962 * **What was measured:** Anthropic-internal: 370 repository tasks graded by the repositories' own tests. The API figures were measured with a plain API agent and a 128,000-token output cap, one run per configuration: Opus 5 alone at the default effort August 9 to 10, 2026, and at `low` and `medium` August 10, 2026; Claude Fable 5.1 alone at five explicitly set effort values August 20, 2026 (the chart shows three of them); and the pairing August 24 to 25, 2026.

962 * **What was measured:** Anthropic-internal: 370 repository tasks graded by the repositories’ own tests. The API figures were measured with a plain API agent and a 128,000-token output cap, one run per configuration: Opus 5 alone at the default effort August 9 to 10, 2026, and at `low` and `medium` August 10, 2026; Claude Fable 5.1 alone at five explicitly set effort values August 20, 2026 (the chart shows three of them); and the pairing August 24 to 25, 2026.

963963 * **August runs:** The August runs had five attempts per task for the pairing and the Claude Opus 5 control and one for the other points.

964 * **How priced:** Costs are per attempt. Costs are priced as a customer's organization is metered: each agent-loop request's prior prompt as a cache read and its new tokens as a 5-minute cache write, from the runs' own usage records, and each advisor call, which uses no cache, from its recorded tokens, all at list prices.

964 * **How priced:** Costs are per attempt. Costs are priced as a customer’s organization is metered: each agent-loop request’s prior prompt as a cache read and its new tokens as a 5-minute cache write, from the runs’ own usage records, and each advisor call, which uses no cache, from its recorded tokens, all at list prices.

965965 * **Claude Opus 5.5 alone:** Claude Opus 5.5 alone ran on all 370 tasks, September 19 to 20, 2026: at its default effort (`medium`) and at `high` with five attempts per task, and at `low` and `xhigh` with one (369 of 370 scored at each, after a setup-check failure). Claude Opus 5.5 alone solved 74.8% of attempts at `low` for $0.35 USD per attempt, 86.6% at `medium` for $0.84 USD, 88.4% at `high` for $1.38 USD, and 91.1% at `xhigh` for $4.11 USD.

966966 * **Claude Opus 5.5 with a Claude Fable 5.1 advisor, runs:** The Claude Opus 5.5 executor at `high` with the released Claude Fable 5.1 as advisor (the August runs used a pre-release snapshot) ran five attempts per task on the same dates; one task failed its setup check, so 1,845 attempts were scored. The 279 attempts in which the advisor was turned away under load were re-run, and attempts whose consults timed out were kept, as in August.

967967 * **Claude Fable 5.1 alone:** For comparison, the released Claude Fable 5.1 alone at `high`, its default, scored 85.7% (317 of 370 tasks), one attempt per task on October 7, 2026.

968968 * **Consultations:** The August pairing averaged about two advisor consultations per attempt; the Claude Opus 5.5 pairing requested 1.39 and received 1.35.

969 * **Claude Opus 5.5 with a Claude Fable 5.1 advisor, results:** The Claude Opus 5.5 pairing scored 90.1% at $2.92 USD per attempt: compared with Claude Opus 5.5 at its default, `medium`, that is 3.5 points for about 3.5 times the money. The latency cost is the consultations themselves: about one or two extra frontier-model calls per task, each on the task's critical path. With the Claude Opus 5.5 executor, the advice saved almost no executor cost: $1.36 USD per attempt compared with $1.38 USD for Claude Opus 5.5 alone at `high`, while the consultations cost $1.55 USD.

969 * **Claude Opus 5.5 with a Claude Fable 5.1 advisor, results:** The Claude Opus 5.5 pairing scored 90.1% at $2.92 USD per attempt: compared with Claude Opus 5.5 at its default, `medium`, that is 3.5 points for about 3.5 times the money. The latency cost is the consultations themselves: about one or two extra frontier-model calls per task, each on the task’s critical path. With the Claude Opus 5.5 executor, the advice saved almost no executor cost: $1.36 USD per attempt compared with $1.38 USD for Claude Opus 5.5 alone at `high`, while the consultations cost $1.55 USD.

970970 * **August pairing:** In August, with a Claude Opus 5 executor and a Claude Fable 5.1 advisor, the executor spent $1.26 USD less per attempt than Claude Opus 5 alone at its default, and the consultations cost $2.47 USD, so that saving paid for about half of the advice. That August pairing was the most accurate configuration measured at the time, at $6.21 USD per attempt.

971 * **Claude Sonnet 5.5 alone, runs:** Claude Sonnet 5.5 alone ran on all 370 tasks on September 24, 2026, at its default effort (`high`) and at `medium`, one attempt per task, with the same 128,000-token output cap, which cut off none of its attempts. All 370 were scored at `medium`, and 369 of 370 at `high`, after a setup-check failure. Its costs are priced as a customer's organization is metered.

972972 * **Claude Sonnet 5.5 alone, results:** With no advisor, Claude Sonnet 5.5 scored 77.8% at its default, `high`, for $0.33 USD per attempt, about 9 points below Claude Opus 5.5 at its default for about two fifths of the cost; at `medium`, it scored 62.7% for $0.16 USD. At `medium`, Claude Sonnet 5.5 scored about 15 points lower than at its default, `high`, for about 48% of the cost per attempt.

973973 * **Compare models:** In [Compare models](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#compare-models-on-cost-per-task), Claude Opus 5.5 at its default cost under a third as much per attempt as Claude Fable 5.1 at `medium`, which is a single run.

974974

from line 980

980980 * **Claude Opus 5.5 runs:** The Claude Opus 5.5 16,384-token figure averages two runs (134 and 135 tasks scored), and its 64,000 and 128,000 figures are single runs (135 tasks each); two attempts in each 16,384-token run and one in each of the 64,000- and 128,000-token runs ended in a safety refusal and count as failures. Claude Opus 5.5 solved 57.6% at 16,384 (58.2% and 57.0%), 75.6% at 64,000, and 68.9% at 128,000. None of its attempts was cut off at 64,000 or 128,000, so the cap does not explain the difference between those two runs.

981981 * **Attempts the cap ended:** Only 1 of the 66 Claude Opus 5.5 attempts that the 16,384-token cap ended, and 9 of the 117 Claude Fable 5.1 attempts, still passed.

982982 * **Cost per attempt:** Cost per attempt was $3 USD at 16,384 and $4 USD at 64,000 for Claude Opus 5.5, at list prices, and $8 USD and $13 USD for Claude Fable 5.1, as a customer is billed.

983 * **SWE-bench Pro cap figures:** The SWE-bench Pro cap figures are one Claude Fable 5.1 run per cap at the default effort, run August 26, 2026, on a 100-problem subset stratified from reference 3's 482-problem set, not comparable to its scores; at the default effort the runs at 16,384 and at 64,000 each solved 94 of the 100 problems.

984 * **Turn length:** The per-turn distributions in the section's dot plot come from the Claude Opus 5.5 and Claude Fable 5.1 runs at 128,000: no Opus 5.5 turn reached the cap (the longest was about 61,000 tokens, and 0.56% of its turns exceeded 16,384), and one Fable 5.1 turn reached 128,000 (0.46% of its turns exceeded 16,384). With the cap at 128,000, 2 of Claude Fable 5.1's 14,331 turns were longer than 64,000 tokens, and no Claude Opus 5.5 turn was.

983 * **SWE-bench Pro cap figures:** The SWE-bench Pro cap figures are one Claude Fable 5.1 run per cap at the default effort, run August 26, 2026, on a 100-problem subset stratified from reference 3’s 482-problem set, not comparable to its scores; at the default effort the runs at 16,384 and at 64,000 each solved 94 of the 100 problems.

984 * **Turn length:** The per-turn distributions in the section’s dot plot come from the Claude Opus 5.5 and Claude Fable 5.1 runs at 128,000: no Opus 5.5 turn reached the cap (the longest was about 61,000 tokens, and 0.56% of its turns exceeded 16,384), and one Fable 5.1 turn reached 128,000 (0.46% of its turns exceeded 16,384). With the cap at 128,000, 2 of Claude Fable 5.1’s 14,331 turns were longer than 64,000 tokens, and no Claude Opus 5.5 turn was.

985985

98613. **Chartography:** Surge AI, "Chartography," 2026.

98613. **Chartography:** Surge AI, “Chartography,” 2026.

987987

988 * **What was measured:** The complete released 100-question set, measured August 6 and 9, 2026 (Claude Opus 5 alone) and September 20, 2026 (Claude Opus 5.5), with Anthropic's implementation on Claude Managed Agents (standard cloud sandbox; advisor configurations use the Managed Agents advisor).

988 * **What was measured:** The complete released 100-question set, measured August 6 and 9, 2026 (Claude Opus 5 alone) and September 20, 2026 (Claude Opus 5.5), with Anthropic’s implementation on Claude Managed Agents (standard cloud sandbox; advisor configurations use the Managed Agents advisor).

989989 * **How scored:** Claude Sonnet 4.6 grades instead of the reference judge and the benchmark runs with tools, so scores compare across configurations here but not to the published leaderboard. They are also not comparable to the Chartography results in the Claude Opus 5.5 system card, which use a different grader and run at `max` effort. Two runs per configuration (three for Claude Opus 5.5), pooled; run-to-run spreads were up to 10 points.

990 * **How priced:** Costs are what a customer running the agent routinely is billed: each chart's first request reads the agent's shared system prompt and tools from the cache, as it does when another session of the same agent ran in the previous 5 minutes. A chart run on its own costs about $0.03 USD more with Claude Opus 5 or Claude Opus 5.5 and about $0.12 USD more with Claude Fable 5.1. The August figures are re-priced this way from the runs' usage records. Costs exclude sandbox time, which added under 1% to the August runs.

991 * **Claude Fable 5.1 alone, August runs:** The runs of Claude Fable 5.1 alone are from August 24, 2026, under the platform's launch serving settings, two runs per setting; six attempts hit the 15-minute session cap and score 0, and two charts per run were answered by Claude Opus 5 after a safety refusal.

992 * **Claude Opus 5 with a Claude Fable 5.1 advisor:** The Claude Opus 5 low-effort executor with a Claude Fable 5.1 advisor ran twice on August 30, 2026, under the same settings (63.0 and 67.0, mean 65.0, at $0.47 USD a chart; the advisor was consulted on 88% of tasks in each run, and 4 of its 219 replies came from Claude Opus 5 instead, each after a production safety filter stopped the advisor's own reply). That pairing matched Claude Fable 5.1 alone at `medium` within run-to-run noise (65.0 compared with 67.5) at about 1.8 times the cost per task: a consult that fires on most tasks costs more than running the stronger model itself.

990 * **How priced:** Costs are what a customer running the agent routinely is billed: each chart’s first request reads the agent’s shared system prompt and tools from the cache, as it does when another session of the same agent ran in the previous 5 minutes. A chart run on its own costs about $0.03 USD more with Claude Opus 5 or Claude Opus 5.5 and about $0.12 USD more with Claude Fable 5.1. The August figures are re-priced this way from the runs’ usage records. Costs exclude sandbox time, which added under 1% to the August runs.

991 * **Claude Fable 5.1 alone, August runs:** The runs of Claude Fable 5.1 alone are from August 24, 2026, under the platform’s launch serving settings, two runs per setting; six attempts hit the 15-minute session cap and score 0, and two charts per run were answered by Claude Opus 5 after a safety refusal.

992 * **Claude Opus 5 with a Claude Fable 5.1 advisor:** The Claude Opus 5 low-effort executor with a Claude Fable 5.1 advisor ran twice on August 30, 2026, under the same settings (63.0 and 67.0, mean 65.0, at $0.47 USD a chart; the advisor was consulted on 88% of tasks in each run, and 4 of its 219 replies came from Claude Opus 5 instead, each after a production safety filter stopped the advisor’s own reply). That pairing matched Claude Fable 5.1 alone at `medium` within run-to-run noise (65.0 compared with 67.5) at about 1.8 times the cost per task: a consult that fires on most tasks costs more than running the stronger model itself.

993993 * **Claude Opus 5.5 runs:** Claude Opus 5.5 ran at `low`, with server-side fallback off and a safety classifier judging every tool call: three runs alone (70, 68, and 68) and three with a Claude Fable 5.1 advisor configured (59, 63, and 63), in which it consulted the advisor on 1 of 300 tasks.

994994 * **Results at `low` effort:** On this chart-reading benchmark, Claude Opus 5.5 at `low` scored 68.7 for about $0.03 USD a chart, against 62.5 for $0.15 USD from Claude Fable 5.1 at `low` and 49 for $0.16 USD from Claude Opus 5 at `low`.

995995 * **Claude Fable 5.1 alone, October runs:** For comparison with the Claude Opus 5.5 pairing, Claude Fable 5.1 alone at `high`, its default, was run three times on October 7, 2026, with the same implementation and platform settings as the Claude Opus 5.5 runs: 82, 79, and 79, a mean of 80.0.

from line 999

999999

10001000 * **What was measured:** An Anthropic-constructed set of 44 support tickets with deterministic grading, run in early August 2026 and reported on August 8, 2026, under six system prompts, each adding to the same clean prompt one pattern common in prompts written for Claude Opus 4.8 and Claude Sonnet 4.6.

10011001 * **The chart:** Each chart point is one of three cases (older model, newer model on the same prompt, newer model after the audit) averaged over the six prompts and 44 tickets.

1002 * **Results, Claude Opus 5:** On Claude Opus 5, the prompts written for Claude Opus 4.8 cost 36% more per ticket than they did on Claude Opus 4.8, for no change in accuracy. After the audit they cost 14% less on Claude Opus 5 than before it (from the unrounded means; the chart's rounded costs, 3.43 and 2.93 US cents per ticket, give 14.6%), and Claude Opus 5 resolved 97% of tickets correctly, up from 92%. By pattern, on Claude Opus 5: removing "verify twice" cut the cost per ticket by a third, and removing "be maximally thorough" cut it almost as much; removing the retired thinking setting, the contradictory rules, and the hand-rolled scratchpad each restored 7 to 11 points of accuracy.

1002 * **Results, Claude Opus 5:** On Claude Opus 5, the prompts written for Claude Opus 4.8 cost 36% more per ticket than they did on Claude Opus 4.8, for no change in accuracy. After the audit they cost 14% less on Claude Opus 5 than before it (from the unrounded means; the chart’s rounded costs, 3.43 and 2.93 US cents per ticket, give 14.6%), and Claude Opus 5 resolved 97% of tickets correctly, up from 92%. By pattern, on Claude Opus 5: removing “verify twice” cut the cost per ticket by a third, and removing “be maximally thorough” cut it almost as much; removing the retired thinking setting, the contradictory rules, and the hand-rolled scratchpad each restored 7 to 11 points of accuracy.

10031003 * **Results, Claude Sonnet 5:** On the Claude Sonnet 4.6 to Claude Sonnet 5 migration, the audit took 14% off the cost per ticket at the same accuracy.

10041004 * **Caveats:** The Opus 5 accuracy gain has a 95% confidence interval of 3 to 8 points; the Sonnet accuracy differences are within noise.

10051005

100615. **Data-file question set:** An Anthropic-constructed set of 25 aggregate questions over a 1,862-row slice of a public liquor-sales CSV, with ground truth computed by pandas and exact-match grading, run on Claude Sonnet 5 and Claude Opus 5 with thinking disabled (the in-context arm cannot complete at the default), a 4,000-token output cap, and no prompt caching, three runs per configuration, run August 19, 2026. The file arm uploads the CSV through the Files API and uses the `code_execution_20260120` tool. The in-context arm's three Claude Sonnet 5 runs answered 6, 7, and 7 of the 25 questions correctly; the chart's label and the text give their mean, 6.67, to the nearest question, and the chart's point is drawn at the mean, 26.7%.

100615. **Data-file question set:** An Anthropic-constructed set of 25 aggregate questions over a 1,862-row slice of a public liquor-sales CSV, with ground truth computed by pandas and exact-match grading, run on Claude Sonnet 5 and Claude Opus 5 with thinking disabled (the in-context arm cannot complete at the default), a 4,000-token output cap, and no prompt caching, three runs per configuration, run August 19, 2026. The file arm uploads the CSV through the Files API and uses the `code_execution_20260120` tool. The in-context arm’s three Claude Sonnet 5 runs answered 6, 7, and 7 of the 25 questions correctly; the chart’s label and the text give their mean, 6.67, to the nearest question, and the chart’s point is drawn at the mean, 26.7%.

10071007

1008100816. **Cache duration measurement:**

10091009

10101010 * **What was measured:** The 20-issue triage job from [Trim input and context tokens](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#trim-input-and-context-tokens), run on Claude Sonnet 5 on August 23, 2026, and on Claude Opus 5.5 on September 19 and 20, 2026, at its default effort (`medium`) and at `high`, on the Messages API with the same harness (for Claude Opus 5.5, a port of it that sends the same request bodies), the Claude Opus 5.5 cells with `max_tokens` raised to 4,096, with pauses inserted before a randomly chosen share of turns (none, 5%, 10%, and every turn at 6 minutes on all 20 issues on both models, plus every turn at 2 minutes on Claude Sonnet 5; 20-minute and 45-minute pauses on a 5-issue subset on both models). The Claude Opus 5.5 figures on this page cover both effort levels.

1011 * **Other models and dates:** Claude Opus 5's keep-alive figures below come from the same job on August 23, 2026, with `max_tokens` raised to 4,096, on the same schedules except the 2-minute and 45-minute pauses. Claude Sonnet 5.5 ran the same measurement as Claude Sonnet 5 (the same pause schedules and three cache settings, three runs per cell), with the ported harness used for Claude Opus 5.5, at its default effort, `high`, on September 24, 2026.

1012 * **How scored and priced:** Three runs per cell, cost computed from each response's `usage` fields at list prices (for Claude Opus 5.5, $4 USD input, $5 USD 5-minute write, $8 USD 1-hour write, $0.20 USD cache read, and $20 USD output per million tokens; Claude Sonnet 5 ran on an Anthropic-internal organization whose usage is metered the same way as a customer organization's), accuracy against the same gold labels.

1013 * **How run and priced, Claude Sonnet 5.5:** Claude Sonnet 5.5 set `max_tokens` to 4,096 on session requests and to 1 on keep-alive requests, ran on an Anthropic-internal organization whose usage is metered the same way as a customer organization's, and is priced at its current list prices ($2 USD input, $2.50 USD 5-minute write, $4 USD 1-hour write, $0.10 USD cache read, and $10 USD output per million tokens). Apart from the higher `max_tokens`, which no turn reached, one input differs from the Claude Sonnet 5 runs: the job's one animated GIF was sent as a PNG of its first frame, the only frame the API uses ([Vision](https://platform.claude.com/docs/en/build-with-claude/vision)), and the two count as the same number of input tokens.

1014 * **Break-even:** The break-even is about 3.3% of turns on Claude Sonnet 5 and 3.1% to 3.2% on Claude Opus 5.5: the median of each session's break-even share, computed by the cost model from that session's turn-by-turn context sizes, over all 45 Claude Sonnet 5 twenty-issue sessions and the 36 Claude Opus 5.5 twenty-issue sessions at each effort level (every pause schedule run on the full job, under all three cache settings, three runs each; the 5-issue cells are not in it). The break-even on Claude Sonnet 5.5 is about 3.1% of turns, the median over its 45 twenty-issue sessions. The cache duration chart plots these Claude Sonnet 5.5 sessions, three per point.

1015 * **5-minute and 1-hour settings, Claude Sonnet 5 and Claude Opus 5.5:** In the 5% cell the 5-minute and 1-hour settings tied on Claude Sonnet 5, because that draw's pauses fell on small prefixes; on Claude Opus 5.5 they nearly tied. On Claude Sonnet 5, at its cache-read price of $0.20 USD per million tokens, a session cost $0.60 USD, $0.69 USD, and $0.99 USD on the 5-minute setting with no pauses, 5%, and 10% of turns paused, and $0.70 USD, $0.70 USD, and $0.71 USD on the 1-hour setting.

1011 * **Other models and dates:** Claude Opus 5’s keep-alive figures below come from the same job on August 23, 2026, with `max_tokens` raised to 4,096, on the same schedules except the 2-minute and 45-minute pauses. Claude Sonnet 5.5 ran the same measurement as Claude Sonnet 5 (the same pause schedules and three cache settings, three runs per cell), with the ported harness used for Claude Opus 5.5, at its default effort, `high`, on September 24, 2026.

1012 * **How scored and priced:** Three runs per cell, cost computed from each response’s `usage` fields at list prices (for Claude Opus 5.5, $4 USD input, $5 USD 5-minute write, $8 USD 1-hour write, $0.20 USD cache read, and $20 USD output per million tokens; Claude Sonnet 5 ran on an Anthropic-internal organization whose usage is metered the same way as a customer organization’s), accuracy against the same gold labels.

1013 * **How run and priced, Claude Sonnet 5.5:** Claude Sonnet 5.5 set `max_tokens` to 4,096 on session requests and to 1 on keep-alive requests, ran on an Anthropic-internal organization whose usage is metered the same way as a customer organization’s, and is priced at its current list prices ($2 USD input, $2.50 USD 5-minute write, $4 USD 1-hour write, $0.10 USD cache read, and $10 USD output per million tokens). Apart from the higher `max_tokens`, which no turn reached, one input differs from the Claude Sonnet 5 runs: the job’s one animated GIF was sent as a PNG of its first frame, the only frame the API uses ([Vision](https://platform.claude.com/docs/en/build-with-claude/vision)), and the two count as the same number of input tokens.

1014 * **Break-even:** The break-even is about 3.3% of turns on Claude Sonnet 5 and 3.1% to 3.2% on Claude Opus 5.5: the median of each session’s break-even share, computed by the cost model from that session’s turn-by-turn context sizes, over all 45 Claude Sonnet 5 twenty-issue sessions and the 36 Claude Opus 5.5 twenty-issue sessions at each effort level (every pause schedule run on the full job, under all three cache settings, three runs each; the 5-issue cells are not in it). The break-even on Claude Sonnet 5.5 is about 3.1% of turns, the median over its 45 twenty-issue sessions. The cache duration chart plots these Claude Sonnet 5.5 sessions, three per point.

1015 * **5-minute and 1-hour settings, Claude Sonnet 5 and Claude Opus 5.5:** In the 5% cell the 5-minute and 1-hour settings tied on Claude Sonnet 5, because that draw’s pauses fell on small prefixes; on Claude Opus 5.5 they nearly tied. On Claude Sonnet 5, at its cache-read price of $0.20 USD per million tokens, a session cost $0.60 USD, $0.69 USD, and $0.99 USD on the 5-minute setting with no pauses, 5%, and 10% of turns paused, and $0.70 USD, $0.70 USD, and $0.71 USD on the 1-hour setting.

10161016 * **Keep-alive requests, Claude Sonnet 5 and Claude Opus 5:** Anthropic measured keep-alive requests that refresh the 5-minute cache on Claude Sonnet 5 and Claude Opus 5 on August 23, 2026, and on Claude Opus 5.5 in the runs above, always sent with `max_tokens: 1`. On Claude Sonnet 5 they cost 7.7% less than the 1-hour setting with 5% of turns paused and about the same with 10%; on Claude Opus 5 no difference was measurable at either share; on both they cost more with a pause of 6 minutes or more before every turn. So on those two models the setting to use is the 1-hour duration, not keep-alive requests.

1017 * **Keep-alive requests, Claude Opus 5.5:** On Claude Opus 5.5 keep-alive requests cost 8% to 18% less than the 1-hour setting with 5% and 10% of turns paused (8% to 13% less at its default effort, `medium`, and 10% to 18% less at `high`; about 10% to 15% once between-session noise is removed by re-billing each keep-alive session's own tokens at 1-hour cache prices), and more with a pause before every turn: 4% to 6% more at 6 minutes, 9% to 10% at 20 minutes, and 56% to 58% at 45 minutes.

1017 * **Keep-alive requests, Claude Opus 5.5:** On Claude Opus 5.5 keep-alive requests cost 8% to 18% less than the 1-hour setting with 5% and 10% of turns paused (8% to 13% less at its default effort, `medium`, and 10% to 18% less at `high`; about 10% to 15% once between-session noise is removed by re-billing each keep-alive session’s own tokens at 1-hour cache prices), and more with a pause before every turn: 4% to 6% more at 6 minutes, 9% to 10% at 20 minutes, and 56% to 58% at 45 minutes.

10181018 * **Requests with `max_tokens: 0`:** Measured October 20, 2026, on Claude Fable 5.1, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5, three times per model, on a 10,000-token system prompt with the 5-minute cache. A `max_tokens: 0` request sent 4 minutes after the cache write returned no output, read the whole entry, and wrote nothing. A request 4 minutes later, 8 minutes after the write, still read the whole entry. Without the `max_tokens: 0` request, the request at 8 minutes read nothing and wrote the prefix again, all 12 times.

1019 * **5-minute and 1-hour settings, Claude Sonnet 5.5:** With 5% of turns paused the 5-minute setting cost 5% more than the 1-hour setting on average (2% less to 12% more across the three runs), which is within run-to-run variation: that draw's pauses fell on small prefixes, as on Claude Sonnet 5, and re-billing each 5-minute session's own tokens at 1-hour cache prices gives about 1% more. With 10% paused it cost 54% more (36% to 73% more). With no pauses, the 5-minute setting cost 19% less than the 1-hour setting on average (3% to 32% less across the three runs; the 1-hour setting's higher write price predicts about 20%), and 21% to 24% less in every run with 2-minute pauses.

1020 * **Keep-alive requests, Claude Sonnet 5.5:** Keep-alive requests cost 16% less than the 1-hour setting on average with 5% of turns paused (13% to 20% less across the three runs) and 8% less with 10% (3% to 10% less), and cost more with a pause of 6 minutes or more before every turn. With 5% and 10% of turns paused, the pauses lasted 6 to 32 minutes on Claude Sonnet 5.5 and on Claude Opus 5.5. Re-billing each keep-alive session's own tokens at 1-hour cache prices, as for Claude Opus 5.5 above, gives 15% to 16% less at 5% paused and about 10% less at 10%, and with a pause before every turn 7% more at 6 minutes, 9% to 10% more at 20 minutes, and 66% to 73% more at 45 minutes. The 6-minute figures leave out run 3, in which 2 of that session's 39 keep-alive requests timed out: the cache expired before those two turns, the session wrote 214,000 tokens to the cache against 80,000 to 85,000 in runs 1 and 2, and it cost 38% more than run 3's 1-hour session.

1021 * **Keep-alive requests, Claude Sonnet 5.5, by run:** Comparing each run's keep-alive session with the same run's 1-hour session instead, keep-alive cost from about the same to 10% more at 6 minutes (runs 1 and 2; 4% more on their average), from about the same to 16% more at 20 minutes, and 64% to 80% more at 45 minutes.

1022 * **Keep-alive requests, Claude Sonnet 5.5, sample size:** The keep-alive chart's 6-minute points average runs 1 and 2 for all three settings. Each cell is three sessions (two for the 6-minute figures above). With no pauses, keep-alive sends no extra requests and so matches the 5-minute setting, yet the two differed by as much as 23% within a single run, so a difference of a few percent in a three-run average is not a clear effect.

1019 * **5-minute and 1-hour settings, Claude Sonnet 5.5:** With 5% of turns paused the 5-minute setting cost 5% more than the 1-hour setting on average (2% less to 12% more across the three runs), which is within run-to-run variation: that draw’s pauses fell on small prefixes, as on Claude Sonnet 5, and re-billing each 5-minute session’s own tokens at 1-hour cache prices gives about 1% more. With 10% paused it cost 54% more (36% to 73% more). With no pauses, the 5-minute setting cost 19% less than the 1-hour setting on average (3% to 32% less across the three runs; the 1-hour setting’s higher write price predicts about 20%), and 21% to 24% less in every run with 2-minute pauses.

1020 * **Keep-alive requests, Claude Sonnet 5.5:** Keep-alive requests cost 16% less than the 1-hour setting on average with 5% of turns paused (13% to 20% less across the three runs) and 8% less with 10% (3% to 10% less), and cost more with a pause of 6 minutes or more before every turn. With 5% and 10% of turns paused, the pauses lasted 6 to 32 minutes on Claude Sonnet 5.5 and on Claude Opus 5.5. Re-billing each keep-alive session’s own tokens at 1-hour cache prices, as for Claude Opus 5.5 above, gives 15% to 16% less at 5% paused and about 10% less at 10%, and with a pause before every turn 7% more at 6 minutes, 9% to 10% more at 20 minutes, and 66% to 73% more at 45 minutes. The 6-minute figures leave out run 3, in which 2 of that session’s 39 keep-alive requests timed out: the cache expired before those two turns, the session wrote 214,000 tokens to the cache against 80,000 to 85,000 in runs 1 and 2, and it cost 38% more than run 3’s 1-hour session.

1021 * **Keep-alive requests, Claude Sonnet 5.5, by run:** Comparing each run’s keep-alive session with the same run’s 1-hour session instead, keep-alive cost from about the same to 10% more at 6 minutes (runs 1 and 2; 4% more on their average), from about the same to 16% more at 20 minutes, and 64% to 80% more at 45 minutes.

1022 * **Keep-alive requests, Claude Sonnet 5.5, sample size:** The keep-alive chart’s 6-minute points average runs 1 and 2 for all three settings. Each cell is three sessions (two for the 6-minute figures above). With no pauses, keep-alive sends no extra requests and so matches the 5-minute setting, yet the two differed by as much as 23% within a single run, so a difference of a few percent in a three-run average is not a clear effect.

10231023 * **Caching off and on, Claude Sonnet 5:** On Claude Sonnet 5, the same job was run with caching off and with caching on, three runs each on August 19, 2026, with `max_tokens` at 700: $3.36 USD against $0.57 USD a session on average, a saving of 83%.

1024 * **Priced from recorded token counts, Claude Sonnet 5.5:** Anthropic also re-priced the recorded token counts of the three Claude Sonnet 5.5 sessions with the 5-minute cache and no pauses for the caching figure in [Why caching comes first](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#why-caching-comes-first). Each of these three sessions is one conversation of 40 requests over the job's 20 issues. At list prices as of October 12, 2026, the sessions cost $0.51 USD each on average, from the usage fields, against $3.70 USD with every input token at the input price and output tokens unchanged: a saving of 86% (86% to 87% across the three sessions), or a factor of 7.3. At the launch cache-read price of $0.20 USD the saving is 82%, so the rise over the Claude Sonnet 5 figure comes from the lower cache-read price.

1024 * **Priced from recorded token counts, Claude Sonnet 5.5:** Anthropic also re-priced the recorded token counts of the three Claude Sonnet 5.5 sessions with the 5-minute cache and no pauses for the caching figure in [Why caching comes first](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#why-caching-comes-first). Each of these three sessions is one conversation of 40 requests over the job’s 20 issues. At list prices as of October 12, 2026, the sessions cost $0.51 USD each on average, from the usage fields, against $3.70 USD with every input token at the input price and output tokens unchanged: a saving of 86% (86% to 87% across the three sessions), or a factor of 7.3. At the launch cache-read price of $0.20 USD the saving is 82%, so the rise over the Claude Sonnet 5 figure comes from the lower cache-read price.

10251025 * **Priced from recorded token counts, Claude Opus 5.5:** Re-priced the same way, the three Claude Opus 5.5 sessions at its default effort, `medium`, with the 5-minute cache and no pauses cost $1.02 USD each on average against $6.93 USD, a saving of 85%, or a factor of 6.8; the model used thinking in 79% of requests.

1026 * **How thinking was set, two sets of runs only:** The requests of the three Claude Sonnet 5.5 sessions with the 5-minute cache and no pauses set no thinking option, so thinking was left at the model's default, and the model used it in 38% of requests. The requests of the Claude Sonnet 5 runs with caching off and with caching on also set no thinking option, so thinking was left at the model's default, and the model used it in 41 of 121 requests with caching off and 40 of 120 with caching on.

1026 * **How thinking was set, two sets of runs only:** The requests of the three Claude Sonnet 5.5 sessions with the 5-minute cache and no pauses set no thinking option, so thinking was left at the model’s default, and the model used it in 38% of requests. The requests of the Claude Sonnet 5 runs with caching off and with caching on also set no thinking option, so thinking was left at the model’s default, and the model used it in 41 of 121 requests with caching off and 40 of 120 with caching on.

10271027 * **Latency after a pause:** On Claude Sonnet 5 and Claude Opus 5, the turn after a pause kept its warm-cache latency on the 1-hour setting.

10281028 * **Changing the duration mid-conversation:** Measured October 21, 2026, on Claude Fable 5.1, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5, on the Messages API with no tools, adaptive thinking, `high` effort, a cache breakpoint on the system prompt, and [automatic caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#automatic-caching) or an explicit breakpoint on the last block. The conversations held about 5,000 or 100,000 tokens of filler text, with fixed one-word assistant turns and no thinking blocks. In a conversation cached at 5 minutes, the first 1-hour request that added a turn read nothing and wrote the whole prompt at the 1-hour price (55 of 55). The next 1-hour request read everything (36 of 36). A system prompt cached at 1 hour from the first request was still read (12 of 12). A 1-hour request that added nothing read the 5-minute entries (31 of 31) and did not extend them: 8 minutes later, the same request read nothing (12 of 12). In a conversation cached at 1 hour, a 5-minute request read everything and wrote only its new turn (12 of 12). The requests ran in one Anthropic-internal organization on the Claude API.

10291029 * **Changing the duration mid-conversation, how priced:** From the `usage` fields at list prices, at just over 100,000 tokens, with `max_tokens` at 16, the first 1-hour request that added a turn cost $2.01 USD, $0.80 USD, $0.40 USD, and $0.10 USD on the four models in the order named. A turn that read the cache cost $0.026 USD, $0.020 USD, $0.010 USD, and $0.005 USD. Claude Haiku 5.5 is at its [long context prices](https://platform.claude.com/docs/en/about-claude/pricing#long-context-pricing).

10301030

103117. **Cache-read share in production:** Aggregated first-party Claude API usage for the 14 days ending August 23, 2026, direct API product only, Anthropic-internal organizations excluded, no organization identified. An organization-day counts as an agent loop when its requests carry tool definitions and tool results, its prompts hold 9 or more prior tool calls on average, caching was used, and it made at least 10 such requests (the API has no conversation identifier, so this stands in for conversation length): 303,003 organization-days across 106,487 organizations, median cache-read share 84.2% of all input tokens, upper quartile 91.7%. Use-case labels (the organization's declared use case, or otherwise its classified one) cover 74% of those organization-days and 99% of their tokens; about 72% of coding organization-days read 80% or more. The top decile of organization-days reads 95.9% or more for coding and 94.2% to 94.8% for support, research, data, and other agents. The request-level split at 25 or more prior tool calls comes from a six-hour sample: coding 92% read, 7% write, under 1% uncached.

103117. **Cache-read share in production:** Aggregated first-party Claude API usage for the 14 days ending August 23, 2026, direct API product only, Anthropic-internal organizations excluded, no organization identified. An organization-day counts as an agent loop when its requests carry tool definitions and tool results, its prompts hold 9 or more prior tool calls on average, caching was used, and it made at least 10 such requests (the API has no conversation identifier, so this stands in for conversation length): 303,003 organization-days across 106,487 organizations, median cache-read share 84.2% of all input tokens, upper quartile 91.7%. Use-case labels (the organization’s declared use case, or otherwise its classified one) cover 74% of those organization-days and 99% of their tokens; about 72% of coding organization-days read 80% or more. The top decile of organization-days reads 95.9% or more for coding and 94.2% to 94.8% for support, research, data, and other agents. The request-level split at 25 or more prior tool calls comes from a six-hour sample: coding 92% read, 7% write, under 1% uncached.

10321032

1033103318. **Cache-break, compaction timing, and status-line measurements:**

10341034

1035 * **October 2026 test, one change to a long conversation:** Measured October 20, 2026, on Claude Fable 5.1, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5, on the Messages API with no tools, adaptive thinking, each model's default effort, the 5-minute cache, a cache breakpoint on the system prompt, and [automatic caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#automatic-caching). The conversation held about 101,000 tokens: a 20,000-token system prompt, 13 user turns of filler text, the model's own reply to the first turn with its thinking block, and one-word replies to the rest. Once one request had cached the conversation, a second added one short turn, and each measured request sent that longer conversation with one change. Two conversations per model gave the same result.

1035 * **October 2026 test, one change to a long conversation:** Measured October 20, 2026, on Claude Fable 5.1, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5, on the Messages API with no tools, adaptive thinking, each model’s default effort, the 5-minute cache, a cache breakpoint on the system prompt, and [automatic caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#automatic-caching). The conversation held about 101,000 tokens: a 20,000-token system prompt, 13 user turns of filler text, the model’s own reply to the first turn with its thinking block, and one-word replies to the rest. Once one request had cached the conversation, a second added one short turn, and each measured request sent that longer conversation with one change. Two conversations per model gave the same result.

10361036 * **October 2026 test, tokens read and written:** With no change, and with a per-message effort change, the request read all 101,000 tokens and wrote none. With a 25-token mid-conversation system message, or a 25-token status line at the end of the newest user turn, it read them all and wrote only the new text. A top-level effort change (to `low` on Claude Fable 5.1 and Claude Sonnet 5.5, to `high` on Claude Opus 5.5 and Claude Haiku 5.5) read the 20,000-token system prompt and wrote 81,000 tokens. The same 25 tokens at the front or the end of the system prompt read nothing and wrote all 101,000. The request after a mid-conversation system message, a top-level effort change, or 25 tokens added to the end of the system prompt read the new prefix; a new status line at the front wrote everything again. A further test on October 21, 2026, on the same four models with conversations of 5,000 tokens, and on all but Claude Fable 5.1 with conversations of 100,000 tokens, all with one-word replies, sent a beta header for the first time mid-conversation, as a first per-message effort change may: that request read everything the request before it had cached, all 54 times. A system message sent with no beta header did the same, all 15 times.

1037 * **October 2026 test, how priced:** The chart gives the prompt side of one request, from its `usage` fields at list prices. The chart's values, in the order system prompt edit, system message, top-level effort change, and per-message effort change: Claude Fable 5.1 $1.26 USD, $0.026 USD, $1.02 USD, and $0.025 USD; Claude Opus 5.5 $0.50 USD, $0.020 USD, $0.41 USD, and $0.020 USD; Claude Sonnet 5.5 $0.25 USD, $0.010 USD, $0.20 USD, and $0.010 USD. The unchanged request repeated an earlier request byte for byte; a new turn of about 25 tokens adds under $0.001 USD. On Claude Haiku 5.5, whose requests were over 100,000 prompt tokens and so at its [long context prices](https://platform.claude.com/docs/en/about-claude/pricing#long-context-pricing): $0.063 USD for the system prompt edit, $0.052 USD for the effort change, and $0.005 USD for the read. The requests ran on an Anthropic-internal organization whose usage is metered the same way as a customer organization's, and on which the API does not enforce the [prefix check](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#prefix-check) by default, so its system prompt edits were accepted. On accounts created on or after August 31, 2026, 00:00 UTC, a request to one of these four models that sends earlier thinking blocks back gets a 400 error by default if it changes `system`, `tools`, or a message before one of them.

1038 * **What was measured:** The triage agent's long variant from [Trim input and context tokens](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#trim-input-and-context-tokens), run August 24, 2026, on Claude Sonnet 5 with the 5-minute cache, cost from the usage fields at list prices, five sessions per arm: a no-change arm at the default effort throughout ($0.81 USD per session), and two arms that start at low effort and make the same two cache-breaking changes, a switch to the default effort and one added tool, either mid-session at requests 12 and 17 ($0.95 USD) or together on the first request after the first compaction ($0.75 USD).

1039 * **Fourth arm:** A fourth arm of six sessions, run August 25, 2026, made the same two changes on the request that triggered the first compaction ($0.92 USD per session): that request's summarization pass wrote the 81,000-token context to the cache instead of reading it, so that pass cost $0.21 USD against $0.04 USD for the same pass in the boundary arm.

1040 * **Compaction:** Sessions first compacted at request 21 to 25 (16 of the 21 sessions at request 22), once the prompt passed the 80,000-token compaction trigger, and two no-change sessions compacted a second time near the end. The boundary arm's lower total than the no-change arm reflects its low-effort requests before the change and those second compactions rather than caching: the two arms' re-write costs differ by under $0.01 USD.

1037 * **October 2026 test, how priced:** The chart gives the prompt side of one request, from its `usage` fields at list prices. The chart’s values, in the order system prompt edit, system message, top-level effort change, and per-message effort change: Claude Fable 5.1 $1.26 USD, $0.026 USD, $1.02 USD, and $0.025 USD; Claude Opus 5.5 $0.50 USD, $0.020 USD, $0.41 USD, and $0.020 USD; Claude Sonnet 5.5 $0.25 USD, $0.010 USD, $0.20 USD, and $0.010 USD. The unchanged request repeated an earlier request byte for byte; a new turn of about 25 tokens adds under $0.001 USD. On Claude Haiku 5.5, whose requests were over 100,000 prompt tokens and so at its [long context prices](https://platform.claude.com/docs/en/about-claude/pricing#long-context-pricing): $0.063 USD for the system prompt edit, $0.052 USD for the effort change, and $0.005 USD for the read. The requests ran on an Anthropic-internal organization whose usage is metered the same way as a customer organization’s, and on which the API does not enforce the [prefix check](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#prefix-check) by default, so its system prompt edits were accepted. On accounts created on or after August 31, 2026, 00:00 UTC, a request to one of these four models that sends earlier thinking blocks back gets a 400 error by default if it changes `system`, `tools`, or a message before one of them.

1038 * **What was measured:** The triage agent’s long variant from [Trim input and context tokens](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#trim-input-and-context-tokens), run August 24, 2026, on Claude Sonnet 5 with the 5-minute cache, cost from the usage fields at list prices, five sessions per arm: a no-change arm at the default effort throughout ($0.81 USD per session), and two arms that start at low effort and make the same two cache-breaking changes, a switch to the default effort and one added tool, either mid-session at requests 12 and 17 ($0.95 USD) or together on the first request after the first compaction ($0.75 USD).

1039 * **Fourth arm:** A fourth arm of six sessions, run August 25, 2026, made the same two changes on the request that triggered the first compaction ($0.92 USD per session): that request’s summarization pass wrote the 81,000-token context to the cache instead of reading it, so that pass cost $0.21 USD against $0.04 USD for the same pass in the boundary arm.

1040 * **Compaction:** Sessions first compacted at request 21 to 25 (16 of the 21 sessions at request 22), once the prompt passed the 80,000-token compaction trigger, and two no-change sessions compacted a second time near the end. The boundary arm’s lower total than the no-change arm reflects its low-effort requests before the change and those second compactions rather than caching: the two arms’ re-write costs differ by under $0.01 USD.

10411041 * **Mid-session arm:** The mid-session arm paid $0.23 USD per session in cache re-writes; the difference between the mid-session and boundary arms was $0.20 USD with a 95% confidence interval of $0.11 USD to $0.29 USD. In the mid-session arm, the effort change and the added tool rewrote 39,000 and 60,000 cached tokens. One of its sessions ran cheap ($0.82 USD) after its model mis-called the search tool following compaction and got empty results; it is included, and without it the arm averages $0.98 USD.

10421042 * **Accuracy and cache reads:** Accuracy averaged 14.2 of 20 labels in each August 24 arm and 14.7 in the August 25 arm; cache reads were 91% of prompt tokens with no changes, 85% mid-session, 91% at the boundary, and 86% with the changes on the triggering request.

10431043 * **Separate measurement, status line:** A separate measurement on the 20-issue triage job from [Trim input and context tokens](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#trim-input-and-context-tokens), run August 18, 2026, also on Claude Sonnet 5 with the 5-minute cache, priced the same way, three runs per arm: with a 25-token status line at the front of the system prompt, a run cost $4.24 USD on average ($4.12 USD to $4.47 USD across the three runs) and read nothing from the cache; with the same line at the end of the newest user turn, after the last cache breakpoint, a run cost $0.59 USD ($0.55 USD to $0.61 USD). The first is more than the same job cost with caching off. A later re-run with the same configuration gave $4.28 USD and $0.61 USD.

1044 * **Compaction trigger on Claude Haiku 5.5:** Measured October 21, 2026, on the Messages API with [compaction at a token threshold](https://platform.claude.com/docs/en/build-with-claude/compaction-threshold), no tools, adaptive thinking, the default effort (`medium`), the 5-minute cache, a cache breakpoint on the system prompt, and [automatic caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#automatic-caching). Each session was one conversation of 45 requests: a 5,000-token system prompt, 10,000 tokens of filler text with every user turn, and one-word assistant turns, except that a reply with a compaction block was sent back whole. Four settings ran three sessions each: triggers of 150,000 tokens (the default), 90,000, and 50,000 (the lowest allowed), and no compaction. Costs within a setting agreed to within 4%. With the default trigger, 15 of each session's 45 replies and all 3 summaries had prompts over 100,000 tokens. With a trigger of 90,000, the largest prompt held 97,269 tokens. Compaction ran at the first request whose whole prompt had reached the trigger, counting the system prompt, cache reads, and cache writes. The summary was written from that prompt plus 44 tokens, up to 7,269 tokens over the trigger. Three more sessions, with a 22,000-token system prompt and a trigger of 50,000, showed that the system prompt counts. The summaries were short (184 to 640 output tokens) because the text was filler. The requests ran in one Anthropic-internal organization on the Claude API.

1045 * **Compaction trigger on Claude Haiku 5.5, how priced:** From the `usage` fields at list prices, a session cost $0.272 USD with the default trigger, $0.082 USD at 90,000, $0.075 USD at 50,000, and $0.729 USD with no compaction. Per request, from the request after the first compaction through the last compaction, the three triggers cost $0.00605 USD, $0.00181 USD, and $0.00166 USD. With every prompt at the prices for prompts up to 100,000 tokens, the default would cost $0.00206 USD per request, and a trigger of 90,000 would save 12%. A compaction's summary and reply are each priced by their own prompt's size.

1044 * **Compaction trigger on Claude Haiku 5.5:** Measured October 21, 2026, on the Messages API with [compaction at a token threshold](https://platform.claude.com/docs/en/build-with-claude/compaction-threshold), no tools, adaptive thinking, the default effort (`medium`), the 5-minute cache, a cache breakpoint on the system prompt, and [automatic caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#automatic-caching). Each session was one conversation of 45 requests: a 5,000-token system prompt, 10,000 tokens of filler text with every user turn, and one-word assistant turns, except that a reply with a compaction block was sent back whole. Four settings ran three sessions each: triggers of 150,000 tokens (the default), 90,000, and 50,000 (the lowest allowed), and no compaction. Costs within a setting agreed to within 4%. With the default trigger, 15 of each session’s 45 replies and all 3 summaries had prompts over 100,000 tokens. With a trigger of 90,000, the largest prompt held 97,269 tokens. Compaction ran at the first request whose whole prompt had reached the trigger, counting the system prompt, cache reads, and cache writes. The summary was written from that prompt plus 44 tokens, up to 7,269 tokens over the trigger. Three more sessions, with a 22,000-token system prompt and a trigger of 50,000, showed that the system prompt counts. The summaries were short (184 to 640 output tokens) because the text was filler. The requests ran in one Anthropic-internal organization on the Claude API.

1045 * **Compaction trigger on Claude Haiku 5.5, how priced:** From the `usage` fields at list prices, a session cost $0.272 USD with the default trigger, $0.082 USD at 90,000, $0.075 USD at 50,000, and $0.729 USD with no compaction. Per request, from the request after the first compaction through the last compaction, the three triggers cost $0.00605 USD, $0.00181 USD, and $0.00166 USD. With every prompt at the prices for prompts up to 100,000 tokens, the default would cost $0.00206 USD per request, and a trigger of 90,000 would save 12%. A compaction’s summary and reply are each priced by their own prompt’s size.

10461046

104719. **Cache duration measurement on Claude Fable 5.1:** The same 20-issue triage job and harness as reference 16, with `max_tokens` raised to 4,096, run August 23 and August 26, 2026, on the Claude Fable 5.1 launch snapshot at its launch prices ($10 USD input, $12.50 USD 5-minute write, $20 USD 1-hour write, $0.25 USD cache read, $50 USD output per million tokens), three settings per schedule: the 5-minute cache, the 1-hour cache, and the 5-minute cache kept warm by a `max_tokens: 0` request on the unchanged prefix every 4 minutes, timed from the previous request's start (the August 23 runs sent keep-alive requests with `max_tokens: 1`; in the August 26 cells reported here, every answered keep-alive request refreshed the cache and its response reported no output tokens). Schedules: no pauses, 10% of turns, and every turn at 6 minutes on all 20 issues, and 45-minute pauses on the 5-issue subset; three runs per cell (six for the August 26 keep-alive cell with 45-minute pauses), cost computed from each response's `usage` fields at list prices, accuracy against the same gold labels (12 to 18 exact labels of 20). Per-session means on August 26 for the 5-minute, 1-hour, and keep-alive settings: no pauses $2.42 USD, $3.09 USD, $2.29 USD; 10% paused $4.50 USD, $2.96 USD, $2.36 USD; every turn $22.89 USD, $3.01 USD, $2.62 USD; the August 23 cells agree within 6%. The 45-minute figures ($1.68 USD, $0.59 USD, and $0.71 USD per 5-issue session) are from later sessions of August 26: that day's first set of sessions was cut off when its machine was shut down, and the second was affected by a fault in the service and is set aside. The third set gives the 5-minute and 1-hour figures; its three keep-alive sessions sent each keep-alive request once, lost requests to rate-limit refusals, and are not in the mean. The keep-alive figure is the mean of six further sessions that sent any refused keep-alive request again within two seconds. The August 23 runs gave $1.67 USD, $0.58 USD, and $0.70 USD. The break-even between the 5-minute and 1-hour settings is 3.1% of turns, the same measure as reference 16. Claude Fable 5.1's cache read costs 0.025x the input price while its cache writes keep the standard multipliers, so a keep-alive request that re-reads the prefix is cheap and the 1-hour duration's write premium is the larger bill, except with 45-minute pauses, where the keep-alive requests cost more than the premium.

104719. **Cache duration measurement on Claude Fable 5.1:** The same 20-issue triage job and harness as reference 16, with `max_tokens` raised to 4,096, run August 23 and August 26, 2026, on the Claude Fable 5.1 launch snapshot at its launch prices ($10 USD input, $12.50 USD 5-minute write, $20 USD 1-hour write, $0.25 USD cache read, $50 USD output per million tokens), three settings per schedule: the 5-minute cache, the 1-hour cache, and the 5-minute cache kept warm by a `max_tokens: 0` request on the unchanged prefix every 4 minutes, timed from the previous request’s start (the August 23 runs sent keep-alive requests with `max_tokens: 1`; in the August 26 cells reported here, every answered keep-alive request refreshed the cache and its response reported no output tokens). Schedules: no pauses, 10% of turns, and every turn at 6 minutes on all 20 issues, and 45-minute pauses on the 5-issue subset; three runs per cell (six for the August 26 keep-alive cell with 45-minute pauses), cost computed from each response’s `usage` fields at list prices, accuracy against the same gold labels (12 to 18 exact labels of 20). Per-session means on August 26 for the 5-minute, 1-hour, and keep-alive settings: no pauses $2.42 USD, $3.09 USD, $2.29 USD; 10% paused $4.50 USD, $2.96 USD, $2.36 USD; every turn $22.89 USD, $3.01 USD, $2.62 USD; the August 23 cells agree within 6%. The 45-minute figures ($1.68 USD, $0.59 USD, and $0.71 USD per 5-issue session) are from later sessions of August 26: that day’s first set of sessions was cut off when its machine was shut down, and the second was affected by a fault in the service and is set aside. The third set gives the 5-minute and 1-hour figures; its three keep-alive sessions sent each keep-alive request once, lost requests to rate-limit refusals, and are not in the mean. The keep-alive figure is the mean of six further sessions that sent any refused keep-alive request again within two seconds. The August 23 runs gave $1.67 USD, $0.58 USD, and $0.70 USD. The break-even between the 5-minute and 1-hour settings is 3.1% of turns, the same measure as reference 16. Claude Fable 5.1’s cache read costs 0.025x the input price while its cache writes keep the standard multipliers, so a keep-alive request that re-reads the prefix is cheap and the 1-hour duration’s write premium is the larger bill, except with 45-minute pauses, where the keep-alive requests cost more than the premium.

10481048

104920. **Terminal-Bench 3:** the public terminal-agent benchmark's 74 tasks, run on [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) with two custom tools, a shell and a file editor that the evaluation harness runs in each task's own container, in place of the platform's built-in tools, and otherwise at the platform's default settings for external accounts, two runs per model at `high` effort, August 27 to 28, 2026. These runs used Terminal-Bench version 3.0, and their scores are not comparable with the public Terminal-Bench leaderboard or with the Terminal-Bench 4.0 results in the Claude Opus 5.5 system card, which come from runs in Claude Code at `max` effort. Each task's time limits are 2.5 times the benchmark's own, which gives the agent between 75 minutes and 20 hours per task (5 hours for the median task), and each task gets three times the memory it specifies, from 6 GiB to 96 GiB, with extra memory for the 12 tasks that run helper services. The agent had no general internet access: its containers could reach an internal package mirror, a short list of download sites including GitHub and the Python Package Index, and a few sites specific to some tasks, and eight of the tasks had no network access at all. Scores are raw pass rates over the 148 attempts per model; single runs swing by 5 to 11 points. Costs are what a customer would be billed at list prices, re-priced request by request from the runs' usage records with the 5-minute cache lifetime. Claude Opus 4.7, Claude Opus 4.8, and Claude Opus 5 each spend $8 USD to $15 USD per task. Claude Opus 4.7 ended 11 of its 148 attempts at its output cap.

104920. **Terminal-Bench 3:** the public terminal-agent benchmark’s 74 tasks, run on [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) with two custom tools, a shell and a file editor that the evaluation harness runs in each task’s own container, in place of the platform’s built-in tools, and otherwise at the platform’s default settings for external accounts, two runs per model at `high` effort, August 27 to 28, 2026. These runs used Terminal-Bench version 3.0, and their scores are not comparable with the public Terminal-Bench leaderboard or with the Terminal-Bench 4.0 results in the Claude Opus 5.5 system card, which come from runs in Claude Code at `max` effort. Each task’s time limits are 2.5 times the benchmark’s own, which gives the agent between 75 minutes and 20 hours per task (5 hours for the median task), and each task gets three times the memory it specifies, from 6 GiB to 96 GiB, with extra memory for the 12 tasks that run helper services. The agent had no general internet access: its containers could reach an internal package mirror, a short list of download sites including GitHub and the Python Package Index, and a few sites specific to some tasks, and eight of the tasks had no network access at all. Scores are raw pass rates over the 148 attempts per model; single runs swing by 5 to 11 points. Costs are what a customer would be billed at list prices, re-priced request by request from the runs’ usage records with the 5-minute cache lifetime. Claude Opus 4.7, Claude Opus 4.8, and Claude Opus 5 each spend $8 USD to $15 USD per task. Claude Opus 4.7 ended 11 of its 148 attempts at its output cap.

10501050

105121. **DRACO:** Perplexity, "DRACO: a Cross-Domain Benchmark for Deep Research Accuracy, Completeness, and Objectivity," arXiv:2602.11685, 2026.

105121. **DRACO:** Perplexity, “DRACO: a Cross-Domain Benchmark for Deep Research Accuracy, Completeness, and Objectivity,” arXiv:2602.11685, 2026.

10521052

10531053 * **What was measured:** Its 100 research tasks across 10 domains are graded against expert-written rubrics of about 40 weighted criteria each, and the score is the weighted share of criteria met, from 0 to 100.

1054 * **Configurations:** Every configuration ran on the Claude API with Claude Opus 5.5, the default adaptive thinking, the production safety classifiers on, and `max_tokens` at 128,000 with streaming: a single agent at `medium` effort (the model's default) and at `low`, the single agent at `medium` with the sentence and the clock, and a team at `medium` with and without them. The team is a lead agent that can start helper agents of the same model through a tool, with no cap on their number.

1055 * **The sentence:** The two changes are a sentence and a clock. The sentence, "Time matters here: do not spend time that can be avoided, and the earlier a correct result is obtained, the better.", goes at the end of the task in the agent's first `user` message, after a blank line, and at the end of each helper's brief.

1056 * **The clock:** The clock is the elapsed time in whole seconds, such as `[elapsed 252s]`, added before every request, including the first, to the end of the newest `user` message: in its own text block after the task on the first request, and at the end of the last tool result's text, after a blank line, when the message carries tool results. Earlier clocks stay in place, so the cached prefix still matches on the next request. Every agent in a team reads the same clock, and the system prompt doesn't change.

1057 * **In the measured runs:** The measured runs used this wording and format. Their clock started at the first token of the first response rather than at the start of the task. In the measured team runs, a helper's report reached the lead in a separate message after the clock, not inside the last tool result.

1054 * **Configurations:** Every configuration ran on the Claude API with Claude Opus 5.5, the default adaptive thinking, the production safety classifiers on, and `max_tokens` at 128,000 with streaming: a single agent at `medium` effort (the model’s default) and at `low`, the single agent at `medium` with the sentence and the clock, and a team at `medium` with and without them. The team is a lead agent that can start helper agents of the same model through a tool, with no cap on their number.

1055 * **The sentence:** The two changes are a sentence and a clock. The sentence, “Time matters here: do not spend time that can be avoided, and the earlier a correct result is obtained, the better.”, goes at the end of the task in the agent’s first `user` message, after a blank line, and at the end of each helper’s brief.

1056 * **The clock:** The clock is the elapsed time in whole seconds, such as `[elapsed 252s]`, added before every request, including the first, to the end of the newest `user` message: in its own text block after the task on the first request, and at the end of the last tool result’s text, after a blank line, when the message carries tool results. Earlier clocks stay in place, so the cached prefix still matches on the next request. Every agent in a team reads the same clock, and the system prompt doesn’t change.

1057 * **In the measured runs:** The measured runs used this wording and format. Their clock started at the first token of the first response rather than at the start of the task. In the measured team runs, a helper’s report reached the lead in a separate message after the clock, not inside the last tool result.

10581058 * **When:** Each configuration made three attempts at each task, with a four-hour limit per attempt, run September 24, 2026, and all configurations of a set started together.

10591059 * **Tools:** The agents used search and fetch tools that the evaluation harness hosts over an Anthropic web index, and Python and a shell in a sandbox with no network access. Those tools set part of the time, and yours will run at a different speed, so the page gives time as a ratio between configurations, not in minutes.

1060 * **How timed:** Time is the wall-clock time of an attempt, from its first request to the end of the last request by any agent, including tool runs, averaged over a task's attempts. A typical-task figure is the median, over tasks, of each task's ratio between two configurations.

1061 * **How priced:** Each task's cost is its requests priced at Claude Opus 5.5's public list prices, with prompt caching billed as it would be for a customer who sets a cache breakpoint at the end of each request and uses the 5-minute cache lifetime. Each request reads the previous request's prompt from the cache and writes the rest. An attempt's first request, and any request that starts more than 5 minutes after the one before it, writes its whole prompt. Costs cover model tokens only; the harness's tools add no charges.

1062 * **How scored:** All intervals are 95% bootstrap intervals over tasks, and score changes are paired differences over tasks. Claude Opus 5 grades the answers, so Claude Opus 5.5 doesn't grade its own work, and each answer's score averages five judging runs.

1063 * **Caveats:** A production safety classifier stopped three attempts in each configuration, all on one task, and those attempts score 0; leaving that task out changes no finding. The runs also passed each agent's tool use through an Anthropic-internal safety check that customer requests don't have, which adds time to each request in every configuration. On DRACO, the single agent without the changes made about twice as many requests, and the team about a third more, so the check probably makes the DRACO time savings look slightly larger.

1060 * **How timed:** Time is the wall-clock time of an attempt, from its first request to the end of the last request by any agent, including tool runs, averaged over a task’s attempts. A typical-task figure is the median, over tasks, of each task’s ratio between two configurations.

1061 * **How priced:** Each task’s cost is its requests priced at Claude Opus 5.5’s public list prices, with prompt caching billed as it would be for a customer who sets a cache breakpoint at the end of each request and uses the 5-minute cache lifetime. Each request reads the previous request’s prompt from the cache and writes the rest. An attempt’s first request, and any request that starts more than 5 minutes after the one before it, writes its whole prompt. Costs cover model tokens only; the harness’s tools add no charges.

1062 * **How scored:** All intervals are 95% bootstrap intervals over tasks, and score changes are paired differences over tasks. Claude Opus 5 grades the answers, so Claude Opus 5.5 doesn’t grade its own work, and each answer’s score averages five judging runs.

1063 * **Caveats:** A production safety classifier stopped three attempts in each configuration, all on one task, and those attempts score 0; leaving that task out changes no finding. The runs also passed each agent’s tool use through an Anthropic-internal safety check that customer requests don’t have, which adds time to each request in every configuration. On DRACO, the single agent without the changes made about twice as many requests, and the team about a third more, so the check probably makes the DRACO time savings look slightly larger.

10641064 * **Results, single agent:** Results for [Show the model elapsed time](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#show-the-model-elapsed-time): with the changes, the single agent took 47% less time at a 60% lower cost on the typical task, its average cost fell from $1.13 USD to $0.44 USD per task, and its score was 4.1 points lower (95% interval 2.9 to 5.2 lower).

1065 * **Results, lower effort:** Lowering the single agent's effort saved more time and cost than the changes did, and lost more score. At `low` effort, it scored 13.3 points lower on DRACO, 3.4 on HLE, and 14.0 on the physics set than at `medium`, and the typical task took 84%, 30%, and 47% less time. With the changes at `medium` effort, it scored 9.2, 2.5, and 11.0 points higher than at `low`, and the typical task took longer than at `low` by a factor of 1.2 to 3.2.

1066 * **Results, team, helpers:** The team's lead rarely started helpers. Without the changes, it started a helper in only 5 of 300 attempts on DRACO, 13 of 1,479 on HLE, and none of 280 on the physics set.

1067 * **Results, team:** So the team results mostly show the lead agent working alone, with the team's own instructions and tools. Without the changes, the team already took about half the single agent's time on the typical DRACO task, and scored 3.3 points lower (95% interval 2.1 to 4.6 lower). With the changes, the team took 17% less time at a 20% lower cost on the typical DRACO task, and scored 1.6 points lower (95% interval 0.3 to 2.8 lower).

1065 * **Results, lower effort:** Lowering the single agent’s effort saved more time and cost than the changes did, and lost more score. At `low` effort, it scored 13.3 points lower on DRACO, 3.4 on HLE, and 14.0 on the physics set than at `medium`, and the typical task took 84%, 30%, and 47% less time. With the changes at `medium` effort, it scored 9.2, 2.5, and 11.0 points higher than at `low`, and the typical task took longer than at `low` by a factor of 1.2 to 3.2.

1066 * **Results, team, helpers:** The team’s lead rarely started helpers. Without the changes, it started a helper in only 5 of 300 attempts on DRACO, 13 of 1,479 on HLE, and none of 280 on the physics set.

1067 * **Results, team:** So the team results mostly show the lead agent working alone, with the team’s own instructions and tools. Without the changes, the team already took about half the single agent’s time on the typical DRACO task, and scored 3.3 points lower (95% interval 2.1 to 4.6 lower). With the changes, the team took 17% less time at a 20% lower cost on the typical DRACO task, and scored 1.6 points lower (95% interval 0.3 to 2.8 lower).

10681068

106922. **HLE:** Phan et al., "Humanity's Last Exam," arXiv:2501.14249, 2025. Expert-written questions with exact answers, graded against the reference answers. Measured on the first 500 questions of the September 10, 2025, release, images included, with the benchmark's own sources blocked from search, and the same setup as reference 21. Each configuration made three attempts at each question, run September 24, 2026. Claude Opus 5 compares each answer with the reference answer, using the benchmark's published judge prompt, and the majority of three judgings counts. The scores cover 493 questions in every configuration. For five of the others, the grading request was over the judge's 1M-token limit, and the other two are left out because the run of the single agent without the changes stopped before three of its attempts on them finished. Time and cost ratios cover 492 questions for the single agent and 491 for the team, because one or two questions have no timing. A production safety classifier stopped 3% to 4% of each configuration's attempts, and those attempts score 0; leaving them out changes no finding. Results for [Show the model elapsed time](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#show-the-model-elapsed-time): with the changes, the single agent took 14% less time at a 9% lower cost on the typical question. With the Claude Opus 5 judge, its score showed no clear change (0.9 points lower, 95% interval 2.5 lower to 0.7 higher). With a second grader, Claude Opus 4.6, its score was 1.9 points lower (95% interval 0.2 to 3.7 lower). Average time fell further than the typical question's: average time fell 43% and average cost 37%, because the changes cut a few very long questions short. The team's time on the typical question changed by 3% or less, and its score didn't change clearly.

106922. **HLE:** Phan et al., “Humanity’s Last Exam,” arXiv:2501.14249, 2025. Expert-written questions with exact answers, graded against the reference answers. Measured on the first 500 questions of the September 10, 2025, release, images included, with the benchmark’s own sources blocked from search, and the same setup as reference 21. Each configuration made three attempts at each question, run September 24, 2026. Claude Opus 5 compares each answer with the reference answer, using the benchmark’s published judge prompt, and the majority of three judgings counts. The scores cover 493 questions in every configuration. For five of the others, the grading request was over the judge’s 1M-token limit, and the other two are left out because the run of the single agent without the changes stopped before three of its attempts on them finished. Time and cost ratios cover 492 questions for the single agent and 491 for the team, because one or two questions have no timing. A production safety classifier stopped 3% to 4% of each configuration’s attempts, and those attempts score 0; leaving them out changes no finding. Results for [Show the model elapsed time](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#show-the-model-elapsed-time): with the changes, the single agent took 14% less time at a 9% lower cost on the typical question. With the Claude Opus 5 judge, its score showed no clear change (0.9 points lower, 95% interval 2.5 lower to 0.7 higher). With a second grader, Claude Opus 4.6, its score was 1.9 points lower (95% interval 0.2 to 3.7 lower). Average time fell further than the typical question’s: average time fell 43% and average cost 37%, because the changes cut a few very long questions short. The team’s time on the typical question changed by 3% or less, and its score didn’t change clearly.

10701070

107123. **Physics set:** An internal set of 70 research-level physics problems, adapted from the public CritPt benchmark: Zhu et al., "Probing the Critical Point (CritPt) of AI Reasoning: a Frontier Physics Research Benchmark," arXiv:2509.26574, 2025. Expert reviewers corrected the problem statements. Claude Opus 4.6 grades each answer with partial credit, using the set's grading prompt, against expert reference solutions that aren't public, so the scores can't be compared with published results. The score is the mean grade over a problem's attempts, averaged over problems, in points out of 100. Measured on all 70 problems, four attempts per problem, run September 24, 2026. Every agent had a Python tool, a shell, and a file editor in a sandbox container with no network access, and no search or fetch tools. No safety classifier stopped an attempt on the physics set. Otherwise the setup is that of reference 21. Results for [Show the model elapsed time](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#show-the-model-elapsed-time): with the changes, the single agent took 7% less time at a 4% lower cost on the typical problem, and its score was 3.0 points lower (95% interval 0.4 to 5.6 lower). The team's time on the typical problem changed by 3% or less, and its score didn't change clearly. The single agent's average time fell 14%. The single agent's whole average time saving comes from one problem, on which the agent without the changes ran code for about half an hour per attempt; without that problem, its average time is about the same with and without the changes.

107123. **Physics set:** An internal set of 70 research-level physics problems, adapted from the public CritPt benchmark: Zhu et al., “Probing the Critical Point (CritPt) of AI Reasoning: a Frontier Physics Research Benchmark,” arXiv:2509.26574, 2025. Expert reviewers corrected the problem statements. Claude Opus 4.6 grades each answer with partial credit, using the set’s grading prompt, against expert reference solutions that aren’t public, so the scores can’t be compared with published results. The score is the mean grade over a problem’s attempts, averaged over problems, in points out of 100. Measured on all 70 problems, four attempts per problem, run September 24, 2026. Every agent had a Python tool, a shell, and a file editor in a sandbox container with no network access, and no search or fetch tools. No safety classifier stopped an attempt on the physics set. Otherwise the setup is that of reference 21. Results for [Show the model elapsed time](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#show-the-model-elapsed-time): with the changes, the single agent took 7% less time at a 4% lower cost on the typical problem, and its score was 3.0 points lower (95% interval 0.4 to 5.6 lower). The team’s time on the typical problem changed by 3% or less, and its score didn’t change clearly. The single agent’s average time fell 14%. The single agent’s whole average time saving comes from one problem, on which the agent without the changes ran code for about half an hour per attempt; without that problem, its average time is about the same with and without the changes.

10721072

1073107324. **tau2-bench retail:** Barres et al., "τ²-Bench: Evaluating Conversational Agents in a Dual-Control Environment," arXiv:2506.07982, 2025.

10741074

1075 * **What was measured:** The retail domain's 114 tasks ran on the public harness against the Claude API, with Claude Haiku 4.5 as the simulated user, Claude Sonnet 5 as the natural-language judge, and prompt caching on; the tasks were split into 57 search and 57 held-out.

1076 * **When:** The two searches ran on September 6, 2026, driven by the Claude API skill's `hillclimb` command. The caching before-and-after pair ran on September 8, 2026.

1077 * **How scored:** In the searches, the starting points and the confirmed configuration are the mean of three held-out runs, kept steps were judged on two runs, and other candidates were scored on one or two runs. The caching pair: three runs each on all 114 tasks with only the harness's cache breakpoints toggled, the configuration the `cost-optimize` command produced in an earlier run. Held-out numbers are on 57 tasks the search never read.

1078 * **How priced:** Cost per task prices the agent's and the simulated user's token counts at list prices (Claude Opus 5 $5 USD and $25 USD, Claude Sonnet 5 $2 USD and $10 USD per million input and output tokens, cache reads and writes at their published rates) and excludes the judge; percent changes come from unrounded costs; the monthly figure is the agent's tokens alone, $0.135 USD and $0.047 USD per task, times 10,000. At 10,000 conversations a month, that is about $1,350 USD before the first search and $470 USD after.

1075 * **What was measured:** The retail domain’s 114 tasks ran on the public harness against the Claude API, with Claude Haiku 4.5 as the simulated user, Claude Sonnet 5 as the natural-language judge, and prompt caching on; the tasks were split into 57 search and 57 held-out.

1076 * **When:** The two searches ran on September 6, 2026, driven by the Claude API skill’s `hillclimb` command. The caching before-and-after pair ran on September 8, 2026.

1077 * **How scored:** In the searches, the starting points and the confirmed configuration are the mean of three held-out runs, kept steps were judged on two runs, and other candidates were scored on one or two runs. The caching pair: three runs each on all 114 tasks with only the harness’s cache breakpoints toggled, the configuration the `cost-optimize` command produced in an earlier run. Held-out numbers are on 57 tasks the search never read.

1078 * **How priced:** Cost per task prices the agent’s and the simulated user’s token counts at list prices (Claude Opus 5 $5 USD and $25 USD, Claude Sonnet 5 $2 USD and $10 USD per million input and output tokens, cache reads and writes at their published rates) and excludes the judge; percent changes come from unrounded costs; the monthly figure is the agent’s tokens alone, $0.135 USD and $0.047 USD per task, times 10,000. At 10,000 conversations a month, that is about $1,350 USD before the first search and $470 USD after.

10791079 * **Caveats:** These measurements ran on the previous Claude Opus and Claude Sonnet models: the caching pair ran on Claude Sonnet 5, the second search started from Claude Sonnet 5, and the first search went from Claude Opus 5 to Claude Sonnet 5.

10801080 * **Caching pair:** The pair ran on Claude Sonnet 5 at the default effort. The public harness, as shipped, sends the whole conversation uncached on every turn. The cached configuration has one breakpoint on the system prompt and one on the latest message. Both searches ran with that caching on. Cost per task went from $0.223 USD uncached to $0.062 USD cached, a 72% saving, and the pass rate from 79.2% to 76.0%. Identical cached runs of that configuration ranged from 85 to 93 of 114 across days. Every cached run scored at or below every uncached run, but the gap of under 4 tasks sits inside the spread of identical cached runs, so the accuracy change is too small to measure at this sample size.

10811081 * **How the search ran.** The `hillclimb` command asks four questions, presents a plan, and waits for approval before it spends anything. In the first search, the plan left the user simulator, grader, caching, temperature, and tasks unchanged. The last of the four questions began: `One pass over the full set is 114 cases x 1 rep on claude-opus-5, roughly 22 minutes.` Each round, the search proposes one change and runs the full set. It keeps the change only when the number moved and the predicted mechanism shows in the usage data. It stops when three rounds in a row bring nothing, then confirms the winner on fresh runs.

10821082 * **First search, result.** The search cut cost per task by 61% while holding the pass rate within a 2-point band set before the search: from Claude Opus 5 at the default effort ($0.142 USD a task, 76.0% passed) to Claude Sonnet 5 at `low` with one cost-neutral prompt edit ($0.055 USD, 74.3%). The search cost $179 USD in evaluation runs and $228 USD in its own tokens.

10831083 * **First search, start: Claude Opus 5, default effort.** 76.0% at $0.142 USD. Three identical runs spanned 43 to 44 of 57. The search set the floor 2 points under, at 74.0%, and rounded it up to 43 of 57 (75.4%) for its verdicts.

1084 * **First search, step 1, effort to `low`: kept.** 77.2% on the two runs that kept it, 77.8% on a three-run confirm after the search, at $0.119 USD, 17% cheaper. The search's own status line reads, in part: `two runs held-out 42 and 46, mean 44.0 >= floor 43; cost mean $0.1187 <= gate $0.1208; mechanism confirmed (output tokens -34% with calls flat)`.

1084 * **First search, step 1, effort to `low`: kept.** 77.2% on the two runs that kept it, 77.8% on a three-run confirm after the search, at $0.119 USD, 17% cheaper. The search’s own status line reads, in part: `two runs held-out 42 and 46, mean 44.0 >= floor 43; cost mean $0.1187 <= gate $0.1208; mechanism confirmed (output tokens -34% with calls flat)`.

10851085 * **First search, step 2, Claude Sonnet 5 at `low`: kept.** 75.4% at $0.055 USD, 61% cheaper.

1086 * **First search, step 3, a prompt edit (look the customer's orders up after login instead of asking for an order ID): kept on selection, then did not hold.** 79.8% on two runs; 74.3% on three fresh runs. The search left it in as cost-neutral: the freed turn became another lookup turn.

1087 * **First search, step 4, a prompt edit (transfer to a human only when asked): rejected and reverted.** 71.9%. It fixed the 3 cases it targeted and broke 10 others with a generic "say what you can and can't do" template.

1088 * **First search, step 5, a prompt edit: not run.** Its predicted gain of 0.5 tasks was under the search's 2-task adoption gate.

1089 * **First search, confirm: Claude Sonnet 5 at `low` with the step-3 prompt, three fresh runs.** 74.3% at $0.055 USD, inside the 2-point band by 0.14 of a task, 1 task in 57 under the start, and below the 43-of-57 floor the search registered. This configuration's five runs spanned 42 to 46, wider than the start's 43 to 44.

1090 * **First search, what it showed.** The effort and model levers produced the savings, and each one's mechanism confirmed it. The prompt lever produced real behavior changes but no durable gain. On this workload, the number of turns and the cached prefix each turn re-reads set the cost per task, not the wording.

1091 * **Second search.** It started from Claude Sonnet 5 at the default effort with caching on: 79.5% at $0.062 USD on the held-out half, with three runs spanning 42 to 47 of 57, so the floor was 45 of 57 (78.9%). Identical runs of a starting configuration differed by up to 5 tasks in 57 here. The second search kept nothing. Effort at `low`, two prompt edits, and both together each scored 77.2%, under the floor, and saved 10% to 14%, short of the search's 15% cost gate. A prompt edit for accuracy scored 79.8% on two runs and 73.7% on three fresh runs, and was reverted. The search took about 19 evaluation runs and $120 USD.

1086 * **First search, step 3, a prompt edit (look the customer’s orders up after login instead of asking for an order ID): kept on selection, then did not hold.** 79.8% on two runs; 74.3% on three fresh runs. The search left it in as cost-neutral: the freed turn became another lookup turn.

1088 * **First search, step 5, a prompt edit: not run.** Its predicted gain of 0.5 tasks was under the search’s 2-task adoption gate.

1089 * **First search, confirm: Claude Sonnet 5 at `low` with the step-3 prompt, three fresh runs.** 74.3% at $0.055 USD, inside the 2-point band by 0.14 of a task, 1 task in 57 under the start, and below the 43-of-57 floor the search registered. This configuration’s five runs spanned 42 to 46, wider than the start’s 43 to 44.

1090 * **First search, what it showed.** The effort and model levers produced the savings, and each one’s mechanism confirmed it. The prompt lever produced real behavior changes but no durable gain. On this workload, the number of turns and the cached prefix each turn re-reads set the cost per task, not the wording.

1091 * **Second search.** It started from Claude Sonnet 5 at the default effort with caching on: 79.5% at $0.062 USD on the held-out half, with three runs spanning 42 to 47 of 57, so the floor was 45 of 57 (78.9%). Identical runs of a starting configuration differed by up to 5 tasks in 57 here. The second search kept nothing. Effort at `low`, two prompt edits, and both together each scored 77.2%, under the floor, and saved 10% to 14%, short of the search’s 15% cost gate. A prompt edit for accuracy scored 79.8% on two runs and 73.7% on three fresh runs, and was reverted. The search took about 19 evaluation runs and $120 USD.

10921092

1093109325. **Claude Managed Agents task set:**

10941094

10951095 * **What was measured:** An Anthropic-internal set of 79 scripted agent tasks in eight areas, including memory, multi-agent, and long-context work, run as [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) sessions in which the test answers every tool call. Each task ran five times per model.

10961096 * **Runs:** The figures are from one run per model on October 7, 2026, graded that day. In three more runs of the same tasks on October 8 and 9, 2026, Claude Haiku 5.5 passed 91% to 93% of attempts, and in one more run on October 8, Claude Haiku 4.5 passed 63%.

1097 * **How scored:** An attempt passed only if the grader, Claude Sonnet 4.6, grading once, marked every line of the task's checklist as met, so pass rates depend on the grader. On all but one task, a separate call, shown the tool results in full, graded the line that checks the files and messages the agent wrote through its tools against those results.

1097 * **How scored:** An attempt passed only if the grader, Claude Sonnet 4.6, grading once, marked every line of the task’s checklist as met, so pass rates depend on the grader. On all but one task, a separate call, shown the tool results in full, graded the line that checks the files and messages the agent wrote through its tools against those results.

10981098 * **How priced:** Costs are token costs at list prices with 5-minute prompt caching, priced request by request, and exclude session runtime.

1099 * **Results, token prices and cost:** Claude Haiku 4.5 did not cache 80% of its requests: each had a prompt of about 4,100 tokens or fewer, and its minimum cacheable prompt length is 4,096 tokens (512 for Claude Haiku 5.5). From Claude Haiku 4.5 to Claude Haiku 5.5, token prices fell by up to 90%, and the token cost of the 79 tasks fell by about 75%. The token cost fell less than the prices because about 5% of Claude Haiku 5.5's requests had prompts over 100,000 tokens, which pay higher prices ([Long context pricing](https://platform.claude.com/docs/en/about-claude/pricing#long-context-pricing)), and they carried 73% of its cost.

1100 * **Thinking:** Anthropic set Claude Haiku 5.5's effort to `medium` and sent no thinking setting or output limit for either model, so thinking was left to Claude Managed Agents' own settings for each model. Claude Haiku 5.5 used thinking in 59% of requests, and Claude Haiku 4.5 in 22%. The comparison is of each model as served, not at equal settings.

1101 * **Cost without caching, priced from recorded token counts:** Anthropic also re-priced the recorded token counts of Claude Haiku 5.5's October 7 run for the caching factor in [Why caching comes first](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#why-caching-comes-first). Claude Managed Agents applies prompt caching itself, so the factor compares two prices for the same requests, not two settings.

1102 * **The factor:** The factor, 1.7, is the run's token cost with every input token at the input price, output tokens unchanged, divided by its token cost with each session priced by itself: each request's prior prompt as a cache read and its new tokens as a 5-minute cache write. Each request is priced for its own prompt length in both costs, so the 87 requests over 100,000 tokens pay the higher prices in both. On the token counts as recorded, which this guide's costs for the run use, the factor is 1.9, because the five attempts of a task ran side by side and read each other's cache entries.

1099 * **Results, token prices and cost:** Claude Haiku 4.5 did not cache 80% of its requests: each had a prompt of about 4,100 tokens or fewer, and its minimum cacheable prompt length is 4,096 tokens (512 for Claude Haiku 5.5). From Claude Haiku 4.5 to Claude Haiku 5.5, token prices fell by up to 90%, and the token cost of the 79 tasks fell by about 75%. The token cost fell less than the prices because about 5% of Claude Haiku 5.5’s requests had prompts over 100,000 tokens, which pay higher prices ([Long context pricing](https://platform.claude.com/docs/en/about-claude/pricing#long-context-pricing)), and they carried 73% of its cost.

1100 * **Thinking:** Anthropic set Claude Haiku 5.5’s effort to `medium` and sent no thinking setting or output limit for either model, so thinking was left to Claude Managed Agents’ own settings for each model. Claude Haiku 5.5 used thinking in 59% of requests, and Claude Haiku 4.5 in 22%. The comparison is of each model as served, not at equal settings.

1101 * **Cost without caching, priced from recorded token counts:** Anthropic also re-priced the recorded token counts of Claude Haiku 5.5’s October 7 run for the caching factor in [Why caching comes first](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#why-caching-comes-first). Claude Managed Agents applies prompt caching itself, so the factor compares two prices for the same requests, not two settings.

1102 * **The factor:** The factor, 1.7, is the run’s token cost with every input token at the input price, output tokens unchanged, divided by its token cost with each session priced by itself: each request’s prior prompt as a cache read and its new tokens as a 5-minute cache write. Each request is priced for its own prompt length in both costs, so the 87 requests over 100,000 tokens pay the higher prices in both. On the token counts as recorded, which this guide’s costs for the run use, the factor is 1.9, because the five attempts of a task ran side by side and read each other’s cache entries.

11031103 * **Why the factor is low:** The factor is low because the sessions are short, a median of 4 requests: most input tokens arrive as tool results on the second or third request and are read from the cache only once or twice. Eight long-context tasks hold three quarters of the cost. A second run, on October 8, also gives 1.7.

11041104

1105110526. **Answer-format measurement:**

11061106

1107 * **What was measured:** The 20-issue triage job from [Trim input and context tokens](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#trim-input-and-context-tokens), run on Claude Sonnet 5 with prompt caching on and no thinking setting in the request, so thinking was left at the model's default, under three final-answer instructions, three runs per instruction.

1107 * **What was measured:** The 20-issue triage job from [Trim input and context tokens](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#trim-input-and-context-tokens), run on Claude Sonnet 5 with prompt caching on and no thinking setting in the request, so thinking was left at the model’s default, under three final-answer instructions, three runs per instruction.

11081108 * **Two-line instruction:** The original asked for two lines: `4. Finish with exactly two lines: LABEL: <one of: bug-confirmed, needs-more-info, duplicate-candidate, feature-request, upstream-issue, perf, ui-polish> SUMMARY: <one or two sentences for the engineering team>`

11091109 * **One-line instruction:** The shorter variant asked for one: `4. Finish with exactly one line in this form: DECISION | LABEL | REASON where DECISION is one of: triage-now, needs-info, close-duplicate; LABEL is one of: bug-confirmed, needs-more-info, duplicate-candidate, feature-request, upstream-issue, perf, ui-polish; REASON is one clause under 15 words. Output nothing after that line.`

11101110 * **Memo instruction:** The longer variant asked for a memo with six headed sections: problem summary, evidence, duplicate check, recommended label, next steps, and confidence.

1111 * **Also in the instructions as sent:** As sent, the two-line instruction also said "Be concise." and the memo instruction "Be thorough and explicit."

1111 * **Also in the instructions as sent:** As sent, the two-line instruction also said “Be concise.” and the memo instruction “Be thorough and explicit.”

11121112 * **When:** The two-line and one-line instructions ran on August 18, 2026, with `max_tokens` at 700, and the memo instruction on August 19, 2026, with `max_tokens` at 3,000. No response reached its cap.

1113 * **How scored and priced:** Figures are the mean of the three runs at Claude Sonnet 5's list prices, and accuracy is exact match against the gold labels.

1114 * **Results:** The one-line answer used 39% fewer output tokens than the two-line original and cost 13% less per run (from the unrounded means; the chart's rounded costs, $0.49 USD and $0.57 USD, give 14%). The memo used six times the output tokens of the two-line original and cost 2.8 times the one-line answer.

1113 * **How scored and priced:** Figures are the mean of the three runs at Claude Sonnet 5’s list prices, and accuracy is exact match against the gold labels.

1114 * **Results:** The one-line answer used 39% fewer output tokens than the two-line original and cost 13% less per run (from the unrounded means; the chart’s rounded costs, $0.49 USD and $0.57 USD, give 14%). The memo used six times the output tokens of the two-line original and cost 2.8 times the one-line answer.

11151115 * **Thinking:** About half of the responses included thinking, and its tokens are counted in the output tokens.

11161116

1117111727. **Tool search measurement:**

11181118

1119 * **What was measured:** The 20-issue triage job from [Trim input and context tokens](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#trim-input-and-context-tokens), run on Claude Sonnet 5 on August 19, 2026, with prompt caching on and no thinking setting in the request, so thinking was left at the model's default, three runs per configuration. The agent had its own two tools plus real tool definitions from public MCP servers, for a total of 7, 17, 52, 102, 252, or 502 tools, with every definition loaded or with the added ones marked `defer_loading` behind tool search.

1120 * **How scored and priced:** Figures are the mean of the three runs at Claude Sonnet 5's list prices, and accuracy is exact match against the gold labels.

1121 * **Results:** With every definition loaded, the run cost rose from $0.55 USD at 7 tools to $1.02 USD at 502 tools, nearly double. With tool search it was $0.55 USD to $0.56 USD at every catalog size, 45% less at 502 tools (from the chart's rounded costs, $0.56 USD and $1.02 USD; the unrounded means give 45.6%). Every run answered 15 to 18 of the 20 issues correctly, with or without tool search.

1122 * **Caveats:** No run called a tool from the catalog or the tool search tool: the agent's own two tools were always loaded, and every tool call went to one of them. The measurement shows what carrying unused definitions costs.

1123 * **Separate measurement:** In a separate measurement on the same model and date, with a public GitHub MCP server attached through the MCP connector and no catalog, three runs with the server's toolset deferred cost 20% less than three runs without ($0.56 USD and $0.70 USD per run), and the three runs of each arm answered 17, 16, and 16 issues correctly. The requests in this separate measurement included no tool search tool. With the toolset loaded, each run called one of the server's tools, `issue_read`, 3 or 4 times; with it deferred, no run called any of the server's tools.

1119 * **What was measured:** The 20-issue triage job from [Trim input and context tokens](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#trim-input-and-context-tokens), run on Claude Sonnet 5 on August 19, 2026, with prompt caching on and no thinking setting in the request, so thinking was left at the model’s default, three runs per configuration. The agent had its own two tools plus real tool definitions from public MCP servers, for a total of 7, 17, 52, 102, 252, or 502 tools, with every definition loaded or with the added ones marked `defer_loading` behind tool search.

1120 * **How scored and priced:** Figures are the mean of the three runs at Claude Sonnet 5’s list prices, and accuracy is exact match against the gold labels.

1121 * **Results:** With every definition loaded, the run cost rose from $0.55 USD at 7 tools to $1.02 USD at 502 tools, nearly double. With tool search it was $0.55 USD to $0.56 USD at every catalog size, 45% less at 502 tools (from the chart’s rounded costs, $0.56 USD and $1.02 USD; the unrounded means give 45.6%). Every run answered 15 to 18 of the 20 issues correctly, with or without tool search.

1122 * **Caveats:** No run called a tool from the catalog or the tool search tool: the agent’s own two tools were always loaded, and every tool call went to one of them. The measurement shows what carrying unused definitions costs.

1123 * **Separate measurement:** In a separate measurement on the same model and date, with a public GitHub MCP server attached through the MCP connector and no catalog, three runs with the server’s toolset deferred cost 20% less than three runs without ($0.56 USD and $0.70 USD per run), and the three runs of each arm answered 17, 16, and 16 issues correctly. The requests in this separate measurement included no tool search tool. With the toolset loaded, each run called one of the server’s tools, `issue_read`, 3 or 4 times; with it deferred, no run called any of the server’s tools.

11241124

1125112528. **Input trimming and context lifecycle measurements:**

11261126

1127 * **What was measured:** The 20-issue triage job from [Trim input and context tokens](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#trim-input-and-context-tokens) and its long variant, run on Claude Sonnet 5 on August 19, 2026 (dated in UTC), three runs per setting, with no thinking setting in the request, so thinking was left at the model's default; about 3 in 10 responses included thinking.

1127 * **What was measured:** The 20-issue triage job from [Trim input and context tokens](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#trim-input-and-context-tokens) and its long variant, run on Claude Sonnet 5 on August 19, 2026 (dated in UTC), three runs per setting, with no thinking setting in the request, so thinking was left at the model’s default; about 3 in 10 responses included thinking.

11281128 * **The chart:** The chart in [Manage the context lifecycle](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#manage-the-context-lifecycle) compares four settings on each job: the job with prompt caching and input trimming (image resizing and tool search) on, and the same with one lever added, which is context editing, compaction, or the prune. The chart counts a change of under 10% as no change.

11291129 * **Lever settings:** The lever settings differed between the two jobs: context editing cleared at least 2,000 tokens once the prompt passed 20,000 on the 20-issue job, and at least 40,000 once it passed 50,000 on the long one, keeping the three most recent tool uses, and compaction triggered at 50,000 input tokens on the 20-issue job and 80,000 on the long one.

1130 * **How priced:** Each cost is the mean of the three runs, from the responses' usage fields at Claude Sonnet 5's list prices, with cache writes at $2.50 USD and cache reads at $0.20 USD per million tokens.

1130 * **How priced:** Each cost is the mean of the three runs, from the responses’ usage fields at Claude Sonnet 5’s list prices, with cache writes at $2.50 USD and cache reads at $0.20 USD per million tokens.

11311131 * **Results, input trimming:** A fifth setting, prompt caching with no input trimming, cost $0.57 USD a run on the 20-issue job and $1.38 USD on the long one, so input trimming took 26% off the first and 21% off the second. Against the same 20-issue job with caching off, which cost $3.36 USD a run (reference 16), prompt caching and input trimming together saved 88% (the unrounded means give 87.5%).

11321132 * **Results, 20-issue run:** On the 20-issue run, where the job with no lever cost $0.42 USD a run, context editing cost 73% more, compaction ran once near the end of each run and cost 7% less, and the prune rewrote nothing, because no search result was over its 2,000-character threshold.

11331133 * **Results, long run:** On the long run, where the job with no lever cost $1.09 USD a run, the prune cost 39% less, compaction 32% less, and context editing 4% more.

about-claude/pricing Changed · +12 / -12 lines

from line 4

44description: Learn about Anthropic's pricing structure for models and features

55---

7This page provides detailed pricing information for Anthropic's models and features. All prices are in USD.

7This page provides detailed pricing information for Anthropic’s models and features. All prices are in USD.

99For the most current pricing information, visit [claude.com/pricing](https://claude.com/pricing).

1010

from line 95

9595| **Tax** | Pre-tax metering; AWS Marketplace handles tax |

9696| **Cost visibility** | Real-time breakdown in the Claude Console (access through the AWS Console); AWS Cost Explorer shows aggregated CCU |

9797

98**CCU:** Claude Consumption Unit. A CCU is a unit of measure used solely for Marketplace Platform invoicing. If Customer accesses the Services through certain Marketplace Platforms (e.g., Claude Platform on AWS), usage will be invoiced in Claude Consumption Units ("CCU") rather than per MTok. One hundred (100) CCU represents $1.00 USD of fees owed for the Services, calculated at the applicable prices on [claude.com/pricing#api](https://claude.com/pricing#api), after application of any discounts.

98**CCU:** Claude Consumption Unit. A CCU is a unit of measure used solely for Marketplace Platform invoicing. If Customer accesses the Services through certain Marketplace Platforms (e.g., Claude Platform on AWS), usage will be invoiced in Claude Consumption Units (“CCU”) rather than per MTok. One hundred (100) CCU represents $1.00 USD of fees owed for the Services, calculated at the applicable prices on [claude.com/pricing#api](https://claude.com/pricing#api), after application of any discounts.

9999

100100### Inference geography

101101

from line 124

124124| **Tax** | Pre-tax metering; Azure Marketplace handles tax |

125125| **Cost visibility** | Azure Cost Management shows aggregated CCU |

126126

127**CCU:** Claude Consumption Unit. A CCU is a unit of measure used solely for Marketplace Platform invoicing. If Customer accesses the Services through certain Marketplace Platforms (e.g., Claude Platform on AWS, Claude in Microsoft Foundry), usage will be invoiced in Claude Consumption Units ("CCU") rather than per MTok. One hundred (100) CCU represents $1.00 USD of fees owed for the Services, calculated at the applicable prices on [claude.com/pricing#api](https://claude.com/pricing#api), after application of any discounts.

127**CCU:** Claude Consumption Unit. A CCU is a unit of measure used solely for Marketplace Platform invoicing. If Customer accesses the Services through certain Marketplace Platforms (e.g., Claude Platform on AWS, Claude in Microsoft Foundry), usage will be invoiced in Claude Consumption Units (“CCU”) rather than per MTok. One hundred (100) CCU represents $1.00 USD of fees owed for the Services, calculated at the applicable prices on [claude.com/pricing#api](https://claude.com/pricing#api), after application of any discounts.

128128

129129### Inference geography

130130

from line 219

219219

220220Claude 4.6 and later models (except Claude Haiku 5.5) and [Claude Mythos Preview](https://anthropic.com/glasswing) include the full [1M token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows) at standard pricing. (A 900k-token request is billed at the same per-token rate as a 9k-token request.) Prompt caching and batch processing discounts apply at standard rates across the full context window.

221221

222Claude Haiku 5.5 is priced by prompt length: a request whose prompt is over 100,000 tokens pays higher prices. A request's prompt length counts all of its input tokens, including cache reads and cache writes. Each request is priced on its own: a request over the threshold pays the higher prices even when part of its prompt is a cache hit, and earlier requests keep the prices they were billed at. The [model pricing](https://platform.claude.com/docs/en/about-claude/pricing#model-pricing) and [batch processing pricing](https://platform.claude.com/docs/en/about-claude/pricing#batch-processing) sections list both sets of prices.

222Claude Haiku 5.5 is priced by prompt length: a request whose prompt is over 100,000 tokens pays higher prices. A request’s prompt length counts all of its input tokens, including cache reads and cache writes. Each request is priced on its own: a request over the threshold pays the higher prices even when part of its prompt is a cache hit, and earlier requests keep the prices they were billed at. The [model pricing](https://platform.claude.com/docs/en/about-claude/pricing#model-pricing) and [batch processing pricing](https://platform.claude.com/docs/en/about-claude/pricing#batch-processing) sections list both sets of prices.

223223

224224### Tool use pricing

225225

from line 314

314314

315315#### Text editor tool

316316

317The text editor tool uses the same pricing structure as other tools used with Claude. It follows the standard input and output token pricing based on the Claude model you're using.

317The text editor tool uses the same pricing structure as other tools used with Claude. It follows the standard input and output token pricing based on the Claude model you’re using.

318318

319319In addition to the base tokens, the following additional input tokens are needed for the text editor tool:

320320

from line 392

392392* Tool execution results returned to Claude

393393

394394<Note>

395 If you're also using bash or text editor tools alongside computer use, those tools have their own token costs as documented in their respective pages.

395 If you’re also using bash or text editor tools alongside computer use, those tools have their own token costs as documented in their respective pages.

396396</Note>

397397

398398#### Browser use tool

from line 416

416416

417417### Tokens

418418

419All tokens consumed by a Claude Managed Agents session are billed at the rates shown in [Model pricing](https://platform.claude.com/docs/en/about-claude/pricing#model-pricing). [Prompt caching multipliers](https://platform.claude.com/docs/en/about-claude/pricing#prompt-caching) apply identically. Web search triggered inside a session incurs the standard $10 USD per 1,000 searches. On Claude Platform on AWS, session token and runtime charges convert to Claude Consumption Units at the standard rate (see [Claude Platform on AWS pricing](https://platform.claude.com/docs/en/about-claude/pricing#claude-platform-on-aws-pricing)). [Fast mode premium pricing](https://platform.claude.com/docs/en/about-claude/pricing#fast-mode-pricing) applies when an agent's `model.speed` is set to `"fast"`.

420420

421The [data residency multiplier](https://platform.claude.com/docs/en/about-claude/pricing#data-residency-pricing) also applies: when an agent's `model.inference_geo` is pinned to `"us"`, tokens consumed by sessions running that agent are billed at 1.1x the standard rates, the same multiplier that applies to US-only inference on the Messages API.

421The [data residency multiplier](https://platform.claude.com/docs/en/about-claude/pricing#data-residency-pricing) also applies: when an agent’s `model.inference_geo` is pinned to `"us"`, tokens consumed by sessions running that agent are billed at 1.1x the standard rates, the same multiplier that applies to US-only inference on the Messages API.

422422

423423The following Messages API modifiers do **not** apply to Claude Managed Agents sessions:

424424

425| Modifier | Why it doesn't apply |

425| Modifier | Why it doesn’t apply |

426426| --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |

427427| [Batch API discount](https://platform.claude.com/docs/en/about-claude/pricing#batch-processing) | Sessions are stateful and interactive. There is no batch mode. |

428428| [Cloud platform pricing](https://platform.claude.com/docs/en/about-claude/pricing#cloud-platform-pricing) | Not available on partner-operated cloud platforms. |

from line 433

433433| --------------- | -------------------------- | ------------------------- |

434434| Session runtime | $0.08 USD per session-hour | `running` status duration |

435435

436Runtime is measured to the millisecond and accrues only while the session's status is `running`. Time spent `idle` (waiting for your next message or a tool confirmation), `rescheduling`, or `terminated` does not count toward runtime.

436Runtime is measured to the millisecond and accrues only while the session’s status is `running`. Time spent `idle` (waiting for your next message or a tool confirmation), `rescheduling`, or `terminated` does not count toward runtime.

437437

438438<Note>

439439 Session runtime replaces the [code execution](https://platform.claude.com/docs/en/about-claude/pricing#code-execution-tool) container-hour billing model when using Claude Managed Agents. You are not separately billed for container hours on top of session runtime.

from line 517

517517

518518### How is token usage calculated?

519519

520Tokens are pieces of text that models process. How many tokens the same text produces depends on the model's tokenizer, the language, and the type of content. Claude 4.7 and later models and Claude Mythos Preview use a newer tokenizer that produces approximately 30 percent more tokens for the same text than earlier models. To see how many tokens a request uses on a specific model, count it with [token counting](https://platform.claude.com/docs/en/build-with-claude/token-counting) and that model's ID.

520Tokens are pieces of text that models process. How many tokens the same text produces depends on the model’s tokenizer, the language, and the type of content. Claude 4.7 and later models and Claude Mythos Preview use a newer tokenizer that produces approximately 30 percent more tokens for the same text than earlier models. To see how many tokens a request uses on a specific model, count it with [token counting](https://platform.claude.com/docs/en/build-with-claude/token-counting) and that model’s ID.

521521

522522### Are there free tiers or trials?

523523

about-claude/use-case-guides/commerce-agents Changed · +4 / -4 lines

from line 4

44description: Build a shopping agent and a merchant agent on Claude using Claude for commerce, an open-source blueprint with working implementations on the Messages API, the Claude Agent SDK, and Claude Managed Agents.

55---

7This guide shows how to build commerce agents on Claude: a shopping agent that customers use inside your app, and a merchant agent for the people running the store, whether that is the business's own operations staff or the sellers on its platform. It does that through Claude for commerce, an open-source blueprint that includes the following:

7This guide shows how to build commerce agents on Claude: a shopping agent that customers use inside your app, and a merchant agent for the people running the store, whether that is the business’s own operations staff or the sellers on its platform. It does that through Claude for commerce, an open-source blueprint that includes the following:

99* A working implementation of each agent on the [Messages API](https://platform.claude.com/docs/en/build-with-claude/working-with-messages), the [Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview), and [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview)

1010* Runnable examples for retail, travel, telecom, and entertainment

from line 38

3838* Explain how the business is doing: why a metric moved, which segment drove it, and pace against a comparable period. An optional analysis delegate runs read-only queries under a time and size budget.

3939* Present a daily digest of what needs attention, including low stock, slow movers, and order exceptions.

4040* Improve listing content and fix catalog data from material the operator supplies.

41* Recommend price changes and promotions within the store's guardrails, with a margin preview.

41* Recommend price changes and promotions within the store’s guardrails, with a margin preview.

4242* Draft marketing campaigns with audiences, placements, and budget.

4343

4444Its five skills cover performance insights, inventory and operations, catalog and listings, pricing and promotions, and marketing campaigns.

from line 58

5858

5959## Where it runs

6060

61The Messages API and Agent SDK runtimes run against the Claude API, [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed), or [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry), or through your own gateway. The Claude Managed Agents path runs on the Claude API. The repository's deployment guide shows where each path selects its platform and which model ID format each expects.

61The Messages API and Agent SDK runtimes run against the Claude API, [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed), or [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry), or through your own gateway. The Claude Managed Agents path runs on the Claude API. The repository’s deployment guide shows where each path selects its platform and which model ID format each expects.

6262

6363## Build your own with the Claude Code plugin

6464

from line 73

7373

7474The plugin also carries six skills on the architecture, prompt caching, UI as tools, trust and safety, evals, and merchant operations, which load whenever a Claude Code conversation matches them. Installation instructions are in the repository README.

7575

76To adapt the reference by hand instead, implement the shopping or merchant backend interface over your services, switch off the systems you don't have with the configuration flags so their tools and prompt lines drop out, and set your brand name, assistant name, and voice. The repository's backend guide walks through identity and credentials, ordered flows, checkout hand-off, and products with options. A pilot can implement search and product details and stub the rest.

76To adapt the reference by hand instead, implement the shopping or merchant backend interface over your services, switch off the systems you don’t have with the configuration flags so their tools and prompt lines drop out, and set your brand name, assistant name, and voice. The repository’s backend guide walks through identity and credentials, ordered flows, checkout hand-off, and products with options. A pilot can implement search and product details and stub the rest.

7777

7878## Get started

7979

about-claude/use-case-guides/content-moderation Changed · +10 / -10 lines

from line 7

77> Visit the [content moderation recipe](https://platform.claude.com/cookbook/misc-building-moderation-filter) in the Claude Cookbook to see an example content moderation implementation using Claude.

99<Tip>

10 This guide is focused on moderating user-generated content within your application. If you're looking for guidance on moderating interactions with Claude, refer to

10 This guide is focused on moderating user-generated content within your application. If you’re looking for guidance on moderating interactions with Claude, refer to

1111

1212 [Mitigate jailbreaks and prompt injections](https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks)

1313

from line 46

4646 </Accordion>

4747

4848 <Accordion title="You need multimodal support">

49 Claude's multimodal capabilities allow it to analyze and interpret content across both text and images. This makes it a versatile tool for comprehensive content moderation in environments where different media types need to be evaluated together.

49 Claude’s multimodal capabilities allow it to analyze and interpret content across both text and images. This makes it a versatile tool for comprehensive content moderation in environments where different media types need to be evaluated together.

5050 </Accordion>

5151</AccordionGroup>

5252

from line 310

310310 ```

311311</CodeGroup>

312312

313Effectively moderating these examples requires a nuanced understanding of language. In the comment, `This movie was great, I really enjoyed it. The main actor really killed it!`, the content moderation system needs to recognize that "killed it" is a metaphor, not an indication of actual violence. Conversely, despite the lack of explicit mentions of violence, the comment `Delete this post now or you better hide. I am coming after you and your family.` should be flagged by the content moderation system.

313Effectively moderating these examples requires a nuanced understanding of language. In the comment, `This movie was great, I really enjoyed it. The main actor really killed it!`, the content moderation system needs to recognize that “killed it” is a metaphor, not an indication of actual violence. Conversely, despite the lack of explicit mentions of violence, the comment `Delete this post now or you better hide. I am coming after you and your family.` should be flagged by the content moderation system.

314314

315The unsafe categories can be customized to fit your specific needs. For example, if you want to prevent minors from creating content on your website, you could add "Underage Posting" to the categories.

315The unsafe categories can be customized to fit your specific needs. For example, if you want to prevent minors from creating content on your website, you could add “Underage Posting” to the categories.

316316

317317***

318318

from line 873

873873

874874In this example, the `moderate_message` function contains an assessment prompt that includes the unsafe content categories and the message to evaluate. The prompt asks Claude to assess whether the message should be moderated, based on the unsafe categories you defined earlier.

875875

876The model's assessment is then parsed to determine if there is a violation. If there is a violation, Claude also returns a list of violated categories and an explanation as to why the message is unsafe.

876The model’s assessment is then parsed to determine if there is a violation. If there is a violation, Claude also returns a list of violated categories and an explanation as to why the message is unsafe.

877877

878878### Evaluate your prompt

879879

880Content moderation is a classification problem. Thus, you can use the same techniques outlined in the Claude Cookbook's [classification recipe](https://platform.claude.com/cookbook/capabilities-classification-guide) to determine the accuracy of your content moderation system.

880Content moderation is a classification problem. Thus, you can use the same techniques outlined in the Claude Cookbook’s [classification recipe](https://platform.claude.com/cookbook/capabilities-classification-guide) to determine the accuracy of your content moderation system.

881881

882882One additional consideration is that instead of treating content moderation as a binary classification problem, you can create multiple categories to represent various risk levels. Creating multiple risk levels allows you to adjust the aggressiveness of your moderation. For example, you might want to automatically block user queries that are deemed high risk, whereas users with many medium risk queries are flagged for human review.

883883

from line 1433

14331433

14341434### Deploy your prompt

14351435

1436Once you are confident in the quality of your solution, it's time to deploy it to production. Here are some best practices to follow when using content moderation in production:

1436Once you are confident in the quality of your solution, it’s time to deploy it to production. Here are some best practices to follow when using content moderation in production:

14371437

143814381. **Provide clear feedback to users:** When user input is blocked or a response is flagged because of content moderation, provide informative and constructive feedback to help users understand why their message was flagged and how they can rephrase it appropriately. In the earlier coding examples, this is done through the `explanation` field in the Claude response.

14391439

from line 2190

21902190

21912191### Consider batch processing

21922192

2193To reduce costs in situations where real-time moderation isn't necessary, consider moderating messages in batches. Include multiple messages within the prompt's context, and ask Claude to assess which messages should be moderated.

2193To reduce costs in situations where real-time moderation isn’t necessary, consider moderating messages in batches. Include multiple messages within the prompt’s context, and ask Claude to assess which messages should be moderated.

21942194

21952195<CodeGroup exclude="shell">

21962196 ```python Python

from line 2728

27282728 ```

27292729</CodeGroup>

27302730

2731In this example, the `batch_moderate_messages` function handles the moderation of an entire batch of messages with a single Claude API call. Inside the function, a prompt is created that includes the list of messages to evaluate and the unsafe content categories. The prompt directs Claude to return a JSON object listing all messages that contain violations. Each message in the response is identified by its `id`, which corresponds to the message's position in the batch. Keep in mind that finding the optimal batch size for your specific needs might require some experimentation. Although larger batch sizes can lower costs, they might also lead to a slight decrease in quality. Additionally, you might need to increase the `max_tokens` parameter in the Claude API call to accommodate longer responses. For details on the maximum number of tokens your chosen model can output, refer to the [model comparison table](https://platform.claude.com/docs/en/models/overview#latest-models-comparison).

2731In this example, the `batch_moderate_messages` function handles the moderation of an entire batch of messages with a single Claude API call. Inside the function, a prompt is created that includes the list of messages to evaluate and the unsafe content categories. The prompt directs Claude to return a JSON object listing all messages that contain violations. Each message in the response is identified by its `id`, which corresponds to the message’s position in the batch. Keep in mind that finding the optimal batch size for your specific needs might require some experimentation. Although larger batch sizes can lower costs, they might also lead to a slight decrease in quality. Additionally, you might need to increase the `max_tokens` parameter in the Claude API call to accommodate longer responses. For details on the maximum number of tokens your chosen model can output, refer to the [model comparison table](https://platform.claude.com/docs/en/models/overview#latest-models-comparison).

27322732

27332733<CardGroup cols={2}>

27342734 <Card title="Content moderation recipe" icon="link" href="https://platform.claude.com/cookbook/misc-building-moderation-filter">

about-claude/use-case-guides/customer-support-chat Changed · +19 / -19 lines

from line 41

4141 </Accordion>

4242

4343 <Accordion title="Consistent brand voice">

44 You can instruct Claude to consistently represent your brand's tone and values, whereas human agents might vary in their communication styles.

44 You can instruct Claude to consistently represent your brand’s tone and values, whereas human agents might vary in their communication styles.

4545 </Accordion>

4646</AccordionGroup>

4747

4848Some considerations for choosing Claude over other LLMs:

4949

50* You prioritize natural, nuanced conversation: Claude's sophisticated language understanding allows for more natural, context-aware conversations that feel more human-like than chats with other LLMs.

50* You prioritize natural, nuanced conversation: Claude’s sophisticated language understanding allows for more natural, context-aware conversations that feel more human-like than chats with other LLMs.

5151* You often receive complex and open-ended queries: Claude can handle a wide range of topics and inquiries without generating scripted responses or requiring extensive programming of permutations of user utterances.

52* You need scalable multilingual support: Claude's multilingual capabilities allow it to engage in conversations in over 200 languages without the need for separate chatbots or extensive translation processes for each supported language.

52* You need scalable multilingual support: Claude’s multilingual capabilities allow it to engage in conversations in over 200 languages without the need for separate chatbots or extensive translation processes for each supported language.

5353

5454### Define your ideal chat interaction

5555

from line 137

137137 </Accordion>

138138

139139 <Accordion title="Response relevance">

140 This assesses how well Claude's response addresses the customer's specific question or issue. Evaluate a set of conversations and rate the relevance of each response (using LLM-based grading for scale). Target a relevance score of 90 percent or above.

140 This assesses how well Claude’s response addresses the customer’s specific question or issue. Evaluate a set of conversations and rate the relevance of each response (using LLM-based grading for scale). Target a relevance score of 90 percent or above.

141141 </Accordion>

142142

143143 <Accordion title="Response accuracy">

from line 149

149149 </Accordion>

150150

151151 <Accordion title="Topic adherence">

152 Measure how well Claude stays on topic, such as the topic of car insurance in the example implementation. Aim for 95 percent of responses to be directly related to car insurance or the customer's specific query.

153153 </Accordion>

154154

155155 <Accordion title="Content generation effectiveness">

from line 157

157157 </Accordion>

158158

159159 <Accordion title="Escalation efficiency">

160 This measures Claude's ability to recognize when a query needs human intervention and escalate appropriately. Track the percentage of correctly escalated conversations versus those that should have been escalated but weren't. Aim for an escalation accuracy of 95 percent or higher.

160 This measures Claude’s ability to recognize when a query needs human intervention and escalate appropriately. Track the percentage of correctly escalated conversations versus those that should have been escalated but weren’t. Aim for an escalation accuracy of 95 percent or higher.

161161 </Accordion>

162162</AccordionGroup>

163163

from line 165

165165

166166<AccordionGroup>

167167 <Accordion title="Sentiment maintenance">

168 This assesses Claude's ability to maintain or improve customer sentiment throughout the conversation. Use sentiment analysis tools to measure sentiment at the beginning and end of each conversation. Aim for maintained or improved sentiment in 90 percent of interactions.

168 This assesses Claude’s ability to maintain or improve customer sentiment throughout the conversation. Use sentiment analysis tools to measure sentiment at the beginning and end of each conversation. Aim for maintained or improved sentiment in 90 percent of interactions.

169169 </Accordion>

170170

171171 <Accordion title="Deflection rate">

from line 214

214214 .

215215</Tip>

216216

217It's best to break down complex prompts into subsections and write one part at a time. For each task, you might find greater success by following a step-by-step process to define the parts of the prompt Claude would need to do the task well. For this car insurance customer support example, you'll be writing piecemeal all the parts for a prompt starting with the "Greeting and general guidance" task. This also makes debugging your prompt easier as you can more quickly adjust individual parts of the overall prompt.

217It’s best to break down complex prompts into subsections and write one part at a time. For each task, you might find greater success by following a step-by-step process to define the parts of the prompt Claude would need to do the task well. For this car insurance customer support example, you’ll be writing piecemeal all the parts for a prompt starting with the “Greeting and general guidance” task. This also makes debugging your prompt easier as you can more quickly adjust individual parts of the overall prompt.

218218

219219```python

220220STATIC_GREETINGS_AND_GENERAL = """

from line 280

280280"""

281281```

282282

283Now that you have your static content, add at least 4–5 sample "good" interactions to guide Claude's responses. These examples should be representative of your ideal customer interaction and can include elements such as guardrails and tool calls.

283Now that you have your static content, add at least 4–5 sample “good” interactions to guide Claude’s responses. These examples should be representative of your ideal customer interaction and can include elements such as guardrails and tool calls.

284284

285285```python

286286EXAMPLES = """

from line 349

349349"""

350350```

351351

352Also include any important instructions outlining dos and don'ts for how Claude should interact with the customer. This might draw from brand guardrails or support policies.

352Also include any important instructions outlining dos and don’ts for how Claude should interact with the customer. This might draw from brand guardrails or support policies.

353353

354354```python

355355ADDITIONAL_GUARDRAILS = """Please adhere to the following guardrails:

from line 432

432432

433433### Deploy your prompts

434434

435It's hard to know how well your prompt works without deploying it in a test production setting and [running evaluations](https://platform.claude.com/docs/en/test-and-evaluate/develop-tests). Build a small application using the prompt, the Anthropic SDK, and Streamlit for a user interface.

435It’s hard to know how well your prompt works without deploying it in a test production setting and [running evaluations](https://platform.claude.com/docs/en/test-and-evaluate/develop-tests). Build a small application using the prompt, the Anthropic SDK, and Streamlit for a user interface.

436436

437437In a file called `chatbot.py` (or the equivalent module in your language), set up the ChatBot class, which will encapsulate the interactions with the Anthropic SDK.

438438

from line 1141

11411141

11421142#### Integrate real-time data with tool use

11431143

1144When dealing with queries that require real-time information, such as account balances or policy details, embedding-based RAG approaches are not sufficient. Instead, tool use can enhance your chatbot's ability to provide accurate, real-time responses. For example, you can use tool use to look up customer information, retrieve order details, and cancel orders on behalf of the customer.

1144When dealing with queries that require real-time information, such as account balances or policy details, embedding-based RAG approaches are not sufficient. Instead, tool use can enhance your chatbot’s ability to provide accurate, real-time responses. For example, you can use tool use to look up customer information, retrieve order details, and cancel orders on behalf of the customer.

11451145

1146This approach, outlined in the [tool use: customer service agent recipe](https://platform.claude.com/cookbook/tool-use-customer-service-agent), lets you integrate live data into Claude's responses and provide a more personalized and efficient customer experience.

1146This approach, outlined in the [tool use: customer service agent recipe](https://platform.claude.com/cookbook/tool-use-customer-service-agent), lets you integrate live data into Claude’s responses and provide a more personalized and efficient customer experience.

11471147

11481148#### Strengthen input and output guardrails

11491149

1150When deploying a chatbot, especially in customer service scenarios, it's important to prevent risks associated with misuse, out-of-scope queries, and inappropriate responses. Although Claude is inherently resilient to such scenarios, here are additional steps to strengthen your chatbot guardrails:

1150When deploying a chatbot, especially in customer service scenarios, it’s important to prevent risks associated with misuse, out-of-scope queries, and inappropriate responses. Although Claude is inherently resilient to such scenarios, here are additional steps to strengthen your chatbot guardrails:

11511151

11521152* [Reduce hallucination](https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/reduce-hallucinations): Implement fact-checking mechanisms and [citations](https://platform.claude.com/cookbook/misc-using-citations) to ground responses in provided information.

1153* Cross-check information: Verify that the agent's responses align with your company's policies and known facts.

1154* Avoid contractual commitments: Ensure the agent doesn't make promises or enter into agreements it's not authorized to make.

1153* Cross-check information: Verify that the agent’s responses align with your company’s policies and known facts.

1154* Avoid contractual commitments: Ensure the agent doesn’t make promises or enter into agreements it’s not authorized to make.

11551155* [Mitigate jailbreaks](https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks): Use methods such as harmlessness screens and input validation to prevent users from exploiting model vulnerabilities to generate inappropriate content.

1156* Avoid mentioning competitors: Implement a competitor mention filter to maintain brand focus and not mention any competitor's products or services.

1156* Avoid mentioning competitors: Implement a competitor mention filter to maintain brand focus and not mention any competitor’s products or services.

11571157* [Increase output consistency](https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/increase-consistency): Prevent Claude from changing style or going out of character, even during long, complex interactions.

11581158* Remove personally identifiable information (PII): Unless explicitly required and authorized, strip out any PII from responses.

11591159

from line 1183

11831183

11841184Although these examples have focused on Python functions callable within a Streamlit environment, deploying Claude for a real-time support chatbot requires an API service.

11851185

1186Here's how you can approach this:

1186Here’s how you can approach this:

11871187

118811881. Create an API wrapper: Develop a simple API wrapper around your classification function. For example, you can use Flask or FastAPI to wrap your code into an HTTP service. Your HTTP service could accept the user input and return the Assistant response in its entirety. Thus, your service could have the following characteristics:

11891189

about-claude/use-case-guides/legal-summarization Changed · +9 / -9 lines

from line 18

1818 </Accordion>

1919

2020 <Accordion title="You need automated extraction of key metadata">

21 Claude can efficiently extract and categorize important metadata from legal documents, such as parties involved, dates, contract terms, or specific clauses. This automated extraction can help organize information, making it easier to search, analyze, and manage large document sets. It's especially useful for contract management, compliance checks, or creating searchable databases of legal information.

21 Claude can efficiently extract and categorize important metadata from legal documents, such as parties involved, dates, contract terms, or specific clauses. This automated extraction can help organize information, making it easier to search, analyze, and manage large document sets. It’s especially useful for contract management, compliance checks, or creating searchable databases of legal information.

2222 </Accordion>

2323

2424 <Accordion title="You want to generate clear, concise, and standardized summaries">

from line 169

169169

170170* **Estimated tokens**

171171

172 * Input tokens: 108M, about 108,000 per agreement (about 1 token per 2.8 characters, the rate both models showed on this guide's sample agreement)

172 * Input tokens: 108M, about 108,000 per agreement (about 1 token per 2.8 characters, the rate both models showed on this guide’s sample agreement)

173173 * Output tokens per summary, including any thinking tokens, which are billed as output: about 6,200 on Claude Opus 5.5 and 3,100 on Claude Haiku 5.5

174174 * Total output tokens: 6.2M on Claude Opus 5.5 and 3.1M on Claude Haiku 5.5

175175

from line 190

190190

191191 [Build a strong prompt](https://platform.claude.com/docs/en/about-claude/use-case-guides/legal-summarization#build-a-strong-prompt)

192192

193 section on this guide's sample agreement, about 105,000 input tokens, and output length varies with the document and from run to run. Each agreement here is one prompt of about 108,000 tokens, over the 100,000-token threshold of Claude Haiku 5.5's

193 section on this guide’s sample agreement, about 105,000 input tokens, and output length varies with the document and from run to run. Each agreement here is one prompt of about 108,000 tokens, over the 100,000-token threshold of Claude Haiku 5.5’s

194194

195195 [long-prompt prices](https://platform.claude.com/docs/en/about-claude/pricing#long-context-pricing)

196196

from line 211

211211

212212### Transform documents into a format that Claude can process

213213

214Before you start summarizing documents, you need to prepare your data. This involves extracting text from PDFs, cleaning the text, and ensuring it's ready to be processed by Claude.

214Before you start summarizing documents, you need to prepare your data. This involves extracting text from PDFs, cleaning the text, and ensuring it’s ready to be processed by Claude.

215215

216216Here is a demonstration of this process on a sample PDF:

217217

from line 465

465465 ```

466466</CodeGroup>

467467

468In this example, you first download a PDF of a sample sublease agreement used in the Claude Cookbook's [summarization recipe](https://platform.claude.com/cookbook/capabilities-summarization-guide). This agreement was sourced from a publicly available sublease agreement from the [sec.gov website](https://www.sec.gov/Archives/edgar/data/1045425/000119312507044370/dex1032.htm).

468In this example, you first download a PDF of a sample sublease agreement used in the Claude Cookbook’s [summarization recipe](https://platform.claude.com/cookbook/capabilities-summarization-guide). This agreement was sourced from a publicly available sublease agreement from the [sec.gov website](https://www.sec.gov/Archives/edgar/data/1045425/000119312507044370/dex1032.htm).

469469

470470The example uses the `pypdf` (typescript: `pdf-parse`; csharp: `PdfPig`; go: `github.com/ledongthuc/pdf`; java: `org.apache.pdfbox:pdfbox`; php: `smalot/pdfparser`; ruby: `pdf-reader`) library to extract the contents of the PDF and convert it to text. The text data is then cleaned by removing page numbers and extra whitespace.

471471

from line 887

887887

888888Legal summarization often involves handling long documents or many related documents at once, such that you surpass Claude’s context window. You can use a chunking method known as meta-summarization to handle this use case. This technique involves breaking down documents into smaller, manageable chunks and then processing each chunk separately. You can then combine the summaries of each chunk to create a meta-summary of the entire document.

889889

890Here's an example of how to perform meta-summarization:

890Here’s an example of how to perform meta-summarization:

891891

892892<CodeGroup exclude="shell">

893893 <CodeGroupItem language="cURL">

from line 1327

13271327

13281328The code achieves this by applying the `summarize_document()` (typescript, go, java: `summarizeDocument()`; php: `$summarizeDocument()`; csharp: `SummarizeDocument()`) function to each chunk of 20,000 characters within the original document. The individual summaries are then combined, and a final summary is created from these chunk summaries.

13291329

1330Note that the `summarize_long_document()` (typescript, go, java: `summarizeLongDocument()`; php: `$summarizeLongDocument()`; csharp: `SummarizeLongDocument()`) function isn't strictly necessary for the example PDF, as the entire document fits within Claude's context window. However, it becomes essential for documents exceeding Claude's context window or when summarizing multiple related documents together. Regardless, this meta-summarization technique often captures additional important details in the final summary that were missed in the earlier single-summary approach.

1330Note that the `summarize_long_document()` (typescript, go, java: `summarizeLongDocument()`; php: `$summarizeLongDocument()`; csharp: `SummarizeLongDocument()`) function isn’t strictly necessary for the example PDF, as the entire document fits within Claude’s context window. However, it becomes essential for documents exceeding Claude’s context window or when summarizing multiple related documents together. Regardless, this meta-summarization technique often captures additional important details in the final summary that were missed in the earlier single-summary approach.

13311331

13321332### Use summary indexed documents to explore a large collection of documents

13331333

from line 1335

13351335

13361336### Fine-tune Claude to learn from your dataset

13371337

1338Another advanced technique to improve Claude's ability to generate summaries is fine-tuning. Fine-tuning involves training Claude on a custom dataset that specifically aligns with your legal summarization needs, ensuring that Claude adapts to your use case. Here’s an overview on how to perform fine-tuning:

1338Another advanced technique to improve Claude’s ability to generate summaries is fine-tuning. Fine-tuning involves training Claude on a custom dataset that specifically aligns with your legal summarization needs, ensuring that Claude adapts to your use case. Here’s an overview on how to perform fine-tuning:

13391339

134013401. **Identify errors:** Start by collecting instances where Claude’s summaries are inadequate. This could include missing critical legal details, misunderstanding context, or using inappropriate legal terminology.

13411341

13422. **Curate a dataset:** Once you've identified these issues, compile a dataset of these problematic examples. This dataset should include the original legal documents alongside your corrected summaries, ensuring that Claude learns the behavior you want.

13422. **Curate a dataset:** Once you’ve identified these issues, compile a dataset of these problematic examples. This dataset should include the original legal documents alongside your corrected summaries, ensuring that Claude learns the behavior you want.

13431343

134413443. **Perform fine-tuning:** Fine-tuning involves retraining the model on your curated dataset to adjust its weights and parameters. This retraining helps Claude better adapt to the specific requirements of your legal domain, improving its ability to summarize documents according to your standards.

13451345

about-claude/use-case-guides/ticket-routing Changed · +19 / -19 lines

from line 16

1616

1717<AccordionGroup>

1818 <Accordion title="You have limited labeled training data available">

19 Traditional ML processes require massive labeled datasets. Claude's pre-trained model can effectively classify tickets with just a few dozen labeled examples, significantly reducing data preparation time and costs.

19 Traditional ML processes require massive labeled datasets. Claude’s pre-trained model can effectively classify tickets with just a few dozen labeled examples, significantly reducing data preparation time and costs.

2020 </Accordion>

2121

2222 <Accordion title="Your classification categories are likely to change or evolve over time">

from line 24

2424 </Accordion>

2525

2626 <Accordion title="You need to handle complex, unstructured text inputs">

27 Traditional ML models often struggle with unstructured data and require extensive feature engineering. Claude's advanced language understanding allows for accurate classification based on content and context, rather than relying on strict ontological structures.

27 Traditional ML models often struggle with unstructured data and require extensive feature engineering. Claude’s advanced language understanding allows for accurate classification based on content and context, rather than relying on strict ontological structures.

2828 </Accordion>

2929

3030 <Accordion title="Your classification rules are based on semantic understanding">

from line 36

3636 </Accordion>

3737

3838 <Accordion title="You want to handle edge cases and ambiguous tickets more effectively">

39 Traditional ML systems often struggle with outliers and ambiguous inputs, frequently misclassifying them or defaulting to a catch-all category. Claude's natural language processing capabilities allow it to better interpret context and nuance in support tickets, potentially reducing the number of misrouted or unclassified tickets that require manual intervention.

39 Traditional ML systems often struggle with outliers and ambiguous inputs, frequently misclassifying them or defaulting to a catch-all category. Claude’s natural language processing capabilities allow it to better interpret context and nuance in support tickets, potentially reducing the number of misrouted or unclassified tickets that require manual intervention.

4040 </Accordion>

4141

4242 <Accordion title="You need multilingual support without maintaining separate models">

43 Traditional ML approaches typically require separate models or extensive translation processes for each supported language. Claude's multilingual capabilities allow it to classify tickets in various languages without the need for separate models or extensive translation processes, streamlining support for global customer bases.

43 Traditional ML approaches typically require separate models or extensive translation processes for each supported language. Claude’s multilingual capabilities allow it to classify tickets in various languages without the need for separate models or extensive translation processes, streamlining support for global customer bases.

4444 </Accordion>

4545</AccordionGroup>

4646

from line 50

5050

5151### Understand your current support approach

5252

53Before you automate, it's crucial to understand your existing ticketing system. Start by investigating how your support team currently handles ticket routing.

53Before you automate, it’s crucial to understand your existing ticketing system. Start by investigating how your support team currently handles ticket routing.

5454

5555Consider questions such as:

5656

from line 159

159159

160160<AccordionGroup>

161161 <Accordion title="Classification consistency">

162 This metric assesses how consistently Claude classifies similar tickets over time. It's crucial for maintaining routing reliability. Measure this by periodically testing the model with a set of standardized inputs and aiming for a consistency rate of 95 percent or higher.

162 This metric assesses how consistently Claude classifies similar tickets over time. It’s crucial for maintaining routing reliability. Measure this by periodically testing the model with a set of standardized inputs and aiming for a consistency rate of 95 percent or higher.

163163 </Accordion>

164164

165165 <Accordion title="Adaptation speed">

from line 167

167167 </Accordion>

168168

169169 <Accordion title="Multilingual handling">

170 This assesses Claude's ability to accurately route tickets in multiple languages. Measure the routing accuracy across different languages, aiming for no more than a 5–10 percent drop in accuracy for non-primary languages.

170 This assesses Claude’s ability to accurately route tickets in multiple languages. Measure the routing accuracy across different languages, aiming for no more than a 5–10 percent drop in accuracy for non-primary languages.

171171 </Accordion>

172172

173173 <Accordion title="Edge case handling">

174 This evaluates Claude's performance on unusual or complex tickets. Create a test set of edge cases and measure the routing accuracy, aiming for at least 80 percent accuracy on these challenging inputs.

174 This evaluates Claude’s performance on unusual or complex tickets. Create a test set of edge cases and measure the routing accuracy, aiming for at least 80 percent accuracy on these challenging inputs.

175175 </Accordion>

176176

177177 <Accordion title="Bias mitigation">

178 This measures Claude's fairness in routing across different customer demographics. Regularly audit routing decisions for potential biases, aiming for consistent routing accuracy (within 2–3 percent) across all customer groups.

178 This measures Claude’s fairness in routing across different customer demographics. Regularly audit routing decisions for potential biases, aiming for consistent routing accuracy (within 2–3 percent) across all customer groups.

179179 </Accordion>

180180

181181 <Accordion title="Prompt efficiency">

from line 183

183183 </Accordion>

184184

185185 <Accordion title="Explainability score">

186 This evaluates the quality and relevance of Claude's explanations for its routing decisions. Human raters can score explanations on a scale (for example, 1–5), with the goal of achieving an average score of 4 or higher.

186 This evaluates the quality and relevance of Claude’s explanations for its routing decisions. Human raters can score explanations on a scale (for example, 1–5), with the goal of achieving an average score of 4 or higher.

187187 </Accordion>

188188</AccordionGroup>

189189

from line 235

235235

236236The choice of model depends on the trade-offs among cost, accuracy, and response time.

237237

238Claude Haiku 5.5 (`claude-haiku-5-5`) suits ticket routing: it's the fastest and most cost-effective current model, and at `low` effort it handles simple, high-volume requests such as classification. If your classification problem requires deep subject matter expertise, a large volume of intent categories, or complex reasoning, you may opt for the [larger Sonnet model](https://platform.claude.com/docs/en/models/overview).

238Claude Haiku 5.5 (`claude-haiku-5-5`) suits ticket routing: it’s the fastest and most cost-effective current model, and at `low` effort it handles simple, high-volume requests such as classification. If your classification problem requires deep subject matter expertise, a large volume of intent categories, or complex reasoning, you may opt for the [larger Sonnet model](https://platform.claude.com/docs/en/models/overview).

239239

240240### Build a strong prompt

241241

from line 247

247247 Try the [metaprompt recipe from the Claude Cookbook](https://colab.research.google.com/github/anthropics/claude-cookbooks/blob/main/misc/metaprompt.ipynb) to have Claude write a first draft for you.

248248</Tip>

249249

250Here's an example ticket routing classification prompt:

250Here’s an example ticket routing classification prompt:

251251

252252<CodeGroup exclude="shell">

253253 <CodeGroupItem language="cURL">

from line 678

678678Here are the key components of this prompt:

679679

680680* The prompt template inserts `ticket_contents` (typescript, csharp, go, java: `ticketContents`; php: `$ticketContents`) into the `<request>` tags.

681* The prompt gives Claude a clearly defined role as a classification system that carefully analyzes the ticket content to determine the customer's core intent and needs.

681* The prompt gives Claude a clearly defined role as a classification system that carefully analyzes the ticket content to determine the customer’s core intent and needs.

682682* The prompt instructs Claude on proper output formatting, in this case to provide its reasoning and analysis inside `<reasoning>` tags, followed by the appropriate classification label inside `<intent>` tags.

683* The prompt specifies the valid intent categories: "Support, Feedback, Complaint", "Order Tracking", and "Refund/Exchange".

683* The prompt specifies the valid intent categories: `Support, Feedback, Complaint`, `Order Tracking`, and `Refund/Exchange`.

684684* The prompt includes a few examples (a.k.a. few-shot prompting) to illustrate how the output should be formatted, which improves accuracy and consistency.

685685

686686Having Claude split its response into separate XML tag sections lets you use regular expressions to extract the reasoning and intent from the output independently. This lets you create targeted next steps in the ticket routing workflow, such as using only the intent to decide which person to route the ticket to.

from line 689

689689

690690It’s hard to know how well your prompt works without deploying it in a test production setting and [running evaluations](https://platform.claude.com/docs/en/test-and-evaluate/develop-tests).

691691

692Build the deployment structure. Start by defining the function signature for wrapping the call to Claude. Extend the function you started writing earlier, which takes `ticket_contents` (typescript, csharp, go, java: `ticketContents`; php: `$ticketContents`) as input, so that it now returns the reasoning and the intent as output. If you have an existing automation using traditional ML, you'll want to follow that signature instead.

693693

694694<CodeGroup exclude="shell">

695695 <CodeGroupItem language="cURL">

from line 1016

10161016* Creates a client instance using your API key.

10171017* Defines a `classify_support_request()` (typescript, go, java, php: `classifySupportRequest()`; csharp: `ClassifySupportRequest()`) function that takes a `ticket_contents` (typescript, csharp, go, java: `ticketContents`; php: `$ticketContents`) string.

10181018* Sends the `ticket_contents` (typescript, csharp, go, java: `ticketContents`; php: `$ticketContents`) to Claude for classification using the `classification_prompt` (typescript, csharp, go, java: `classificationPrompt`; php: `$classificationPrompt`).

1019* Returns the model's reasoning and intent extracted from the response.

1019* Returns the model’s reasoning and intent extracted from the response.

10201020

10211021Because the entire reasoning and intent text must be generated before parsing, the example does not stream the response.

10221022

from line 1037

10371037

10381038You might need to assess Claude on other axes depending on which factors are important to you.

10391039

1040To assess this, first modify the script so that it compares the predicted intent with the actual intent. Then have it return the API call's token usage, from which you can calculate cost.

1040To assess this, first modify the script so that it compares the predicted intent with the actual intent. Then have it return the API call’s token usage, from which you can calculate cost.

10411041

10421042<CodeGroup exclude="shell">

10431043 <CodeGroupItem language="cURL">

from line 1426

142614261. Organize your intents in a taxonomic tree structure.

142714272. Create a series of classifiers at every level of the tree to make a cascading routing approach possible.

14281428

1429For example, you might have a top-level classifier that broadly categorizes tickets into "Technical Issues," "Billing Questions," and "General Inquiries." Each of these categories can then have its own sub-classifier to further refine the classification.

1429For example, you might have a top-level classifier that broadly categorizes tickets into “Technical Issues,” “Billing Questions,” and “General Inquiries.” Each of these categories can then have its own sub-classifier to further refine the classification.

14301430

14311431```mermaid

14321432---

from line 1474

14741474

14751475<AccordionGroup>

14761476 <Accordion title="Customers make implicit requests">

1477 Customers often express needs indirectly. For example, "I've been waiting for my package for over two weeks now" might be an indirect request for order status.

1477 Customers often express needs indirectly. For example, “I’ve been waiting for my package for over two weeks now” might be an indirect request for order status.

14781478

14791479 * **Solution:** Provide Claude with some real customer examples of these kinds of requests, along with what the underlying intent is. You can get even better results if you include a classification rationale for particularly nuanced ticket intents, so that Claude can better generalize the logic to other tickets.

14801480 </Accordion>

agents-and-tools/agent-skills/best-practices Changed · +69 / -69 lines

### Solve, don’t defer ### Solve, don't defer

from line 16

1616

1717* The system prompt

1818* Conversation history

19* Other Skills' metadata

19* Other Skills’ metadata

2020* Your actual request

2121

2222Not every token in your Skill has an immediate cost. At startup, only the metadata (name and description) from all Skills is pre-loaded. Claude reads `SKILL.md` only when the Skill becomes relevant, and reads additional files only as needed. However, being concise in `SKILL.md` still matters: once Claude loads it, every token competes with conversation history and other context.

from line 23

2323

2424**Default assumption:** Claude is already very smart

2525

26Only add context Claude doesn't already have. Challenge each piece of information:

26Only add context Claude doesn’t already have. Challenge each piece of information:

2727

28* "Does Claude really need this explanation?"

29* "Can I assume Claude has this information?"

30* "Does this paragraph justify its token cost?"

28* “Does Claude really need this explanation?”

29* “Can I assume Claude has this information?”

30* “Does this paragraph justify its token cost?”

3131

3232**Good example: Concise** (approximately 50 tokens):

3333

from line 60

6060

6161### Set appropriate degrees of freedom

6262

63Match the level of specificity to the task's fragility and variability.

63Match the level of specificity to the task’s fragility and variability.

6464

6565**High freedom** (text-based instructions):

6666

from line 128

128128

129129**Analogy:** Think of Claude as a robot exploring a path:

130130

131* **Narrow bridge with cliffs on both sides:** There's only one safe way forward. Provide specific guardrails and exact instructions (low freedom). Example: database migrations that must run in exact sequence.

131* **Narrow bridge with cliffs on both sides:** There’s only one safe way forward. Provide specific guardrails and exact instructions (low freedom). Example: database migrations that must run in exact sequence.

132132* **Open field with no hazards:** Many paths lead to success. Give general direction and trust Claude to find the best route (high freedom). Example: code reviews where context determines the best approach.

133133

134134### Test with all models you plan to use

from line 153

153153 * Maximum 64 characters

154154 * Must contain only lowercase letters, numbers, and hyphens

155155 * Cannot contain XML tags

156 * Cannot contain reserved words: "anthropic", "claude"

156 * Cannot contain reserved words: `anthropic`, `claude`

157157

158158 `description`:

159159

from line 205

205205<Warning>

206206 **Always write in third person**. The description is injected into the system prompt, and inconsistent point-of-view can cause discovery problems.

207207

208 * **Good:** "Processes Excel files and generates reports"

209 * **Avoid:** "I can help you process Excel files"

210 * **Avoid:** "You can use this to process Excel files"

208 * **Good:** “Processes Excel files and generates reports”

209 * **Avoid:** “I can help you process Excel files”

210 * **Avoid:** “You can use this to process Excel files”

211211</Warning>

212212

213213**Be specific and include key terms**. Include both what the Skill does and specific triggers/contexts for when to use it.

from line 377

377377

378378### Avoid deeply nested references

379379

380Claude might partially read files when they're referenced from other referenced files. When encountering nested references, Claude might use commands such as `head -100` to preview content rather than reading entire files, resulting in incomplete information.

380Claude might partially read files when they’re referenced from other referenced files. When encountering nested references, Claude might use commands such as `head -100` to preview content rather than reading entire files, resulting in incomplete information.

381381

382382**Keep references one level deep from `SKILL.md`**. All reference files should link directly from `SKILL.md` to ensure Claude reads complete files when needed.

383383

from line 478

478478Check that every claim references the correct source document. If citations are incomplete, return to Step 3.

479479````

480480

481This example shows how workflows apply to analysis tasks that don't require code. The checklist pattern works for any complex, multistep process.

481This example shows how workflows apply to analysis tasks that don’t require code. The checklist pattern works for any complex, multistep process.

482482

483483**Example 2: PDF form filling workflow** (for Skills with code):

484484

from line 549

5495495. Finalize and save the document

550550```

551551

552This shows the validation loop pattern using reference documents instead of scripts. The "validator" is `STYLE_GUIDE.md`, and Claude performs the check by reading and comparing.

552This shows the validation loop pattern using reference documents instead of scripts. The “validator” is `STYLE_GUIDE.md`, and Claude performs the check by reading and comparing.

553553

554554**Example 2: Document editing process** (for Skills with code):

555555

from line 573

573573

574574### Avoid time-sensitive information

575575

576Don't include information that will become outdated:

576Don’t include information that will become outdated:

577577

578578**Bad example: Time-sensitive** (will become wrong):

579579

from line 582

582582After August 2025, use the new API.

583583```

584584

585**Good example** (use "old patterns" section):

585**Good example** (use “old patterns” section):

586586

587587```markdown

588588## Current method

from line 608

608608

609609**Good - Consistent:**

610610

611* Always "API endpoint"

612* Always "field"

613* Always "extract"

611* Always “API endpoint”

612* Always “field”

613* Always “extract”

614614

615615**Bad - Inconsistent:**

616616

617* Mix "API endpoint," "URL," "API route," "path"

618* Mix "field," "box," "element," "control"

619* Mix "extract," "pull," "get," "retrieve"

617* Mix “API endpoint,” “URL,” “API route,” “path”

618* Mix “field,” “box,” “element,” “control”

619* Mix “extract,” “pull,” “get,” “retrieve”

620620

621621Consistency helps Claude parse and follow instructions.

622622

from line 753

753753

7547541. **Identify gaps:** Run Claude on representative tasks without a Skill. Document specific failures or missing context.

7557552. **Create evaluations:** Build three scenarios that test these gaps.

7563. **Establish baseline:** Measure Claude's performance without the Skill.

7563. **Establish baseline:** Measure Claude’s performance without the Skill.

7577574. **Write minimal instructions:** Create just enough content to address the gaps and pass evaluations.

7587585. **Iterate:** Run evaluations, compare against baseline, and refine.

759759

760This approach ensures you're solving actual problems rather than anticipating requirements that might never materialize.

760This approach ensures you’re solving actual problems rather than anticipating requirements that might never materialize.

761761

762762**Evaluation structure:**

763763

from line 780

780780

781781### Develop Skills iteratively with Claude

782782

783The most effective Skill development process involves Claude itself. Work with one instance of Claude ("Claude A") to create a Skill that is used by other instances ("Claude B"). Claude A helps you design and refine instructions, whereas Claude B tests them in real tasks. This works because Claude models can both write effective agent instructions and identify what information agents need.

783The most effective Skill development process involves Claude itself. Work with one instance of Claude (“Claude A”) to create a Skill that is used by other instances (“Claude B”). Claude A helps you design and refine instructions, whereas Claude B tests them in real tasks. This works because Claude models can both write effective agent instructions and identify what information agents need.

784784

785785**Creating a new Skill:**

786786

7871. **Complete a task without a Skill:** Work through a problem with Claude A using normal prompting. As you work, you'll naturally provide context, explain preferences, and share procedural knowledge. Notice what information you repeatedly provide.

7871. **Complete a task without a Skill:** Work through a problem with Claude A using normal prompting. As you work, you’ll naturally provide context, explain preferences, and share procedural knowledge. Notice what information you repeatedly provide.

788788

7897892. **Identify the reusable pattern:** After completing the task, identify what context you provided that would be useful for similar future tasks.

790790

791 **Example:** If you worked through a BigQuery analysis, you might have provided table names, field definitions, filtering rules (such as "always exclude test accounts"), and common query patterns.

791 **Example:** If you worked through a BigQuery analysis, you might have provided table names, field definitions, filtering rules (such as “always exclude test accounts”), and common query patterns.

792792

7933. **Ask Claude A to create a Skill:** "Create a Skill that captures this BigQuery analysis pattern we just used. Include the table schemas, naming conventions, and the rule about filtering test accounts."

7933. **Ask Claude A to create a Skill:** “Create a Skill that captures this BigQuery analysis pattern we just used. Include the table schemas, naming conventions, and the rule about filtering test accounts.”

794794

795795 <Tip>

796 Claude models handle the Skill format and structure natively. You don't need special system prompts or a "writing skills" skill to get Claude to help create Skills. Ask Claude to create a Skill and it generates properly structured `SKILL.md` content with appropriate frontmatter and body content.

796 Claude models handle the Skill format and structure natively. You don’t need special system prompts or a “writing skills” skill to get Claude to help create Skills. Ask Claude to create a Skill and it generates properly structured `SKILL.md` content with appropriate frontmatter and body content.

797797 </Tip>

798798

7994. **Review for conciseness:** Check that Claude A hasn't added unnecessary explanations. Ask: "Remove the explanation about what win rate means - Claude already knows that."

7994. **Review for conciseness:** Check that Claude A hasn’t added unnecessary explanations. Ask: “Remove the explanation about what win rate means - Claude already knows that.”

800800

8015. **Improve information architecture:** Ask Claude A to organize the content more effectively. For example: "Organize this so the table schema is in a separate reference file. We might add more tables later."

8015. **Improve information architecture:** Ask Claude A to organize the content more effectively. For example: “Organize this so the table schema is in a separate reference file. We might add more tables later.”

802802

8038036. **Test on similar tasks:** Use the Skill with Claude B (a fresh instance with the Skill loaded) on related use cases. Observe whether Claude B finds the right information, applies rules correctly, and handles the task successfully.

804804

8057. **Iterate based on observation:** If Claude B struggles or misses something, return to Claude A with specifics: "When Claude used this Skill, it forgot to filter by date for Q4. Should we add a section about date filtering patterns?"

8057. **Iterate based on observation:** If Claude B struggles or misses something, return to Claude A with specifics: “When Claude used this Skill, it forgot to filter by date for Q4. Should we add a section about date filtering patterns?”

806806

807807**Iterating on existing Skills:**

808808

from line 810

810810

811811* **Working with Claude A** (the expert who helps refine the Skill)

812812* **Testing with Claude B** (the agent using the Skill to perform real work)

813* **Observing Claude B's behavior** and bringing insights back to Claude A

813* **Observing Claude B’s behavior** and bringing insights back to Claude A

814814

8158151. **Use the Skill in real workflows:** Give Claude B (with the Skill loaded) actual tasks, not test scenarios.

816816

8172. **Observe Claude B's behavior:** Note where it struggles, succeeds, or makes unexpected choices.

8172. **Observe Claude B’s behavior:** Note where it struggles, succeeds, or makes unexpected choices.

818818

819 **Example observation:** "When I asked Claude B for a regional sales report, it wrote the query but forgot to filter out test accounts, even though the Skill mentions this rule."

819 **Example observation:** “When I asked Claude B for a regional sales report, it wrote the query but forgot to filter out test accounts, even though the Skill mentions this rule.”

820820

8213. **Return to Claude A for improvements:** Share the current `SKILL.md` and describe what you observed. Ask: "I noticed Claude B forgot to filter test accounts when I asked for a regional report. The Skill mentions filtering, but maybe it's not prominent enough?"

8213. **Return to Claude A for improvements:** Share the current `SKILL.md` and describe what you observed. Ask: “I noticed Claude B forgot to filter test accounts when I asked for a regional report. The Skill mentions filtering, but maybe it’s not prominent enough?”

822822

8234. **Review Claude A's recommendations:** Claude A might recommend reorganizing to make rules more prominent, using stronger language such as "MUST filter" instead of "always filter," or restructuring the workflow section.

8234. **Review Claude A’s recommendations:** Claude A might recommend reorganizing to make rules more prominent, using stronger language such as “MUST filter” instead of “always filter,” or restructuring the workflow section.

824824

8255. **Apply and test changes:** Update the Skill with Claude A's refinements, then test again with Claude B on similar requests.

8255. **Apply and test changes:** Update the Skill with Claude A’s refinements, then test again with Claude B on similar requests.

826826

8278276. **Repeat based on usage:** Continue this observe-refine-test cycle as you encounter new scenarios. Each iteration improves the Skill based on real agent behavior, not assumptions.

828828

from line 829

829829**Gathering team feedback:**

830830

8318311. Share Skills with teammates and observe their usage.

8322. Ask: Does the Skill activate when expected? Are instructions clear? What's missing?

8322. Ask: Does the Skill activate when expected? Are instructions clear? What’s missing?

8338333. Incorporate feedback to address gaps in your own usage patterns.

834834

835835**Why this approach works:** Claude A identifies agent needs, you provide domain expertise, Claude B reveals gaps through real usage, and iterative refinement improves Skills based on observed behavior rather than assumptions.

from line 838

838838

839839As you iterate on Skills, pay attention to how Claude actually uses them in practice. Watch for:

840840

841* **Unexpected exploration paths:** Does Claude read files in an order you didn't anticipate? This might indicate your structure isn't as intuitive as you thought.

841* **Unexpected exploration paths:** Does Claude read files in an order you didn’t anticipate? This might indicate your structure isn’t as intuitive as you thought.

842842* **Missed connections:** Does Claude fail to follow references to important files? Your links might need to be more explicit or prominent.

843843* **Overreliance on certain sections:** If Claude repeatedly reads the same file, consider whether that content should be in the main `SKILL.md` instead.

844844* **Ignored content:** If Claude never accesses a bundled file, it might be unnecessary or poorly signaled in the main instructions.

845845

846Iterate based on these observations rather than assumptions. The `name` and `description` in your Skill's metadata are particularly critical. Claude uses these when determining whether to trigger the Skill in response to the current task. Make sure they clearly describe what the Skill does and when it should be used.

846Iterate based on these observations rather than assumptions. The `name` and `description` in your Skill’s metadata are particularly critical. Claude uses these when determining whether to trigger the Skill in response to the current task. Make sure they clearly describe what the Skill does and when it should be used.

847847

848848## Anti-patterns to avoid

849849

from line 858

858858

859859### Avoid offering too many options

860860

861Don't present multiple approaches unless necessary:

861Don’t present multiple approaches unless necessary:

862862

863863````markdown

864864**Bad example: Too many choices** (confusing):

from line 877

877877

878878The following sections focus on Skills that include executable scripts. If your Skill uses only markdown instructions, skip to [Checklist for effective Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#checklist-for-effective-skills).

879879

880### Solve, don't defer

880### Solve, don’t defer

881881

882882When writing scripts for Skills, handle error conditions rather than deferring to Claude.

883883

from line 909

909909 return open(path).read()

910910```

911911

912Also justify and document configuration parameters to avoid "voodoo constants" (Ousterhout's law). If you don't know the right value, how will Claude determine it?

912Also justify and document configuration parameters to avoid “voodoo constants” (Ousterhout’s law). If you don’t know the right value, how will Claude determine it?

913913

914914**Good example: Self-documenting:**

915915

from line 949

949949

950950**Important distinction:** Make clear in your instructions whether Claude should:

951951

952* **Run the script** (most common): "Run `analyze_form.py` to extract fields"

953* **Read it as reference** (for complex logic): "See `analyze_form.py` for the field extraction algorithm"

952* **Run the script** (most common): “Run `analyze_form.py` to extract fields”

953* **Read it as reference** (for complex logic): “See `analyze_form.py` for the field extraction algorithm”

954954

955For most utility scripts, execution is preferred because it's more reliable and efficient. See the following [Runtime environment](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#runtime-environment) section for details on how script execution works.

955For most utility scripts, execution is preferred because it’s more reliable and efficient. See the following [Runtime environment](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#runtime-environment) section for details on how script execution works.

956956

957957**Example:**

958958

from line 1004

10041004````

10051005

10061006<Note>

1007 In this example, you'd need to write the `pdf_to_images.py` script.

1007 In this example, you’d need to write the `pdf_to_images.py` script.

10081008</Note>

10091009

1010Claude's vision capabilities help analyze layouts and structures.

1010Claude’s vision capabilities help analyze layouts and structures.

10111011

10121012### Create verifiable intermediate outputs

10131013

1014When Claude performs complex, open-ended tasks, it can make mistakes. The "plan-validate-execute" pattern catches errors early by having Claude first create a plan in a structured format, then validate that plan with a script before executing it.

1014When Claude performs complex, open-ended tasks, it can make mistakes. The “plan-validate-execute” pattern catches errors early by having Claude first create a plan in a structured format, then validate that plan with a script before executing it.

10151015

10161016**Example:** Imagine asking Claude to update 50 form fields in a PDF based on a spreadsheet. Without validation, Claude might reference non-existent fields, create conflicting values, miss required fields, or apply updates incorrectly.

10171017

from line 1026

10261026

10271027**When to use:** Batch operations, destructive changes, complex validation rules, high-stakes operations.

10281028

1029**Implementation tip:** Make validation scripts verbose with specific error messages such as "Field 'signature\_date' not found. Available fields: customer\_name, order\_total, signature\_date\_signed" to help Claude fix issues.

1029**Implementation tip:** Make validation scripts verbose with specific error messages such as “Field ‘signature\_date’ not found. Available fields: customer\_name, order\_total, signature\_date\_signed” to help Claude fix issues.

10301030

10311031### Package dependencies

10321032

from line 1035

10351035* **claude.ai:** Can install packages from npm and PyPI and pull from GitHub repositories

10361036* **Claude API:** Has no network access and no runtime package installation

10371037

1038List required packages in your `SKILL.md` and verify they're available in the [Code execution tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool) documentation.

1038List required packages in your `SKILL.md` and verify they’re available in the [Code execution tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool) documentation.

10391039

10401040### Runtime environment

10411041

from line 1045

10451045

10461046**How Claude accesses Skills:**

10471047

10481. **Metadata pre-loaded:** At startup, the name and description from all Skills' YAML frontmatter are loaded into the system prompt.

10481. **Metadata pre-loaded:** At startup, the name and description from all Skills’ YAML frontmatter are loaded into the system prompt.

104910492. **Files read on-demand:** Claude uses bash Read tools to access `SKILL.md` and other files from the filesystem when needed.

10503. **Scripts run efficiently:** Utility scripts can be run through bash without loading their full contents into context. Only the script's output consumes tokens.

10514. **No context penalty for large files:** Reference files, data, or documentation don't consume context tokens until actually read.

10503. **Scripts run efficiently:** Utility scripts can be run through bash without loading their full contents into context. Only the script’s output consumes tokens.

10514. **No context penalty for large files:** Reference files, data, or documentation don’t consume context tokens until actually read.

10521052

10531053* **File paths matter:** Claude navigates your skill directory like a filesystem. Use forward slashes (`reference/guide.md`), not backslashes.

10541054

from line 1065

10651065

10661066* **Make execution intent clear:**

10671067

1068 * "Run `analyze_form.py` to extract fields" (execute)

1069 * "See `analyze_form.py` for the extraction algorithm" (read as reference)

1068 * “Run `analyze_form.py` to extract fields” (execute)

1069 * “See `analyze_form.py` for the extraction algorithm” (read as reference)

10701070

10711071* **Test file access patterns:** Verify Claude can navigate your directory structure by testing with real requests.

10721072

from line 1088

10881088

10891089### MCP tool references

10901090

1091If your Skill uses MCP (Model Context Protocol) tools, always use fully qualified tool names to avoid "tool not found" errors.

1091If your Skill uses MCP (Model Context Protocol) tools, always use fully qualified tool names to avoid “tool not found” errors.

10921092

10931093**Format:** `ServerName:tool_name`

10941094

from line 1108

11081108

11091109### Avoid assuming tools are installed

11101110

1111Don't assume packages are available:

1111Don’t assume packages are available:

11121112

11131113````markdown

11141114**Bad example: Assumes installation**:

from line 1149

11491149* [ ] Description includes both what the Skill does and when to use it

11501150* [ ] `SKILL.md` body is under 500 lines

11511151* [ ] Additional details are in separate files (if needed)

1152* [ ] No time-sensitive information (or in "old patterns" section)

1152* [ ] No time-sensitive information (or in “old patterns” section)

11531153* [ ] Consistent terminology throughout

11541154* [ ] Examples are concrete, not abstract

11551155* [ ] File references are one level deep

from line 1160

11601160

11611161* [ ] Scripts solve problems rather than defer to Claude

11621162* [ ] Error handling is explicit and helpful

1163* [ ] No "voodoo constants" (all values justified)

1163* [ ] No “voodoo constants” (all values justified)

11641164* [ ] Required packages listed in instructions and verified as available

11651165* [ ] Scripts have clear documentation

11661166* [ ] No Windows-style paths (all forward slashes)

agents-and-tools/agent-skills/claude-api-skill Changed · +11 / -11 lines

from line 13

1313

1414The skill comes bundled with [Claude Code](https://code.claude.com/docs/en/overview) and is also available in the open-source [Anthropic skills repository](https://github.com/anthropics/skills), where you can install it in any environment that supports Agent Skills.

1515

16The skill uses [progressive disclosure](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#how-skills-work) to keep context efficient: Claude loads only the documentation relevant to your project's language, surface (Messages API or Managed Agents), and the specific task at hand (tool use, streaming, batches, and so on), rather than loading everything at once.

16The skill uses [progressive disclosure](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#how-skills-work) to keep context efficient: Claude loads only the documentation relevant to your project’s language, surface (Messages API or Managed Agents), and the specific task at hand (tool use, streaming, batches, and so on), rather than loading everything at once.

1717

1818## What the skill provides

1919

from line 21

2121

2222**For the Messages API:**

2323

24* **Language-specific SDK documentation:** Installation, quick start, common patterns, and error handling for your project's language

24* **Language-specific SDK documentation:** Installation, quick start, common patterns, and error handling for your project’s language

2525* **Tool use guidance:** Language-specific examples and [conceptual foundations](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) for function calling, including the beta tool runner where available

2626* **Streaming patterns:** Implementation details for building chat UIs and handling incremental display

2727* **Batch processing:** Offline batch processing at 50 percent cost

from line 34

3434**For Managed Agents (beta):**

3535

3636* **Onboarding flow:** An interview-driven walkthrough for setting up a new Managed Agent, available through the `/claude-api managed-agents-onboard` subcommand

37* **Security guide check:** A read-only check of an agent's settings against [Secure your Managed Agents deployment](https://platform.claude.com/docs/en/managed-agents/secure-deployment), available through the `/claude-api managed-agents-secure` subcommand of the skill bundled with Claude Code

37* **Security guide check:** A read-only check of an agent’s settings against [Secure your Managed Agents deployment](https://platform.claude.com/docs/en/managed-agents/secure-deployment), available through the `/claude-api managed-agents-secure` subcommand of the skill bundled with Claude Code

3838* **Language-specific Managed Agents docs:** Creating persistent agents, starting sessions, streaming events, and handling tool confirmations for Python, TypeScript, C#, Go, Java, PHP, Ruby, and cURL

3939* **Client patterns:** Lossless stream reconnect, `processed_at` queued/processed gate, interrupt handling, file-mount pitfalls, and credential handling

40* **Deployment constraints:** Which platforms support Managed Agents, and the Messages API with tool use as the alternative on platforms that don't

40* **Deployment constraints:** Which platforms support Managed Agents, and the Messages API with tool use as the alternative on platforms that don’t

4141

4242## When the skill activates

4343

from line 55

5555

5656## Supported languages

5757

58The skill detects your project's language automatically by examining project files (for example, `requirements.txt` for Python, `tsconfig.json` for TypeScript, `go.mod` for Go) and loads the appropriate documentation.

58The skill detects your project’s language automatically by examining project files (for example, `requirements.txt` for Python, `tsconfig.json` for TypeScript, `go.mod` for Go) and loads the appropriate documentation.

5959

6161| ---------- | ---------------- | ----------- | -------------- |

from line 141

141141* **Cloud platform detection**, preserving platform-specific model ID formats (for example, the `anthropic.` prefix on Amazon Bedrock) and skipping changes for features that are unavailable on partner-operated platforms

142142* **Breaking parameter changes**, such as removing `temperature`, `top_p`, and `top_k` for Claude Opus 4.8 and Claude Opus 4.7, and converting `thinking: {type: "enabled", budget_tokens: N}` to `thinking: {type: "adaptive"}`

143143* **Prefill replacement**, converting assistant-message prefill patterns to [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) where applicable

144* **Beta header cleanup**, removing beta headers that the target model doesn't require (for example, `effort-2025-11-24`, `fine-grained-tool-streaming-2025-05-14`, `interleaved-thinking-2025-05-14`) and switching back from `client.beta.messages.create()` (go: `client.Beta.Messages.New()`; java: `client.beta().messages().create()`; csharp: `client.Beta.Messages.Create()`; php: `$client->beta->messages->create()`) to `client.messages.create()` (go: `client.Messages.New()`; java: `client.messages().create()`; csharp: `client.Messages.Create()`; php: `$client->messages->create()`)

144* **Beta header cleanup**, removing beta headers that the target model doesn’t require (for example, `effort-2025-11-24`, `fine-grained-tool-streaming-2025-05-14`, `interleaved-thinking-2025-05-14`) and switching back from `client.beta.messages.create()` (go: `client.Beta.Messages.New()`; java: `client.beta().messages().create()`; csharp: `client.Beta.Messages.Create()`; php: `$client->beta->messages->create()`) to `client.messages.create()` (go: `client.Messages.New()`; java: `client.messages().create()`; csharp: `client.Messages.Create()`; php: `$client->messages->create()`)

145145* **Effort calibration**, recommending an `output_config.effort` starting point for the target model (for example, the default `high` on Claude Opus 5, and `xhigh` for coding and agentic use cases on Claude Opus 4.8 and Claude Opus 4.7)

146146* **Prompt-behavior tuning**, flagging length-control, tool-triggering, subagent, and instruction-following prompts that might behave differently on the target model

147147* **Silent default handling**, opting back into thinking summarization (`thinking.display: "summarized"`) when reasoning is surfaced to users on Claude Opus 4.8 and Claude Opus 4.7

from line 171

171171

172172If your project has an eval, the skill also compares scores and token usage with and without dropped `thinking` blocks.

173173

174The test requests and replays are real Messages API requests, billed at the model's normal rates. Each replay requests only a few output tokens and sets `tool_choice` to `none`, so no tool runs. The skill states the cost and asks for your approval before it sends them.

174The test requests and replays are real Messages API requests, billed at the model’s normal rates. Each replay requests only a few output tokens and sets `tool_choice` to `none`, so no tool runs. The skill states the cost and asks for your approval before it sends them.

175175

176176## Setting up a Managed Agent

177177

from line 189

189189

190190## Checking a Managed Agents deployment

191191

192To compare an agent's settings with the guide [Secure your Managed Agents deployment](https://platform.claude.com/docs/en/managed-agents/secure-deployment), invoke the `managed-agents-secure` subcommand of the skill bundled with Claude Code:

192To compare an agent’s settings with the guide [Secure your Managed Agents deployment](https://platform.claude.com/docs/en/managed-agents/secure-deployment), invoke the `managed-agents-secure` subcommand of the skill bundled with Claude Code:

193193

194194Let Claude Code check your agent against the security guide

195195

from line 197

197197/claude-api managed-agents-secure

198198```

199199

200Add the agent's ID after the subcommand, or the skill asks for it. The skill fetches the guide, then reads the agent, its recent sessions and [scheduled deployments](https://platform.claude.com/docs/en/managed-agents/scheduled-deployments), and the environments and vaults they use. Unless you ask it not to, it also searches the current folder's files for text that looks like a secret key. It lists only the names of matching files. It changes nothing. The report lists each setting to change with its recommended value, the questions only you can answer, and what it did not read.

200Add the agent’s ID after the subcommand, or the skill asks for it. The skill fetches the guide, then reads the agent, its recent sessions and [scheduled deployments](https://platform.claude.com/docs/en/managed-agents/scheduled-deployments), and the environments and vaults they use. Unless you ask it not to, it also searches the current folder’s files for text that looks like a secret key. It lists only the names of matching files. It changes nothing. The report lists each setting to change with its recommended value, the questions only you can answer, and what it did not read.

201201

202The skill reads the agent with the `ant` CLI, so first set up the CLI for the agent's workspace, as the [CLI quickstart](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/quickstart) shows. It needs a current version of Claude Code; run `claude update` to upgrade.

202The skill reads the agent with the `ant` CLI, so first set up the CLI for the agent’s workspace, as the [CLI quickstart](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/quickstart) shows. It needs a current version of Claude Code; run `claude update` to upgrade.

203203

204204## Example usage

205205

agents-and-tools/agent-skills/enterprise Changed · +16 / -16 lines

from line 20

2020| Risk indicator | What to look for | Concern level |

2121| ------------------------ | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |

2222| Code execution | Scripts in the Skill directory (`*.py`, `*.sh`, `*.js`) | High: scripts run with full environment access |

23| Instruction manipulation | Directives to ignore safety rules, hide actions from users, or alter Claude's behavior conditionally | High: can bypass security controls |

23| Instruction manipulation | Directives to ignore safety rules, hide actions from users, or alter Claude’s behavior conditionally | High: can bypass security controls |

2424| MCP server references | Instructions referencing MCP tools (`ServerName:tool_name`) | High: extends access beyond the Skill itself |

2525| Network access patterns | URLs, API endpoints, `fetch`, `curl`, or `requests` calls | High: potential data exfiltration vector |

2626| Hardcoded credentials | API keys, tokens, or passwords in Skill files or scripts | High: secrets exposed in Git history and context window |

from line 32

3232Before deploying any Skill from a third party or internal contributor, complete these steps:

3333

34341. **Read all Skill directory content.** Review `SKILL.md`, all referenced markdown files, and any bundled scripts or resources.

352. **Verify script behavior matches stated purpose.** Run scripts in a sandboxed environment and confirm outputs align with the Skill's description.

352. **Verify script behavior matches stated purpose.** Run scripts in a sandboxed environment and confirm outputs align with the Skill’s description.

36363. **Check for adversarial instructions.** Look for directives that tell Claude to ignore safety rules, hide actions from users, exfiltrate data through responses, or alter behavior based on specific inputs.

37374. **Check for external URL fetches or network calls.** Search scripts and instructions for network access patterns (`http`, `requests.get`, `urllib`, `curl`, `fetch`).

38385. **Verify no hardcoded credentials.** Check for API keys, tokens, or passwords in Skill files. Credentials should use environment variables or secure credential stores, never appear in Skill content.

39396. **Identify tools and commands the Skill instructs Claude to run.** List all bash commands, file operations, and tool references. Consider the combined risk when a Skill uses both file-read and network tools together.

40407. **Confirm redirect destinations.** If the Skill references external URLs, verify they point to expected domains.

418. **Verify no data exfiltration patterns.** Look for instructions that read sensitive data and then write, send, or encode it for external transmission, including through Claude's conversational responses.

4242

4343<Warning>

4444 Never deploy Skills from untrusted sources without a full audit. A malicious Skill can direct Claude to run arbitrary code, access sensitive files, or transmit data externally. Treat Skill installation with the same rigor as installing software on production systems.

from line 48

4848

4949Claude Enterprise organizations can turn on automated security scanning for custom Skills in claude.ai and Claude Cowork. The setting is **Skill and plugin security scanning** at [claude.ai > Organization settings > Skills](https://claude.ai/admin-settings/skills).

5050

51After you turn on the setting, scanning applies to Skills that members then upload or edit in claude.ai or Cowork. Each scan checks for signs of malicious behavior. These signs include hidden code execution, transfer of your data to an outside service, and instructions that tamper with Claude's safeguards.

5252

5353Whether a Skill is usable depends on its scan:

5454

5555* A Skill that fails the scan is blocked from use.

56* A Skill whose scan hasn't completed is blocked from use.

56* A Skill whose scan hasn’t completed is blocked from use.

5757* A Skill that passes with a warning stays usable behind a caution notice.

5858

5959Organization owners can allow some Skills that failed the scan. So can members whose [custom role](https://platform.claude.com/docs/en/manage-claude/user-management#custom-roles) can manage **Libraries**.

6060

61If scanning is available to your organization, turn it on. Scanning complements, but doesn't replace, the [review checklist](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/enterprise#review-checklist).

61If scanning is available to your organization, turn it on. Scanning complements, but doesn’t replace, the [review checklist](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/enterprise#review-checklist).

6262

63Scanning doesn't cover the Claude API. Skills you upload through the Skills API (`/v1/skills`), including from the Claude Console, aren't scanned, so for API deployments, rely on the review checklist and [version pinning](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/enterprise#versioning-strategy). Scanning also doesn't apply to Skills that were already in your organization when you turned it on, or to organizations with certain data handling configurations, such as customer-managed encryption keys (CMEK), zero data retention (ZDR), or HIPAA readiness. For setup steps, exclusions, and result types, see [Get started with skill and plugin scanning](https://support.claude.com/en/articles/15927065-get-started-with-skill-and-plugin-scanning) in the Claude Help Center.

63Scanning doesn’t cover the Claude API. Skills you upload through the Skills API (`/v1/skills`), including from the Claude Console, aren’t scanned, so for API deployments, rely on the review checklist and [version pinning](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/enterprise#versioning-strategy). Scanning also doesn’t apply to Skills that were already in your organization when you turned it on, or to organizations with certain data handling configurations, such as customer-managed encryption keys (CMEK), zero data retention (ZDR), or HIPAA readiness. For setup steps, exclusions, and result types, see [Get started with skill and plugin scanning](https://support.claude.com/en/articles/15927065-get-started-with-skill-and-plugin-scanning) in the Claude Help Center.

6464

6565## Evaluating Skills before deployment

6666

from line 73

7373| Dimension | What it measures | Example failure |

7474| --------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |

7575| Triggering accuracy | Does the Skill activate for the right queries and stay inactive for unrelated ones? | Skill triggers on every spreadsheet mention, even when the user just wants to discuss data |

76| Isolation behavior | Does the Skill work correctly on its own? | Skill references files that don't exist in its directory |

77| Coexistence | Does adding this Skill degrade other Skills? | New Skill's description is too broad, stealing triggers from existing Skills |

78| Instruction following | Does Claude follow the Skill's instructions accurately? | Claude skips validation steps or uses wrong libraries |

76| Isolation behavior | Does the Skill work correctly on its own? | Skill references files that don’t exist in its directory |

77| Coexistence | Does adding this Skill degrade other Skills? | New Skill’s description is too broad, stealing triggers from existing Skills |

78| Instruction following | Does Claude follow the Skill’s instructions accurately? | Claude skips validation steps or uses wrong libraries |

7979| Output quality | Does the Skill produce correct, useful results? | Generated reports have formatting errors or missing data |

8080

8181### Evaluation requirements

from line 88

8888

8989Evaluation results signal when to act:

9090

91* **Declining trigger accuracy:** Update the Skill's description or instructions

91* **Declining trigger accuracy:** Update the Skill’s description or instructions

9292* **Coexistence conflicts:** Consolidate overlapping Skills or narrow descriptions

9393* **Consistently low output quality:** Rewrite instructions or add validation steps

9494* **Persistent failures across updates:** Deprecate the Skill

from line 125

125125

126126### Recall limits

127127

128As a general guideline, limit the number of Skills loaded simultaneously to maintain reliable recall accuracy. Each Skill's metadata (name and description) competes for attention in the system prompt. With too many Skills active, Claude might fail to select the right Skill or miss relevant ones entirely. Use your evaluation suite to measure recall accuracy as you add Skills, and stop adding when performance degrades.

128As a general guideline, limit the number of Skills loaded simultaneously to maintain reliable recall accuracy. Each Skill’s metadata (name and description) competes for attention in the system prompt. With too many Skills active, Claude might fail to select the right Skill or miss relevant ones entirely. Use your evaluation suite to measure recall accuracy as you add Skills, and stop adding when performance degrades.

129129

130130Note that API requests support a maximum of 20 Skills for each request (see [Using Agent Skills with the API](https://platform.claude.com/docs/en/build-with-claude/skills-guide)). If a role requires more Skills than a single request supports, consider consolidating narrow Skills into broader ones or routing requests to different Skill sets based on task type.

131131

from line 134

134134Encourage teams to start with narrow, workflow-specific Skills rather than broad, multipurpose ones. As patterns emerge across your organization, consolidate related Skills into role-based bundles.

135135

136136<Tip>

137 Use evaluations to decide when to consolidate. Merge narrow Skills into a broader one only when the consolidated Skill's evaluations confirm equivalent performance to the individual Skills it replaces.

137 Use evaluations to decide when to consolidate. Merge narrow Skills into a broader one only when the consolidated Skill’s evaluations confirm equivalent performance to the individual Skills it replaces.

138138</Tip>

139139

140140**Example progression:**

from line 156

156156

157157### Role-based bundles

158158

159Group Skills by organizational role to keep each user's active Skill set focused:

159Group Skills by organizational role to keep each user’s active Skill set focused:

160160

161161* **Sales team:** CRM operations, pipeline reporting, proposal generation

162162* **Engineering:** Code review, deployment workflows, incident response

163163* **Finance:** Report generation, data validation, audit preparation

164164

165Each role-based bundle should contain only the Skills relevant to that role's daily workflows.

165Each role-based bundle should contain only the Skills relevant to that role’s daily workflows.

166166

167167## Distribution and version control

168168

agents-and-tools/agent-skills/overview Changed · +21 / -21 lines

from line 10

1010

1111## Why use Skills

1212

13Skills are reusable, filesystem-based resources that give Claude domain-specific expertise: workflows, context, and best practices that turn a general-purpose agent into a specialist. Unlike prompts (conversation-level instructions for one-off tasks), Skills load on demand, so you don't have to repeat the same guidance across conversations.

13Skills are reusable, filesystem-based resources that give Claude domain-specific expertise: workflows, context, and best practices that turn a general-purpose agent into a specialist. Unlike prompts (conversation-level instructions for one-off tasks), Skills load on demand, so you don’t have to repeat the same guidance across conversations.

1414

1515**Key benefits:**

1616

from line 28

2828

2929**Pre-built Agent Skills** are available on claude.ai, the Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), and [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry). On Microsoft Foundry, Agent Skills require a [Hosted on Anthropic deployment](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#additional-features-not-supported-when-hosted-on-azure). See [Available Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#available-skills) for the complete list.

3030

31**Custom Skills** let you package domain expertise and organizational knowledge. They're available across Claude's products: create them in Claude Code, upload them through the Claude API, or add them in claude.ai settings. On [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws) and [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry), upload custom Skills through the Skills API.

31**Custom Skills** let you package domain expertise and organizational knowledge. They’re available across Claude’s products: create them in Claude Code, upload them through the Claude API, or add them in claude.ai settings. On [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws) and [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry), upload custom Skills through the Skills API.

3232

3333<Note>

3434 **Get started:**

from line 39

3939

4040## How Skills work

4141

42Skills use Claude's VM environment to provide capabilities beyond what's possible with prompts alone. Claude operates in a virtual machine with filesystem access, allowing Skills to exist as directories containing instructions, executable code, and reference materials, organized like an onboarding guide you'd create for a new team member.

42Skills use Claude’s VM environment to provide capabilities beyond what’s possible with prompts alone. Claude operates in a virtual machine with filesystem access, allowing Skills to exist as directories containing instructions, executable code, and reference materials, organized like an onboarding guide you’d create for a new team member.

4343

4444This filesystem-based architecture allows **progressive disclosure:** Claude loads information in stages as needed, rather than consuming context upfront.

4545

from line 47

4747

4848### Level 1: Metadata (always loaded)

4949

50The Skill's YAML frontmatter provides discovery information:

50The Skill’s YAML frontmatter provides discovery information:

5151

5252```yaml

5353---

from line 79

7979For advanced form filling, see [FORMS.md](FORMS.md).

8080````

8181

82When you request something that matches a Skill's description, Claude reads `SKILL.md` from the filesystem using bash. Only then does this content enter the context window.

82When you request something that matches a Skill’s description, Claude reads `SKILL.md` from the filesystem using bash. Only then does this content enter the context window.

8383

8484### Level 3: Resources and code (loaded as needed)

8585

from line 111

111111

112112### The Skills architecture

113113

114Skills run in a code execution environment where Claude has filesystem access, bash commands, and code execution capabilities. Skills exist as directories on a virtual machine, and Claude interacts with them using the same bash commands you'd use to navigate files on your computer.

115115

116116<Frame>

117117 ![Agent Skills architecture, showing how Skills integrate with the agent's configuration and virtual machine](https://platform.claude.com/docs/images/agent-skills-architecture.svg)

from line 123

123123

124124**What this architecture makes possible:**

125125

126* **On-demand file access:** Claude reads only the files each task needs. A Skill can include dozens of reference files, but if your task only needs the sales schema, that's the one file Claude loads. The rest stay on the filesystem and cost zero tokens.

127* **Efficient script execution:** When Claude runs `validate_form.py`, the script's code never loads into the context window. Only its output (such as "Validation passed" or a specific error message) consumes tokens, which makes scripts far more efficient than having Claude generate equivalent code during the task.

128* **No practical limit on bundled content:** Files don't consume context until accessed, so Skills can include comprehensive API documentation, large datasets, or extensive examples. There's no context penalty for bundled content that isn't used.

126* **On-demand file access:** Claude reads only the files each task needs. A Skill can include dozens of reference files, but if your task only needs the sales schema, that’s the one file Claude loads. The rest stay on the filesystem and cost zero tokens.

127* **Efficient script execution:** When Claude runs `validate_form.py`, the script’s code never loads into the context window. Only its output (such as “Validation passed” or a specific error message) consumes tokens, which makes scripts far more efficient than having Claude generate equivalent code during the task.

128* **No practical limit on bundled content:** Files don’t consume context until accessed, so Skills can include comprehensive API documentation, large datasets, or extensive examples. There’s no context penalty for bundled content that isn’t used.

129129

130130### Example: Loading a PDF processing Skill

131131

132Here's how Claude loads and uses the custom `pdf-processing` Skill from the earlier examples (not the pre-built `pdf` Skill):

132Here’s how Claude loads and uses the custom `pdf-processing` Skill from the earlier examples (not the pre-built `pdf` Skill):

133133

1341341. **Startup:** System prompt includes: `pdf-processing - Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.`

1352. **User request:** "Extract the text from this PDF and summarize it"

1352. **User request:** “Extract the text from this PDF and summarize it”

1361363. **Claude calls:** `bash: cat pdf-processing/SKILL.md` → Instructions loaded into context

1371374. **Claude determines:** Form filling is not needed, so `FORMS.md` is not read

1381385. **Claude executes:** Uses instructions from `SKILL.md` to complete the task

from line 143

143143

144144## Where Skills work

145145

146Skills are available across Claude's agent products:

146Skills are available across Claude’s agent products:

147147

148148<Note>

149149 Claude Platform on AWS and Microsoft Foundry inherit the same Skills behavior as the Claude API in all following sections, except where [Limitations and constraints](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#limitations-and-constraints) says otherwise.

from line 167

167167

168168**Custom Skills:** Create Skills as directories with `SKILL.md` files. Claude discovers and uses them automatically.

169169

170Custom Skills in Claude Code are filesystem-based and don't require API uploads: place them in `~/.claude/skills/` (personal) or `.claude/skills/` (project).

170Custom Skills in Claude Code are filesystem-based and don’t require API uploads: place them in `~/.claude/skills/` (personal) or `.claude/skills/` (project).

171171

172172To learn more, see [Use Skills in Claude Code](https://code.claude.com/docs/en/skills).

173173

from line 214

214214* Maximum 64 characters

215215* Must contain only lowercase letters, numbers, and hyphens

216216* Cannot contain XML tags

217* Cannot contain reserved words: "anthropic", "claude"

217* Cannot contain reserved words: `anthropic`, `claude`

218218

219219`description`:

220220

from line 226

226226

227227## Security considerations

228228

229Use Skills only from trusted sources: those you created yourself or obtained from Anthropic. Skills give Claude new capabilities through instructions and code, which also means a malicious Skill can direct Claude to call tools or run code in ways that don't match the Skill's stated purpose.

230230

231231<Warning>

232232 If you must use a Skill from an untrusted or unknown source, exercise extreme caution and thoroughly audit it before use. Depending on what access Claude has when running the Skill, malicious Skills could lead to data exfiltration, unauthorized system access, or other security risks.

from line 234

234234

235235**Key security considerations:**

236236

237* **Audit thoroughly:** Review all files bundled in the Skill: `SKILL.md`, scripts, images, and other resources. Look for unusual patterns such as unexpected network calls, file access patterns, or operations that don't match the Skill's stated purpose.

238238* **External sources are risky:** Skills that fetch data from external URLs pose particular risk, as fetched content might contain malicious instructions. Even trustworthy Skills can be compromised if their external dependencies change over time.

239239* **Tool misuse:** Malicious Skills can call tools (file operations, bash commands, code execution) in harmful ways.

240240* **Data exposure:** Skills with access to sensitive data could be designed to leak information to external systems.

241241* **Treat like installing software:** Be especially careful when integrating Skills into production systems with access to sensitive data or critical operations.

242242

243For organization-scale governance, vetting, and deployment guidance, see [Skills for enterprise](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/enterprise). Claude Enterprise organizations can also turn on [Skill content scanning](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/enterprise#skill-content-scanning) for custom Skills uploaded in claude.ai and Claude Cowork. Scanning doesn't cover Skills uploaded through the Skills API or the Claude Console.

243For organization-scale governance, vetting, and deployment guidance, see [Skills for enterprise](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/enterprise). Claude Enterprise organizations can also turn on [Skill content scanning](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/enterprise#skill-content-scanning) for custom Skills uploaded in claude.ai and Claude Cowork. Scanning doesn’t cover Skills uploaded through the Skills API or the Claude Console.

244244

245245## Available Skills

246246

from line 267

267267

268268## Data retention

269269

270Agent Skills is not covered by ZDR arrangements. Skill definitions and execution data are retained according to Anthropic's standard data retention policy.

270Agent Skills is not covered by ZDR arrangements. Skill definitions and execution data are retained according to Anthropic’s standard data retention policy.

271271

272272For ZDR eligibility across all features, see [API and data retention](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention).

273273

from line 312

312312

313313* **Claude Code:**

314314

315 * **Full network access:** Skills have the same network access as any other program on the user's computer.

316 * **Global package installation discouraged:** Skills should only install packages locally to avoid interfering with the user's computer.

315 * **Full network access:** Skills have the same network access as any other program on the user’s computer.

316 * **Global package installation discouraged:** Skills should only install packages locally to avoid interfering with the user’s computer.

317317

318318Plan your Skills to work within these constraints.

319319

from line 325

325325 </Card>

326326

327327 <Card title="Using Agent Skills with the API" icon="code" href="https://platform.claude.com/docs/en/build-with-claude/skills-guide">

328 Learn how to use Agent Skills to extend Claude's capabilities through the API.

328 Learn how to use Agent Skills to extend Claude’s capabilities through the API.

329329 </Card>

330330

331331 <Card title="Use Skills in Claude Code" icon="terminal" href="https://code.claude.com/docs/en/skills">

agents-and-tools/agent-skills/quickstart Changed · +5 / -5 lines

from line 4

44description: Learn how to use Agent Skills to create documents with the Claude API in under 10 minutes.

55---

7This tutorial shows you how to use Agent Skills to create a PowerPoint presentation. You'll learn how to enable Skills, make a request, and access the generated file.

7This tutorial shows you how to use Agent Skills to create a PowerPoint presentation. You’ll learn how to enable Skills, make a request, and access the generated file.

99## Prerequisites

1010

from line 14

1414

1515## Agent Skills overview

1616

17Pre-built Agent Skills extend Claude's capabilities with specialized expertise for tasks such as creating documents, analyzing data, and processing files. Anthropic provides the following pre-built Agent Skills in the API:

17Pre-built Agent Skills extend Claude’s capabilities with specialized expertise for tasks such as creating documents, analyzing data, and processing files. Anthropic provides the following pre-built Agent Skills in the API:

1818

1919* **PowerPoint (pptx):** Create and edit presentations

2020* **Excel (xlsx):** Create and analyze spreadsheets

from line 117

117117

118118You see the following Skills: `pptx`, `xlsx`, `docx`, and `pdf`.

119119

120This API returns each Skill's metadata: its name and description. Claude loads this metadata at startup to determine which Skills are available. This is the first level of **progressive disclosure**, where Claude discovers Skills without loading their full instructions yet.

120This API returns each Skill’s metadata: its name and description. Claude loads this metadata at startup to determine which Skills are available. This is the first level of **progressive disclosure**, where Claude discovers Skills without loading their full instructions yet.

121121

122122## Step 2: Create a presentation

123123

from line 350

350350 The examples use the `code_execution_20260521` tool version, and the Step 3 code parses the result types that current tool versions return. Skills also work with older [code execution tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool) versions such as `code_execution_20250825`: any current code execution tool version satisfies the Skills requirement. If you use a different version, use the tool `type` listed on the code execution tool page.

351351</Note>

352352

353When you make this request, Claude automatically matches your task to the relevant Skill. Because you asked for a presentation, Claude determines the PowerPoint Skill is relevant and loads its full instructions: the second level of progressive disclosure. Then Claude runs the Skill's code to create your presentation.

354354

355355## Step 3: Download the created file

356356

from line 1173

11731173 </Card>

11741174

11751175 <Card title="Using Agent Skills with the API" icon="book" href="https://platform.claude.com/docs/en/build-with-claude/skills-guide">

1176 Learn how to use Agent Skills to extend Claude's capabilities through the API.

1176 Learn how to use Agent Skills to extend Claude’s capabilities through the API.

11771177 </Card>

11781178

11791179 <Card title="Create custom Skills" icon="code" href="https://platform.claude.com/docs/en/api/skills/create">

agents-and-tools/mcp-connector Changed · +21 / -21 lines

## Pin an MCP server’s tool list (beta) ## Pin an MCP server's tool list (beta)

from line 12

1212 Microsoft Foundry: beta

1313---

1414

15Claude's Model Context Protocol (MCP) connector feature allows you to connect to remote MCP servers directly from the Messages API without a separate MCP client.

15Claude’s Model Context Protocol (MCP) connector feature allows you to connect to remote MCP servers directly from the Messages API without a separate MCP client.

1616

1717<Note>

1818 The previous version of this feature (`mcp-client-2025-04-04`) is deprecated. See [Deprecated version: mcp-client-2025-04-04](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector#deprecated-version-mcp-client-2025-04-04).

from line 29

2929

3030## When Claude uses MCP tools

3131

32Once an MCP server is connected, Claude calls its tools when the user's request maps to a tool's described capability, either explicitly ("search Jira for open bugs") or implicitly ("what's blocking the release?" with a Jira server attached).

32Once an MCP server is connected, Claude calls its tools when the user’s request maps to a tool’s described capability, either explicitly (“search Jira for open bugs”) or implicitly (“what’s blocking the release?” with a Jira server attached).

3333

34Claude does **not** call an MCP tool for general knowledge questions about a connected service. Asking "how do Notion databases work?" with a Notion server attached is answered directly; asking "what's in my Projects database?" triggers the tool.

34Claude does **not** call an MCP tool for general knowledge questions about a connected service. Asking “how do Notion databases work?” with a Notion server attached is answered directly; asking “what’s in my Projects database?” triggers the tool.

3535

3636You can steer how readily Claude calls MCP tools through your system prompt. See [When Claude uses tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview#when-claude-uses-tools) for general guidance and example phrasings.

3737

from line 318

318318

320320| --------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

322322| `url` | string | Yes | The URL of the MCP server. Must start with `https://`. |

324324| `authorization_token` | string | No | OAuth authorization token if required by the MCP server. See [Authentication](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector#authentication) for how to obtain one, or the [MCP specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) for protocol details. |

from line 350

350350

352352| ----------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |

358358

359With the `mcp-client-2026-09-15` beta header, an MCPToolset also accepts `tools`, a pinned copy of the server's tool list. See [Pin an MCP server's tool list](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector#pin-mcp-tool-list).

359With the `mcp-client-2026-09-15` beta header, an MCPToolset also accepts `tools`, a pinned copy of the server’s tool list. See [Pin an MCP server’s tool list](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector#pin-mcp-tool-list).

360360

361361### Tool configuration options

362362

from line 490

490490* **Server must exist:** The `mcp_server_name` in an MCPToolset must match a server defined in the `mcp_servers` array.

491491* **Server must be used:** Every MCP server defined in `mcp_servers` must be referenced by exactly one MCPToolset.

492492* **Unique toolset for each server:** Each MCP server can only be referenced by one MCPToolset.

493* **Unknown tool names:** If a tool name in `configs` doesn't exist on the MCP server, a backend warning is logged but no error is returned (MCP servers might have dynamic tool availability).

493* **Unknown tool names:** If a tool name in `configs` doesn’t exist on the MCP server, a backend warning is logged but no error is returned (MCP servers might have dynamic tool availability).

494494

495495## Response content types

496496

from line 524

524524}

525525```

526526

527## Pin an MCP server's tool list (beta)

527## Pin an MCP server’s tool list (beta)

528528

529An MCP server can change its tools at any time. The `mcp-client-2026-09-15` beta header records the tool list each server returns and lets you pin it, so a server that changes its tools doesn't change what Claude receives partway through a conversation. It includes everything `mcp-client-2025-11-20` does, so send it in place of that header. It's available on the Claude API.

529An MCP server can change its tools at any time. The `mcp-client-2026-09-15` beta header records the tool list each server returns and lets you pin it, so a server that changes its tools doesn’t change what Claude receives partway through a conversation. It includes everything `mcp-client-2025-11-20` does, so send it in place of that header. It’s available on the Claude API.

530530

531531When the API asks an MCP server for its tools while producing a response, the response starts with an `mcp_tool_listing` block for that server, one block for each server it asked:

532532

from line 550

550550

551551If your code reads `content[0]`, skip these blocks. Send the assistant message back unchanged, `mcp_tool_listing` blocks included, and keep sending `mcp-client-2026-09-15` on every request that carries one. Later requests then use the recorded list for that server instead of asking it again.

552552

553To pin a list yourself, copy a block's `tools` into the `tools` field of that server's MCPToolset. The API then doesn't ask the server for its tools, and the toolset's tools are exactly those entries, with `default_config` and `configs` applied:

553To pin a list yourself, copy a block’s `tools` into the `tools` field of that server’s MCPToolset. The API then doesn’t ask the server for its tools, and the toolset’s tools are exactly those entries, with `default_config` and `configs` applied:

554554

555555```json

556556{

from line 570

570570}

571571```

572572

573Each entry in `tools` holds the tool's `name` as the server lists it (without the server name), its `description`, and its `input_schema`.

573Each entry in `tools` holds the tool’s `name` as the server lists it (without the server name), its `description`, and its `input_schema`.

574574

575The following example sends one request with an unpinned toolset, copies the returned list into the toolset's `tools` field, and sends the request again. The second response has no `mcp_tool_listing` block, because the API doesn't ask the server:

575The following example sends one request with an unpinned toolset, copies the returned list into the toolset’s `tools` field, and sends the request again. The second response has no `mcp_tool_listing` block, because the API doesn’t ask the server:

576576

577577<CodeGroup>

578578 ```bash cURL

from line 1181

11811181

11821182## Authentication

11831183

1184For MCP servers that require OAuth authentication, you'll need to obtain an access token. The MCP connector beta supports passing an `authorization_token` parameter in the MCP server definition. API consumers are expected to handle the OAuth flow and obtain the access token prior to making the API call, and to refresh the token as needed.

1184For MCP servers that require OAuth authentication, you’ll need to obtain an access token. The MCP connector beta supports passing an `authorization_token` parameter in the MCP server definition. API consumers are expected to handle the OAuth flow and obtain the access token prior to making the API call, and to refresh the token as needed.

11851185

11861186### Obtaining an access token for testing

11871187

from line 1209

12091209

12101210### Using the access token

12111211

1212Once you've obtained an access token, you can use it in your MCP server configuration:

1212Once you’ve obtained an access token, you can use it in your MCP server configuration:

12131213

12141214```json

12151215{

from line 1374

13741374

13751375### Use MCP tools

13761376

1377Convert MCP tools for use with the SDK's [tool runner](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-runner), which handles tool execution automatically:

1377Convert MCP tools for use with the SDK’s [tool runner](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-runner), which handles tool execution automatically:

13781378

13791379<CodeGroup exclude="shell">

13801380 ```python Python

from line 1978

19781978

19791979### Error handling

19801980

1981The conversion functions fail with `UnsupportedMCPValueError` (go: `UnsupportedValueError`; java, csharp: `AnthropicInvalidDataException`) if an MCP value isn't supported by the Claude API (thrown, or in Go returned as an error). This can occur with unsupported content types, MIME types, or resource links (resolve resource links with your MCP client before converting).

1981The conversion functions fail with `UnsupportedMCPValueError` (go: `UnsupportedValueError`; java, csharp: `AnthropicInvalidDataException`) if an MCP value isn’t supported by the Claude API (thrown, or in Go returned as an error). This can occur with unsupported content types, MIME types, or resource links (resolve resource links with your MCP client before converting).

19821982

19831983## Batch requests

19841984

from line 1986

19861986

19871987## Data retention

19881988

1989The MCP connector is not covered by ZDR arrangements. Data exchanged with MCP servers, including tool definitions and execution results, is retained according to Anthropic's standard data retention policy.

19901990

19911991For ZDR eligibility across all features, see [API and data retention](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention).

19921992

19931993## Migration guide

19941994

1995If you're using the deprecated `mcp-client-2025-04-04` beta header, follow this guide to migrate to the new version.

1995If you’re using the deprecated `mcp-client-2025-04-04` beta header, follow this guide to migrate to the new version.

19961996

19971997### Key changes

19981998

agents-and-tools/mcp-tunnels/concepts Changed · +6 / -6 lines

from line 15

1515| Term | Definition | Also appears as |

1616| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

1717| **Tunnel stack** | The two containers you run inside your network to attach to a tunnel: the proxy and cloudflared. One stack serves one tunnel and can be replicated across hosts for availability. With programmatic access, the setup component runs alongside the stack to provision credentials. | the stack, the MCP tunnel stack, the tunnel deployment, your deployment |

18| **Proxy** | Anthropic's routing component. Terminates inner TLS, validates that upstream IPs fall within an allowed range, and routes each request to an upstream MCP server based on hostname. | `mcp-proxy` (image name, Compose service name, and Helm container name), `mcp-gateway` (container-internal config path `/etc/mcp-gateway/config.yaml` and Helm `gateway.config.*` values prefix) |

19| **cloudflared** | Cloudflare's open-source tunnel connector. Initiates the outbound-only connections from your network to the tunnel edge and carries encrypted traffic between the edge and the proxy. Not related to a Managed Agent. | the outbound connector, the tunnel connector |

18| **Proxy** | Anthropic’s routing component. Terminates inner TLS, validates that upstream IPs fall within an allowed range, and routes each request to an upstream MCP server based on hostname. | `mcp-proxy` (image name, Compose service name, and Helm container name), `mcp-gateway` (container-internal config path `/etc/mcp-gateway/config.yaml` and Helm `gateway.config.*` values prefix) |

19| **cloudflared** | Cloudflare’s open-source tunnel connector. Initiates the outbound-only connections from your network to the tunnel edge and carries encrypted traffic between the edge and the proxy. Not related to a Managed Agent. | the outbound connector, the tunnel connector |

2020| **Setup component** | The `setup` binary, shipped inside the `mcp-proxy` image. With programmatic access it authenticates over Workload Identity Federation, fetches the tunnel token, generates a CA and server certificate, and registers the CA with Anthropic. Also provides `renew-cert`. | setup Job (the Helm pre-install hook), `setup` service (the Compose profile), setup hook, setup binary, setup CLI |

2121| **Tunnel edge** | The Cloudflare edge servers that cloudflared dials out to (IP ranges `198.41.192.0/19` and `2606:4700:a0::/44`, port 7844 TCP and UDP). The tunnel that runs over them is provisioned and controlled by Anthropic; Cloudflare operates the underlying network. | the edge, the Anthropic-operated tunnel edge |

22| **Inner TLS** | A second TLS handshake carried inside the tunnel's plaintext WebSocket stream, between Anthropic's back end and your proxy. The proxy presents a server certificate signed by a CA you registered on the tunnel. Because only you hold the private key, the transport provider cannot read request or response payloads. | the inner TLS handshake |

22| **Inner TLS** | A second TLS handshake carried inside the tunnel’s plaintext WebSocket stream, between Anthropic’s back end and your proxy. The proxy presents a server certificate signed by a CA you registered on the tunnel. Because only you hold the private key, the transport provider cannot read request or response payloads. | the inner TLS handshake |

2323| **Upstream MCP server** | An MCP server running in your private network that the proxy routes to. Each upstream is exposed as one subdomain under your tunnel domain. | upstream, routed MCP server, tunneled MCP server |

2424

2525## Credential provisioning

2626

27The tunnel stack needs two credentials at runtime: the **tunnel token**, which authenticates cloudflared's outbound connection, and a **server certificate** signed by a CA registered on the tunnel, which the proxy presents during the inner TLS handshake. There are two ways to supply them, presented throughout this guide as a pair of tabs.

27The tunnel stack needs two credentials at runtime: the **tunnel token**, which authenticates cloudflared’s outbound connection, and a **server certificate** signed by a CA registered on the tunnel, which the proxy presents during the inner TLS handshake. There are two ways to supply them, presented throughout this guide as a pair of tabs.

2828

3030| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ------------------------------- |

from line 40

4040* **Connection direction:** cloudflared dials **outbound** from your network to the tunnel edge. Your firewall sees only egress on port 7844; no inbound port is opened.

4141* **Request direction:** once that connection is established, MCP requests travel **from Anthropic toward your network** over it, through cloudflared to the proxy, and on to the upstream MCP server.

4242

43The phrase "outbound-only" describes the connection, not the requests carried over it.

43The phrase “outbound-only” describes the connection, not the requests carried over it.

4444

45Inner TLS spans Anthropic's back end and your proxy. cloudflared and the tunnel edge sit between them on the wire but see only ciphertext; the proxy is the first place inside your network where MCP request payloads are readable.

45Inner TLS spans Anthropic’s back end and your proxy. cloudflared and the tunnel edge sit between them on the wire but see only ciphertext; the proxy is the first place inside your network where MCP request payloads are readable.

4646

4747```mermaid

4848sequenceDiagram

agents-and-tools/mcp-tunnels/console Changed · +11 / -11 lines

from line 37

3737

3838 Programmatic access relies on [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation); read that page first if federation issuers, rules, and service accounts are unfamiliar. To turn the toggle on you need:

3939

40 1. **A registered OIDC issuer** for the identity provider your stack presents tokens from (such as a Kubernetes cluster, AWS IAM, Google Cloud, or GitHub Actions). Register one on the **Issuers** tab of the [Workload identity](https://platform.claude.com/settings/workload-identity-federation) page (`platform.claude.com/settings/workload-identity-federation`) in the Claude Console if your organization doesn't have one.

4141 2. **A federation rule with the `workspace:manage_tunnels` scope.** Turning on the toggle reveals a **Federation rule** picker. Select an existing rule with that scope, or click **Create federation rule** to create one inline.

42 3. **The rule's service account added to this workspace.** The Tunnels API authorizes against the service account's workspace memberships. If you're creating the tunnel in a workspace other than the organization's default, [add the service account to that workspace](https://platform.claude.com/docs/en/manage-claude/workspaces#role-inheritance) and pass the workspace ID at deploy time (`api.wif.workspaceId` for Helm, `ANTHROPIC_WORKSPACE_ID` for Compose).

42 3. **The rule’s service account added to this workspace.** The Tunnels API authorizes against the service account’s workspace memberships. If you’re creating the tunnel in a workspace other than the organization’s default, [add the service account to that workspace](https://platform.claude.com/docs/en/manage-claude/workspaces#role-inheritance) and pass the workspace ID at deploy time (`api.wif.workspaceId` for Helm, `ANTHROPIC_WORKSPACE_ID` for Compose).

4343

4444 Skipping this step is fully supported; both deploy guides have a **Without programmatic access** tab.

4545 </Step>

from line 52

5252 Both deploy paths need:

5353

5454 * The **tunnel ID** (`tnl_...`), shown on the tunnel detail page.

55 * The **tunnel domain** (`abcd1234.tunnel.anthropic.com`), shown on the tunnel detail page. Used as the proxy's `tunnel_domain` and in the server certificate's SAN.

55 * The **tunnel domain** (`abcd1234.tunnel.anthropic.com`), shown on the tunnel detail page. Used as the proxy’s `tunnel_domain` and in the server certificate’s SAN.

5656

5757 What else you need depends on the [credential-provisioning mode](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#credential-provisioning):

5858

from line 61

6161 | The **federation rule ID** (`fdrl_...`) of the rule you selected. The rule is org-level, not stored on the tunnel; find it on the **Rules** tab of the [Workload identity](https://platform.claude.com/settings/workload-identity-federation?tab=rules) page (`platform.claude.com/settings/workload-identity-federation?tab=rules`) in the Claude Console. | The **tunnel token**, revealed with the eye icon next to **Token** on the detail page. Treat it as a secret. See [Get the connection details](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#get-the-connection-details). |

6262 | The **organization ID** (a UUID), shown on the [Organization](https://platform.claude.com/settings/organization) page (`platform.claude.com/settings/organization`) in the Claude Console. | A **CA certificate** that you generate and [register on the tunnel](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#add-a-ca-certificate). |

6363

64 With programmatic access, your stack fetches the tunnel token through the Tunnels API, generates the CA and server certificate locally (the private key never leaves your environment), and registers only the CA's public certificate with Anthropic. You're still responsible for securing the private keys and renewing the server certificate before it expires.

64 With programmatic access, your stack fetches the tunnel token through the Tunnels API, generates the CA and server certificate locally (the private key never leaves your environment), and registers only the CA’s public certificate with Anthropic. You’re still responsible for securing the private keys and renewing the server certificate before it expires.

6565 </Step>

6666</Steps>

6767

from line 73

7373

7474| Field | Description |

7575| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

76| **Domain** | Copy the assigned `abcd1234.tunnel.anthropic.com` value. Your proxy's routes are subdomains of this domain. |

77| **Token** | Click the eye icon (**Show token**) to fetch the tunnel token, then use the copy icon to copy it into your tunnel stack's secret store. Click **Rotate token** to invalidate the current token and issue a new one. |

76| **Domain** | Copy the assigned `abcd1234.tunnel.anthropic.com` value. Your proxy’s routes are subdomains of this domain. |

77| **Token** | Click the eye icon (**Show token**) to fetch the tunnel token, then use the copy icon to copy it into your tunnel stack’s secret store. Click **Rotate token** to invalidate the current token and issue a new one. |

7878

7979<Note>

80 Every reveal and rotation is recorded in your organization's [Compliance API](https://platform.claude.com/docs/en/manage-claude/compliance-api) activity log. Rotation does not sever cloudflared connections that are already established, so you can rotate, redeploy with the new value, and let the old connections drain.

80 Every reveal and rotation is recorded in your organization’s [Compliance API](https://platform.claude.com/docs/en/manage-claude/compliance-api) activity log. Rotation does not sever cloudflared connections that are already established, so you can rotate, redeploy with the new value, and let the old connections drain.

8181</Note>

8282

8383## Add a CA certificate

from line 86

8686

8787<Steps>

8888 <Step title="Find the Certificates section">

89 On the tunnel's detail page, scroll to the **Certificates** section and click **Add certificate**.

89 On the tunnel’s detail page, scroll to the **Certificates** section and click **Add certificate**.

9090 </Step>

9191

9292 <Step title="Provide the certificate">

93 Click **Choose file** to select a `.pem`, `.crt`, or `.cer` file, drag the file onto the text area, or paste the PEM block directly. The modal window rejects private-key material and content that isn't a `-----BEGIN CERTIFICATE-----` block. The file must be 8 kB or smaller.

93 Click **Choose file** to select a `.pem`, `.crt`, or `.cer` file, drag the file onto the text area, or paste the PEM block directly. The modal window rejects private-key material and content that isn’t a `-----BEGIN CERTIFICATE-----` block. The file must be 8 kB or smaller.

9494 </Step>

9595

9696 <Step title="Add the certificate">

from line 98

9898 </Step>

9999</Steps>

100100

101A tunnel holds up to two active certificates so you can rotate without downtime: register the new certificate alongside the old one, redeploy your proxy with the new key pair, confirm traffic is flowing, then click **Revoke** on the old certificate's row. Revoked certificates remain visible in the list with a **Revoked** badge.

101A tunnel holds up to two active certificates so you can rotate without downtime: register the new certificate alongside the old one, redeploy your proxy with the new key pair, confirm traffic is flowing, then click **Revoke** on the old certificate’s row. Revoked certificates remain visible in the list with a **Revoked** badge.

102102

103103## Deploy the tunnel stack

104104

from line 136

136136 </Step>

137137

138138 <Step title="Supply the routing">

139 The card shows two optional fields: **Subdomain** (prefixed to the tunnel domain) and **Path** (appended after it). Fill in one or both, depending on how your proxy's routes are configured. The **Resolves to** line shows the full MCP server URL that the agent connects to.

139 The card shows two optional fields: **Subdomain** (prefixed to the tunnel domain) and **Path** (appended after it). Fill in one or both, depending on how your proxy’s routes are configured. The **Resolves to** line shows the full MCP server URL that the agent connects to.

140140 </Step>

141141</Steps>

142142

agents-and-tools/mcp-tunnels/deploy-compose Changed · +21 / -21 lines

from line 14

1414

1515You need:

1616

17* **A tunnel.** With programmatic access, the [setup component](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) creates one for you when you don't supply a tunnel ID; to attach to an existing tunnel instead, [create it in the Claude Console](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#create-a-tunnel) and record the tunnel ID (`tnl_...`). Manual provisioning always starts from a Console-created tunnel.

17* **A tunnel.** With programmatic access, the [setup component](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) creates one for you when you don’t supply a tunnel ID; to attach to an existing tunnel instead, [create it in the Claude Console](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#create-a-tunnel) and record the tunnel ID (`tnl_...`). Manual provisioning always starts from a Console-created tunnel.

1818

1919* **A way for the host to authenticate to the Tunnels API.**

2020

21 * **Programmatic access (recommended).** Turn on **Set up programmatic access** when creating the tunnel so the setup component can authenticate through Workload Identity Federation. If you're letting the setup component create the tunnel, create the federation rule directly on the [Workload identity](https://platform.claude.com/settings/workload-identity-federation) page (`platform.claude.com/settings/workload-identity-federation`) in the Claude Console instead. Record the federation rule ID (`fdrl_...`) and your organization ID.

22 * **Manual.** Skip programmatic access. You'll [get the tunnel token from the Console](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#get-the-connection-details), generate a CA and server certificate yourself, and [register the CA in the Console](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#add-a-ca-certificate).

21 * **Programmatic access (recommended).** Turn on **Set up programmatic access** when creating the tunnel so the setup component can authenticate through Workload Identity Federation. If you’re letting the setup component create the tunnel, create the federation rule directly on the [Workload identity](https://platform.claude.com/settings/workload-identity-federation) page (`platform.claude.com/settings/workload-identity-federation`) in the Claude Console instead. Record the federation rule ID (`fdrl_...`) and your organization ID.

22 * **Manual.** Skip programmatic access. You’ll [get the tunnel token from the Console](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#get-the-connection-details), generate a CA and server certificate yourself, and [register the CA in the Console](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#add-a-ca-certificate).

2323

2424* **A host with Docker and Docker Compose** installed. The manual flow also requires `openssl` (1.1.1 or later).

2525

2626* **Outbound network connectivity** from the host to `api.anthropic.com` (443 TCP) and the [tunnel edge](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) (7844 TCP and UDP). See the full [network requirements](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview#network-requirements).

2727

28* **One or more MCP servers** running and reachable from the host on the addresses you'll configure under `routes`. If you don't have one yet, [use the sample server](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-compose#optional-use-a-sample-mcp-server).

28* **One or more MCP servers** running and reachable from the host on the addresses you’ll configure under `routes`. If you don’t have one yet, [use the sample server](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-compose#optional-use-a-sample-mcp-server).

2929

3030## Optional: Use a sample MCP server

3131

32If you don't have an MCP server available for testing, use this minimal one:

32If you don’t have an MCP server available for testing, use this minimal one:

3333

3434```bash

3535mkdir -p mcp-tunnel

from line 54

5454

5555## Install

5656

57This guide provides one reference approach using Docker Compose. You are responsible for adapting it to meet your organization's security requirements.

57This guide provides one reference approach using Docker Compose. You are responsible for adapting it to meet your organization’s security requirements.

5858

5959<Tabs>

6060 <Tab title="With programmatic access">

61 This path requires the host to have an OIDC identity provider (such as a cloud VM metadata server or SPIFFE). If it doesn't, use the **Without programmatic access** tab instead.

61 This path requires the host to have an OIDC identity provider (such as a cloud VM metadata server or SPIFFE). If it doesn’t, use the **Without programmatic access** tab instead.

6262

6363 The setup component uses Workload Identity Federation to fetch the tunnel token, generate a CA and server certificate, and register the CA with Anthropic.

6464

from line 143

143143 EOF

144144 ```

145145

146 If you're using the [sample MCP server](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-compose#optional-use-a-sample-mcp-server), append it as a service:

146 If you’re using the [sample MCP server](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-compose#optional-use-a-sample-mcp-server), append it as a service:

147147

148148 ```bash

149149 cat >> docker-compose.yaml <<'EOF'

from line 168

168168 export ANTHROPIC_ORGANIZATION_ID=00000000-0000-0000-0000-000000000000

169169 ```

170170

171 If your federation rule is scoped to a workspace other than your organization's default, also set `ANTHROPIC_WORKSPACE_ID=wrkspc_...`; the setup component uses the default workspace otherwise. An auto-created tunnel is created in that workspace.

171 If your federation rule is scoped to a workspace other than your organization’s default, also set `ANTHROPIC_WORKSPACE_ID=wrkspc_...`; the setup component uses the default workspace otherwise. An auto-created tunnel is created in that workspace.

172172

173 Set `ANTHROPIC_IDENTITY_TOKEN` to an OIDC JWT from this host's identity provider. Follow the [WIF guide for your provider](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation#identity-providers) to register the issuer, set the rule's subject, and mint the token; the rule's audience must match the audience you request when minting.

173 Set `ANTHROPIC_IDENTITY_TOKEN` to an OIDC JWT from this host’s identity provider. Follow the [WIF guide for your provider](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation#identity-providers) to register the issuer, set the rule’s subject, and mint the token; the rule’s audience must match the audience you request when minting.

174174

175175 Run the setup component:

176176

from line 224

224224 </Tab>

225225

226226 <Tab title="Without programmatic access">

227 Use this flow if you didn't turn on **Set up programmatic access**, or for local development and testing. There is no `setup` service.

227 Use this flow if you didn’t turn on **Set up programmatic access**, or for local development and testing. There is no `setup` service.

228228

229229 <Steps>

230230 <Step title="Get the tunnel token and domain from the Console">

from line 244

244244 cd mcp-tunnel

245245 ```

246246

247 The proxy listens on `:8080` over plain WebSocket; the [inner TLS](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) handshake occurs **inside** that WebSocket stream using these certificates. Anthropic verifies the inner handshake against the CA you register in the Console. The server certificate's Subject Alternative Name (SAN) must include `*.<tunnel-domain>` as described in the [certificate requirements](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/reference#certificate-requirements).

247 The proxy listens on `:8080` over plain WebSocket; the [inner TLS](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) handshake occurs **inside** that WebSocket stream using these certificates. Anthropic verifies the inner handshake against the CA you register in the Console. The server certificate’s Subject Alternative Name (SAN) must include `*.<tunnel-domain>` as described in the [certificate requirements](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/reference#certificate-requirements).

248248

249249 ```bash

250250 # Self-signed CA. Explicit extensions so it satisfies the certificate

from line 288

288288 cat data/ca.crt

289289 ```

290290

291 The **Needs certificate** badge next to the tunnel's name goes away once a certificate is registered. See [Add a CA certificate](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#add-a-ca-certificate).

291 The **Needs certificate** badge next to the tunnel’s name goes away once a certificate is registered. See [Add a CA certificate](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#add-a-ca-certificate).

292292 </Step>

293293

294294 <Step title="Write the proxy config">

from line 311

311311 </Step>

312312

313313 <Step title="Write docker-compose.yaml">

314 The `network_mode: "service:mcp-proxy"` setting places [cloudflared](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) in the proxy's network namespace so that `localhost:8080` inside the cloudflared container reaches the proxy. The `--url http://localhost:8080` flag gives cloudflared its forwarding target; without that flag, cloudflared has no route for incoming requests and returns a 503.

314 The `network_mode: "service:mcp-proxy"` setting places [cloudflared](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) in the proxy’s network namespace so that `localhost:8080` inside the cloudflared container reaches the proxy. The `--url http://localhost:8080` flag gives cloudflared its forwarding target; without that flag, cloudflared has no route for incoming requests and returns a 503.

315315

316316 ```bash

317317 cat > docker-compose.yaml <<'EOF'

from line 358

358358 EOF

359359 ```

360360

361 If you're using the [sample MCP server](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-compose#optional-use-a-sample-mcp-server), append it as a service:

361 If you’re using the [sample MCP server](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-compose#optional-use-a-sample-mcp-server), append it as a service:

362362

363363 ```bash

364364 cat >> docker-compose.yaml <<'EOF'

from line 385

385385

386386The compose file reads `TUNNEL_TOKEN` from the host environment with no default, so you must repeat the export in every fresh shell and after a reboot.

387387

388For a multi-VM deployment, copy the `mcp-tunnel/` directory to each host, set `TUNNEL_TOKEN`, and run `docker compose up -d`. In the programmatic flow `TUNNEL_TOKEN` is `$(sudo cat data/tunnel-token)`; in the manual flow it's the value you copied from the Console. The same tunnel token and certificates work across all replicas.

388For a multi-VM deployment, copy the `mcp-tunnel/` directory to each host, set `TUNNEL_TOKEN`, and run `docker compose up -d`. In the programmatic flow `TUNNEL_TOKEN` is `$(sudo cat data/tunnel-token)`; in the manual flow it’s the value you copied from the Console. The same tunnel token and certificates work across all replicas.

389389

390390## Verify the deployment

391391

392Verify end to end by calling an [upstream MCP server](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) from Anthropic's side: see [Use the tunneled MCP servers](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview#use-the-tunneled-mcp-servers). With the [sample MCP server](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-compose#optional-use-a-sample-mcp-server), the routed URL is `https://echo.<your-tunnel-domain>/mcp`. If verification fails, see [Troubleshooting](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/troubleshooting).

392Verify end to end by calling an [upstream MCP server](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) from Anthropic’s side: see [Use the tunneled MCP servers](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview#use-the-tunneled-mcp-servers). With the [sample MCP server](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-compose#optional-use-a-sample-mcp-server), the routed URL is `https://echo.<your-tunnel-domain>/mcp`. If verification fails, see [Troubleshooting](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/troubleshooting).

393393

394394## Upgrades

395395

from line 429

429429

430430### Certificate renewal

431431

432You're responsible for monitoring expiry and renewing the server certificate before it expires.

432You’re responsible for monitoring expiry and renewing the server certificate before it expires.

433433

434434With programmatic access:

435435

from line 437

437437docker compose run --rm setup renew-cert --output=dir:/data

438438```

439439

440The CLI arguments replace the `setup` service's `command` (the `init` arguments) but keep its `entrypoint`, so this runs `/setup renew-cert --output=dir:/data`.

440The CLI arguments replace the `setup` service’s `command` (the `init` arguments) but keep its `entrypoint`, so this runs `/setup renew-cert --output=dir:/data`.

441441

442442<Tip>

443443 Pass `--renew-before=720h` to make the command a no-op when more than 30 days of validity remain. This makes it safe to run on a fixed schedule.

444444</Tip>

445445

446Without programmatic access, sign a new server certificate with your existing CA (the CA registered in the Console doesn't change) and replace `data/tls.crt`. Set `TUNNEL_DOMAIN` first if you're running this from a fresh shell.

446Without programmatic access, sign a new server certificate with your existing CA (the CA registered in the Console doesn’t change) and replace `data/tls.crt`. Set `TUNNEL_DOMAIN` first if you’re running this from a fresh shell.

447447

448448```bash

449449export TUNNEL_DOMAIN=YOUR_TUNNEL_DOMAIN_HERE

agents-and-tools/mcp-tunnels/deploy-helm Changed · +25 / -25 lines

from line 8

88 MCP tunnels are in research preview. [Request access](https://claude.com/form/mcp-tunnels) to try them.

99</Note>

1010

11The Anthropic Helm chart installs the [tunnel stack](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) as a single Deployment and attaches it to your tunnel: one the chart's setup hook creates for you, or an existing tunnel you created in the [Claude Console](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#create-a-tunnel).

11The Anthropic Helm chart installs the [tunnel stack](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) as a single Deployment and attaches it to your tunnel: one the chart’s setup hook creates for you, or an existing tunnel you created in the [Claude Console](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#create-a-tunnel).

1212

1313## Before you start

1414

1515You need:

1616

17* **A tunnel.** With programmatic access, the chart's setup hook creates one for you when you don't supply a tunnel ID; to attach to an existing tunnel instead, [create it in the Console](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#create-a-tunnel) and record the tunnel ID (`tnl_...`). Manual provisioning always starts from a Console-created tunnel; you also need its tunnel token and tunnel domain.

17* **A tunnel.** With programmatic access, the chart’s setup hook creates one for you when you don’t supply a tunnel ID; to attach to an existing tunnel instead, [create it in the Console](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#create-a-tunnel) and record the tunnel ID (`tnl_...`). Manual provisioning always starts from a Console-created tunnel; you also need its tunnel token and tunnel domain.

1818

1919* **A way for the chart to authenticate to the Tunnels API.**

2020

2121 * **[Programmatic access](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#credential-provisioning) (recommended).** The [setup component](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) authenticates through Workload Identity Federation, fetches the tunnel token, generates a CA, registers it with Anthropic, and stores everything in a Secret. You need a federation rule scoped to `workspace:manage_tunnels`.

22 * **[Manual](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#credential-provisioning).** Skip programmatic access. You'll [get the tunnel token from the Console](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#get-the-connection-details), generate a CA and server certificate yourself, [register the CA in the Console](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#add-a-ca-certificate), and supply the credentials to the cluster as Secrets.

22 * **[Manual](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#credential-provisioning).** Skip programmatic access. You’ll [get the tunnel token from the Console](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#get-the-connection-details), generate a CA and server certificate yourself, [register the CA in the Console](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#add-a-ca-certificate), and supply the credentials to the cluster as Secrets.

2323

2424* **A Kubernetes cluster** you can deploy to with `helm` and `kubectl`. The **Without programmatic access** tab also uses `openssl` (1.1.1 or later).

2525

2626* **Outbound network connectivity** from the cluster to `api.anthropic.com` (443 TCP) and the [tunnel edge](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) (7844 TCP and UDP). See the full [network requirements](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview#network-requirements).

2727

28* **One or more MCP servers** running and reachable from the cluster on the addresses you'll configure under `gateway.config.routes`. If you don't have one yet, [use the sample server](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm#optional-use-a-sample-mcp-server).

28* **One or more MCP servers** running and reachable from the cluster on the addresses you’ll configure under `gateway.config.routes`. If you don’t have one yet, [use the sample server](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm#optional-use-a-sample-mcp-server).

2929

3030## Optional: Use a sample MCP server

3131

32If you don't have an MCP server available for testing, use this minimal one:

32If you don’t have an MCP server available for testing, use this minimal one:

3333

3434```bash

3535kubectl create namespace mcp-tunnel --dry-run=client -o yaml | kubectl apply -f -

from line 95

9595

9696<Tabs>

9797 <Tab title="With programmatic access">

98 The setup component exchanges the cluster's projected ServiceAccount token through your federation rule, fetches the tunnel token, generates a CA and server certificate, and registers the CA with Anthropic. A daily CronJob renews the server certificate as needed, so you don't handle any secrets by hand.

98 The setup component exchanges the cluster’s projected ServiceAccount token through your federation rule, fetches the tunnel token, generates a CA and server certificate, and registers the CA with Anthropic. A daily CronJob renews the server certificate as needed, so you don’t handle any secrets by hand.

9999

100100 <Steps>

101101 <Step title="Set up Workload Identity Federation for the cluster">

102 Follow [Use WIF with Kubernetes](https://platform.claude.com/docs/en/manage-claude/wif-providers/kubernetes) to register your cluster's OIDC issuer and create a federation rule. The setup component runs under its own ServiceAccount in the release namespace; the exact name follows Helm's `fullname` convention, so for any release name other than `mcp-tunnel`, run `helm template <release> ... | grep -A2 'kind: ServiceAccount'` to confirm it before creating the rule. The rest of this guide assumes release name `mcp-tunnel` in namespace `mcp-tunnel`, where the ServiceAccount is `mcp-tunnel-setup`.

102 Follow [Use WIF with Kubernetes](https://platform.claude.com/docs/en/manage-claude/wif-providers/kubernetes) to register your cluster’s OIDC issuer and create a federation rule. The setup component runs under its own ServiceAccount in the release namespace; the exact name follows Helm’s `fullname` convention, so for any release name other than `mcp-tunnel`, run `helm template <release> ... | grep -A2 'kind: ServiceAccount'` to confirm it before creating the rule. The rest of this guide assumes release name `mcp-tunnel` in namespace `mcp-tunnel`, where the ServiceAccount is `mcp-tunnel-setup`.

103103

104104 | Field | Value |

105105 | -------- | ---------------------------------------------------- |

106106 | Subject | `system:serviceaccount:mcp-tunnel:mcp-tunnel-setup` |

107 | Audience | `api.anthropic.com` (the chart's default; no scheme) |

107 | Audience | `api.anthropic.com` (the chart’s default; no scheme) |

108108 | Scope | `workspace:manage_tunnels` |

109109

110110 <Note>

111 The chart's default audience is `api.anthropic.com` with no scheme, but the Console's federation-rule form suggests `https://api.anthropic.com`. The two must match byte-for-byte or authentication fails. Either set the rule's audience to `api.anthropic.com`, or set `api.wif.audience` in `values.yaml` to `https://api.anthropic.com`.

111 The chart’s default audience is `api.anthropic.com` with no scheme, but the Console’s federation-rule form suggests `https://api.anthropic.com`. The two must match byte-for-byte or authentication fails. Either set the rule’s audience to `api.anthropic.com`, or set `api.wif.audience` in `values.yaml` to `https://api.anthropic.com`.

112112 </Note>

113113

114 If the tunnel is in a workspace other than the organization's default, also [add the rule's service account to that workspace](https://platform.claude.com/docs/en/manage-claude/workspaces#role-inheritance) (the Tunnels API authorizes against the service account's workspace memberships).

114 If the tunnel is in a workspace other than the organization’s default, also [add the rule’s service account to that workspace](https://platform.claude.com/docs/en/manage-claude/workspaces#role-inheritance) (the Tunnels API authorizes against the service account’s workspace memberships).

115115

116 Note the rule's ID (`fdrl_...`); you'll set it as `api.wif.federationRuleId`.

116 Note the rule’s ID (`fdrl_...`); you’ll set it as `api.wif.federationRuleId`.

117117

118118 <Note>

119119 The daily certificate-renewal CronJob uses a separate ServiceAccount (also derived from the Helm `fullname`) but does not call the Tunnels API; it renews the certificate locally and only needs Kubernetes RBAC, which the chart grants. The federation rule does not need to cover it.

from line 158

158158 With these routes, Claude reaches the servers at `docs.<your-tunnel-domain>` and `search.<your-tunnel-domain>`. Some managed Kubernetes distributions allocate the Service CIDR outside the standard private ranges; if your routes target in-cluster Services, add `gateway.config.upstream.allowed_ips` here as described in [Upstream IP validation](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/troubleshooting#upstream-ip-validation).

159159

160160 <Note>

161 If you're using the [sample MCP server](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm#optional-use-a-sample-mcp-server), set `routes` to `echo: http://hello-mcp:9000` instead.

161 If you’re using the [sample MCP server](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm#optional-use-a-sample-mcp-server), set `routes` to `echo: http://hello-mcp:9000` instead.

162162 </Note>

163163 </Step>

164164

165165 <Step title="Review the rendered manifests">

166 Render the chart and review the output according to your organization's vetting practices:

166 Render the chart and review the output according to your organization’s vetting practices:

167167

168168 ```bash

169169 helm template mcp-tunnel \

from line 185

185185

186186 The setup component runs as a Helm pre-install hook Job, so `helm install` blocks until it completes. On success Helm deletes the Job automatically. If `helm install` fails with a hook error, see [Setup component authentication failures](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/troubleshooting#setup-component-authentication-failures).

187187

188 When `tunnel.id` is empty, the setup component creates the tunnel in the workspace your federation rule targets (the organization's default workspace unless you set `api.wif.workspaceId`) and stores its ID and domain in the `mcp-tunnel` Secret. Find the domain you'll need for [verification](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm#verify-the-deployment) on the tunnel's detail page, which you open from the [MCP tunnels](https://platform.claude.com/settings/workspaces/default/mcp-tunnels) page (`platform.claude.com/settings/workspaces/default/mcp-tunnels`) in the Console. In the workspace picker in the sidebar, select the workspace that holds the tunnel. You can also read the domain from the Secret:

188 When `tunnel.id` is empty, the setup component creates the tunnel in the workspace your federation rule targets (the organization’s default workspace unless you set `api.wif.workspaceId`) and stores its ID and domain in the `mcp-tunnel` Secret. Find the domain you’ll need for [verification](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm#verify-the-deployment) on the tunnel’s detail page, which you open from the [MCP tunnels](https://platform.claude.com/settings/workspaces/default/mcp-tunnels) page (`platform.claude.com/settings/workspaces/default/mcp-tunnels`) in the Console. In the workspace picker in the sidebar, select the workspace that holds the tunnel. You can also read the domain from the Secret:

189189

190190 ```bash

191191 kubectl -n mcp-tunnel get secret mcp-tunnel \

from line 195

195195 Re-running the setup component (during [upgrades](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm#upgrades) or [token rotation](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm#rotate-the-tunnel-token)) reuses the tunnel ID stored in this Secret; it never creates a second tunnel.

196196

197197 <Warning>

198 The `api.wif.*` values are identifiers, not secrets, so storing them in Helm release-history Secrets is not a risk. The sensitive data at rest is the `mcp-tunnel` Secret the setup component creates, which holds the tunnel token and TLS private keys. Apply your organization's standard practices for protecting Kubernetes Secrets to this namespace.

198 The `api.wif.*` values are identifiers, not secrets, so storing them in Helm release-history Secrets is not a risk. The sensitive data at rest is the `mcp-tunnel` Secret the setup component creates, which holds the tunnel token and TLS private keys. Apply your organization’s standard practices for protecting Kubernetes Secrets to this namespace.

199199 </Warning>

200200 </Step>

201201 </Steps>

from line 202

202202 </Tab>

203203

204204 <Tab title="Without programmatic access">

205 In this mode (`setup.enabled: false`) the chart makes no API calls; the setup component does not run and there is no cert-renew CronJob. Use this path if you'd rather not set up Workload Identity Federation.

205 In this mode (`setup.enabled: false`) the chart makes no API calls; the setup component does not run and there is no cert-renew CronJob. Use this path if you’d rather not set up Workload Identity Federation.

206206

207207 <Steps>

208208 <Step title="Get the tunnel token and domain">

from line 209

209209 [Create the tunnel](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#create-a-tunnel) and [get the tunnel token from the Console](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#get-the-connection-details).

210210

211211 <Note>

212 Record the tunnel domain from the detail page. You'll set it as `gateway.config.tunnel_domain`.

212 Record the tunnel domain from the detail page. You’ll set it as `gateway.config.tunnel_domain`.

213213 </Note>

214214 </Step>

215215

216216 <Step title="Generate a CA and server certificate">

217 The proxy listens on plain WebSocket, with [inner TLS](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) carried inside that stream using the certificate you generate here. The server certificate's SAN must include `*.<tunnel-domain>` as described in the [certificate requirements](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/reference#certificate-requirements).

217 The proxy listens on plain WebSocket, with [inner TLS](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) carried inside that stream using the certificate you generate here. The server certificate’s SAN must include `*.<tunnel-domain>` as described in the [certificate requirements](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/reference#certificate-requirements).

218218

219219 ```bash

220220 export TUNNEL_DOMAIN=YOUR_TUNNEL_DOMAIN_HERE

from line 249

249249 -extfile data/tls.ext

250250 ```

251251

252 [Register `data/ca.crt` in the Console](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#add-a-ca-certificate). Keep `data/ca.key` somewhere durable and secure; you'll need it to sign a fresh server certificate at renewal time.

252 [Register `data/ca.crt` in the Console](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#add-a-ca-certificate). Keep `data/ca.key` somewhere durable and secure; you’ll need it to sign a fresh server certificate at renewal time.

253253 </Step>

254254

255255 <Step title="Create the two Secrets">

from line 299

299299 Some managed Kubernetes distributions allocate the Service CIDR outside the standard private ranges; if your routes target in-cluster Services, add `gateway.config.upstream.allowed_ips` here as described in [Upstream IP validation](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/troubleshooting#upstream-ip-validation).

300300

301301 <Note>

302 If you're using the [sample MCP server](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm#optional-use-a-sample-mcp-server), set `routes` to `echo: http://hello-mcp:9000` instead.

302 If you’re using the [sample MCP server](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm#optional-use-a-sample-mcp-server), set `routes` to `echo: http://hello-mcp:9000` instead.

303303 </Note>

304304 </Step>

305305

from line 328

328328

329329## Verify the deployment

330330

331Verify end to end from Anthropic's side: use `https://<route>.<your-tunnel-domain>/<path>` in a Managed Agent session or a Messages API request, where `<route>` is a key from `gateway.config.routes` and `<path>` is whatever the upstream MCP server serves at. With the [sample MCP server](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm#optional-use-a-sample-mcp-server), that's `https://echo.<your-tunnel-domain>/mcp`. See [Use the tunneled MCP servers](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview#use-the-tunneled-mcp-servers) for the request shapes.

331Verify end to end from Anthropic’s side: use `https://<route>.<your-tunnel-domain>/<path>` in a Managed Agent session or a Messages API request, where `<route>` is a key from `gateway.config.routes` and `<path>` is whatever the upstream MCP server serves at. With the [sample MCP server](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm#optional-use-a-sample-mcp-server), that’s `https://echo.<your-tunnel-domain>/mcp`. See [Use the tunneled MCP servers](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview#use-the-tunneled-mcp-servers) for the request shapes.

332332

333333If that fails, check the pod logs (`kubectl -n mcp-tunnel logs deploy/mcp-tunnel -c mcp-proxy` and `-c cloudflared`) and consult [Troubleshooting](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/troubleshooting).

334334

from line 348

348348

349349## Upgrades

350350

351Always pass `--version` to `helm upgrade` so you don't pull a newer chart unexpectedly.

351Always pass `--version` to `helm upgrade` so you don’t pull a newer chart unexpectedly.

352352

353353### Upgrade from chart 1.x

354354

355Chart 2.0.0 moves the tunnel ID from `api.wif.tunnelId` to `tunnel.id`. Before upgrading, edit your `values.yaml`: move the `tnl_...` value to `tunnel.id` and remove `api.wif.tunnelId`. Leaving `tunnel.id` unset is safe (the setup component reuses the tunnel ID already stored in the `mcp-tunnel` Secret on re-run), but the explicit move keeps your `values.yaml` accurate. Also update your federation rule's scope from `org:manage_tunnels` to `workspace:manage_tunnels` in the Console.

355Chart 2.0.0 moves the tunnel ID from `api.wif.tunnelId` to `tunnel.id`. Before upgrading, edit your `values.yaml`: move the `tnl_...` value to `tunnel.id` and remove `api.wif.tunnelId`. Leaving `tunnel.id` unset is safe (the setup component reuses the tunnel ID already stored in the `mcp-tunnel` Secret on re-run), but the explicit move keeps your `values.yaml` accurate. Also update your federation rule’s scope from `org:manage_tunnels` to `workspace:manage_tunnels` in the Console.

356356

357357### Change configuration

358358

from line 367

367367```

368368

369369<Warning>

370 Maintain a complete `values.yaml` rather than relying on `--reuse-values`. Helm's deep-merge behavior can silently fail to remove deleted routes.

370 Maintain a complete `values.yaml` rather than relying on `--reuse-values`. Helm’s deep-merge behavior can silently fail to remove deleted routes.

371371</Warning>

372372

373373### Rotate the tunnel token

agents-and-tools/mcp-tunnels/overview Changed · +15 / -15 lines

from line 4

44description: Securely connect Claude to MCP servers running in your private network without opening inbound ports or exposing services to the public internet.

55---

7MCP tunnels let you connect Claude to Model Context Protocol (MCP) servers that run inside your private network. Traffic flows over an outbound-only connection, so you don't need to open inbound firewall ports, expose services to the public internet, or allowlist Anthropic's IP ranges on your origin.

7MCP tunnels let you connect Claude to Model Context Protocol (MCP) servers that run inside your private network. Traffic flows over an outbound-only connection, so you don’t need to open inbound firewall ports, expose services to the public internet, or allowlist Anthropic’s IP ranges on your origin.

99<Note>

10 MCP tunnels are in research preview. [Request access](https://claude.com/form/mcp-tunnels) to try them. They are provided "as-is" without any uptime, support, or continuity commitment, and they depend on a third-party network provider (Cloudflare) that makes no availability commitment for the underlying transport. Anthropic may modify or discontinue MCP tunnels at any time.

10 MCP tunnels are in research preview. [Request access](https://claude.com/form/mcp-tunnels) to try them. They are provided “as-is” without any uptime, support, or continuity commitment, and they depend on a third-party network provider (Cloudflare) that makes no availability commitment for the underlying transport. Anthropic may modify or discontinue MCP tunnels at any time.

1111</Note>

1212

1313For Zero Data Retention and HIPAA BAA eligibility, see [API and data retention](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#feature-eligibility).

from line 16

1616

1717The [tunnel stack](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) is two components that run inside your network:

1818

19* **[cloudflared](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components):** Cloudflare's open-source tunnel connector. It initiates outbound-only connections to the [tunnel edge](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) and carries encrypted traffic from Anthropic to your proxy.

20* **[Proxy](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components):** Anthropic's routing component. It terminates [inner TLS](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components), validates that upstream IPs fall within an allowed range, and routes each request to the correct [upstream MCP server](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) based on hostname.

19* **[cloudflared](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components):** Cloudflare’s open-source tunnel connector. It initiates outbound-only connections to the [tunnel edge](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) and carries encrypted traffic from Anthropic to your proxy.

20* **[Proxy](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components):** Anthropic’s routing component. It terminates [inner TLS](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components), validates that upstream IPs fall within an allowed range, and routes each request to the correct [upstream MCP server](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) based on hostname.

2121

2222Each MCP server you expose gets a hostname under your tunnel domain (for example, `docs.<your-tunnel-domain>`). You attach these hostnames to a Managed Agent session in the Claude Console, or pass them to the Messages API through the [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector).

2323

from line 27

2727

2828* A deployment target: a Kubernetes cluster, or a VM with Docker and Docker Compose.

2929

30* A tunnel. Create one in the Claude Console (see [Create a tunnel](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#create-a-tunnel)) or through the API; the Helm chart's setup hook can also create one for you during install.

30* A tunnel. Create one in the Claude Console (see [Create a tunnel](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#create-a-tunnel)) or through the API; the Helm chart’s setup hook can also create one for you during install.

3131

3232* A way for your stack to authenticate to the Tunnels API. Choose one:

3333

from line 55

5555| Layer | Protects against |

5656| --------------------------------------------------------------------------- | ------------------------------------------------------------------------ |

5757| Outer mTLS between Anthropic and the transport provider, with IP validation | Unauthorized clients reaching the tunnel |

58| Inner TLS from Anthropic's back end to your proxy | Payload inspection by the transport provider or any network intermediary |

58| Inner TLS from Anthropic’s back end to your proxy | Payload inspection by the transport provider or any network intermediary |

5959| OAuth on each MCP server | Unauthorized use of MCP tools by authenticated tunnel traffic |

6060

61The tunnel transport runs on Cloudflare's network. Because the proxy terminates inner TLS using a certificate that only you hold, Cloudflare cannot read request or response payloads. Anthropic does not connect to a tunnel until a CA certificate is registered, so payloads are always encrypted when they cross Cloudflare's network. Cloudflare does receive connection metadata; see [What the transport provider can observe](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview#what-the-transport-provider-can-observe).

61The tunnel transport runs on Cloudflare’s network. Because the proxy terminates inner TLS using a certificate that only you hold, Cloudflare cannot read request or response payloads. Anthropic does not connect to a tunnel until a CA certificate is registered, so payloads are always encrypted when they cross Cloudflare’s network. Cloudflare does receive connection metadata; see [What the transport provider can observe](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview#what-the-transport-provider-can-observe).

6262

6363### Shared responsibility model

6464

6565| Anthropic handles | Your organization handles |

6666| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |

67| Tunnel access control | All content and traffic that transits your tunnel, and compliance with applicable third-party acceptable-use policies (including Cloudflare's) |

67| Tunnel access control | All content and traffic that transits your tunnel, and compliance with applicable third-party acceptable-use policies (including Cloudflare’s) |

6868| Validating your CA certificate before connecting to your proxy | Adherence to the deployment guidance on these pages |

6969| Ensuring Claude only sends requests to tunnels owned by your organization | Securing tunnel tokens and TLS private keys |

7070| | Managing the server certificate and renewing it before it expires |

from line 85

8585* connection timing and byte-volume

8686* the `*.tunnel.anthropic.com` subdomain assigned to your tunnel

8787

88Anthropic's agreement with Cloudflare restricts Cloudflare's use of this telemetry. Cloudflare acts as a subprocessor for this research preview.

88Anthropic’s agreement with Cloudflare restricts Cloudflare’s use of this telemetry. Cloudflare acts as a subprocessor for this research preview.

8989

9090## Deploy a tunnel

9191

92If you're new to MCP tunnels, start with the quickstart to get a working tunnel locally before configuring a production deployment.

92If you’re new to MCP tunnels, start with the quickstart to get a working tunnel locally before configuring a production deployment.

9393

9494<CardGroup cols={2}>

9595 <Card title="Quickstart" icon="rocket" href="https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/quickstart">

from line 115

115115* **Authentication for setup**

116116

117117 * **Programmatic access** (through Workload Identity Federation) when you have an OIDC identity provider such as a Kubernetes cluster, cloud IAM, or SPIFFE

118 * **Manual credentials** when you don't, or when you're testing

118 * **Manual credentials** when you don’t, or when you’re testing

119119

120120## Use the tunneled MCP servers

121121

from line 130

130130### Managed Agents (Console)

131131

1321321. On the [Sessions](https://platform.claude.com/sessions) page (`platform.claude.com/sessions`) in the Claude Console, create a session and select **Create new agent** so you can edit the MCP server list.

1332. Click **+ MCP Server** and open the dropdown menu. Tunnels in the session's workspace that have at least one active certificate appear at the top of the list, above the public connector catalog.

1332. Click **+ MCP Server** and open the dropdown menu. Tunnels in the session’s workspace that have at least one active certificate appear at the top of the list, above the public connector catalog.

1341343. Select the tunnel and supply the **Subdomain** that your proxy routes to a specific MCP server, and the **Path** the upstream MCP server expects. The **Resolves to** line shows the exact URL.

135135

136136### Messages API

137137

138Pass the upstream MCP server's URL in the `mcp_servers` array, the same way as any other remote MCP server. The request body and `anthropic-beta` header follow the standard [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector) format; only the `url` is tunnel-specific. The following example uses the MCP connector's `mcp-client` beta header, which is separate from the `mcp-tunnels` beta used by the [Tunnels API](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/reference). Make the request in the workspace the tunnel was created in by using an API key for that workspace or, if your key isn't scoped to a workspace, by setting the [`anthropic-workspace-id` header](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace) to that workspace.

138Pass the upstream MCP server’s URL in the `mcp_servers` array, the same way as any other remote MCP server. The request body and `anthropic-beta` header follow the standard [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector) format; only the `url` is tunnel-specific. The following example uses the MCP connector’s `mcp-client` beta header, which is separate from the `mcp-tunnels` beta used by the [Tunnels API](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/reference). Make the request in the workspace the tunnel was created in by using an API key for that workspace or, if your key isn’t scoped to a workspace, by setting the [`anthropic-workspace-id` header](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace) to that workspace.

139139

140The URL's host is `<subdomain>.<your-tunnel-domain>`. The path depends on your upstream MCP server, not the tunnel: FastMCP's `streamable-http` transport serves at `/mcp`, and other servers might use `/` or a custom path (check the server's documentation). The proxy forwards the path untouched.

140The URL’s host is `<subdomain>.<your-tunnel-domain>`. The path depends on your upstream MCP server, not the tunnel: FastMCP’s `streamable-http` transport serves at `/mcp`, and other servers might use `/` or a custom path (check the server’s documentation). The proxy forwards the path untouched.

141141

142142<CodeGroup>

143143 ```bash cURL

agents-and-tools/mcp-tunnels/quickstart Changed · +3 / -3 lines

## What you’ll build ## What you'll build

from line 10

1010

1111This quickstart takes you from creating a tunnel to Claude calling a private MCP server through it. It uses Docker Compose with [manual](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#credential-provisioning) credential provisioning, which is the shortest path for local testing. For production deployments, see [Deploy with Helm](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-helm) or [Deploy with Docker Compose](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/deploy-compose).

1212

13## What you'll build

13## What you’ll build

1414

1515A two-container [tunnel stack](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) (the [proxy](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) and [cloudflared](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components)) plus a sample MCP server running alongside it. When everything is running, the sample server is reachable from Claude at `https://echo.<your-tunnel-domain>/mcp` even though nothing is listening on a public port.

1616

from line 24

2424 <Step title="Create a tunnel">

2525 In the Claude Console, go to the [MCP tunnels](https://platform.claude.com/settings/workspaces/default/mcp-tunnels) page (`platform.claude.com/settings/workspaces/default/mcp-tunnels`). Each tunnel belongs to one workspace. Select the workspace you want in the workspace picker in the sidebar. Click **New tunnel** and give it a name. Leave **Set up programmatic access** off; this quickstart uses manual credential provisioning.

2626

27 After it's created, open the tunnel. Copy two values from the **Connection** section:

27 After it’s created, open the tunnel. Copy two values from the **Connection** section:

2828

2929 * **Domain** (looks like `abcd1234.tunnel.anthropic.com`)

3030 * **Token** (click the eye icon, then copy)

from line 107

107107 </Tab>

108108 </Tabs>

109109

110 Back in the Console, on the tunnel detail page, click **Add certificate** and upload `data/ca.crt` (or paste its contents). The **Needs certificate** badge next to the tunnel's name goes away.

110 Back in the Console, on the tunnel detail page, click **Add certificate** and upload `data/ca.crt` (or paste its contents). The **Needs certificate** badge next to the tunnel’s name goes away.

111111 </Step>

112112

113113 <Step title="Write the sample MCP server">

agents-and-tools/mcp-tunnels/reference Changed · +3 / -3 lines

from line 74

7474Presented by the proxy during [inner TLS](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components).

7575

7676* Signed directly by a registered CA (no intermediates).

77* `AuthorityKeyIdentifier` extension present and matching the CA's `SubjectKeyIdentifier`.

77* `AuthorityKeyIdentifier` extension present and matching the CA’s `SubjectKeyIdentifier`.

7878* Subject Alternative Name includes a DNS name matching `<route>.<tunnel-domain>`. A wildcard `*.<tunnel-domain>` covers all routes.

7979* If the `ExtendedKeyUsage` extension is present, it includes `serverAuth`.

8080* Within its validity period.

from line 84

8484

8585## Setup component

8686

87The setup component ships inside the `mcp-proxy` image as the `setup` binary. Run it with `docker compose run --rm setup <subcommand>` (Compose) or rely on the chart's hooks and CronJobs (Helm).

87The setup component ships inside the `mcp-proxy` image as the `setup` binary. Run it with `docker compose run --rm setup <subcommand>` (Compose) or rely on the chart’s hooks and CronJobs (Helm).

8888

8989### `setup init`

9090

from line 110

110110| `--cert-duration` | New certificate validity period. | `2160h` (90 days) |

111111| `--renew-before` | Skip renewal if the existing certificate has more than this duration remaining. | `0` (always renew) |

112112

113Setting `--renew-before=720h` makes the command a no-op when more than 30 days of validity remain, so it's safe to run on a fixed schedule.

113Setting `--renew-before=720h` makes the command a no-op when more than 30 days of validity remain, so it’s safe to run on a fixed schedule.

114114

agents-and-tools/mcp-tunnels/security Changed · +4 / -4 lines

from line 12

1212

1313## Best practices

1414

15* **Require OAuth on every MCP server.** Configure each [upstream MCP server](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) to require OAuth as described in the [MCP authorization spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization). OAuth provides defense in depth on top of the tunnel's transport authentication and allows user-level authorization at the data layer.

16* **Enable SSO for your organization.** Tunnels, federation rules, and service accounts are managed in the Claude Console. SSO enforces your identity provider's session controls on the admins who can change them.

17* **Restrict `upstream.allowed_ips`.** Use the smallest CIDR ranges that cover your MCP servers. This is the [proxy](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components)'s primary SSRF defense.

15* **Require OAuth on every MCP server.** Configure each [upstream MCP server](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) to require OAuth as described in the [MCP authorization spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization). OAuth provides defense in depth on top of the tunnel’s transport authentication and allows user-level authorization at the data layer.

16* **Enable SSO for your organization.** Tunnels, federation rules, and service accounts are managed in the Claude Console. SSO enforces your identity provider’s session controls on the admins who can change them.

1818* **Monitor logs.** Alert on warnings, errors, and unusual traffic patterns from the tunnel stack.

1919* **Rotate credentials.** Rotate the server certificate and tunnel token on a regular schedule, and immediately if you suspect compromise.

2020* **Keep images updated.** Track new proxy releases and pin images by SHA-256 digest.

2121* **Limit network reach.** The proxy and [cloudflared](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) should only be able to reach the destinations listed in the [network requirements](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview#network-requirements). Use NetworkPolicy (Kubernetes) or host firewall rules (Compose).

2222* **Limit MCP server scope.** Each server should expose only the tools and data required for its purpose.

23* **Protect credentials at rest.** Apply your organization's secrets-management practices to private keys and tunnel tokens.

23* **Protect credentials at rest.** Apply your organization’s secrets-management practices to private keys and tunnel tokens.

2424

2525## Respond to a suspected breach

2626

agents-and-tools/mcp-tunnels/troubleshooting Changed · +13 / -13 lines

## Tunnel won’t connect ## Tunnel won't connect

from line 14

1414

1515| Symptom | Cause | Fix |

1616| -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

17| Tunnel doesn't appear in the agent **+ MCP Server** picker | The picker only lists tunnels in the session's workspace that have at least one active certificate. | Register a CA certificate, or open the session in the workspace the tunnel was created in. |

17| Tunnel doesn’t appear in the agent **+ MCP Server** picker | The picker only lists tunnels in the session’s workspace that have at least one active certificate. | Register a CA certificate, or open the session in the workspace the tunnel was created in. |

1818| Caller sees HTTP 500; [cloudflared](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) logs `No ingress rules were defined` | cloudflared has no local target. | Add `--url http://localhost:8080` and `network_mode: "service:mcp-proxy"` to the cloudflared service. |

19| Proxy logs `no route for host` | `tunnel_domain` doesn't match the assigned domain, or `config.yaml` was edited without restarting. | Set `tunnel_domain` to the exact domain shown on the tunnel detail page, then restart the proxy (`docker compose restart mcp-proxy`). |

19| Proxy logs `no route for host` | `tunnel_domain` doesn’t match the assigned domain, or `config.yaml` was edited without restarting. | Set `tunnel_domain` to the exact domain shown on the tunnel detail page, then restart the proxy (`docker compose restart mcp-proxy`). |

2020| Proxy logs `IP validation failed: <ip> is not a private address` | Upstream MCP server resolves outside RFC1918. | See [Upstream IP validation](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/troubleshooting#upstream-ip-validation). |

2121| Proxy exits with `cannot unmarshal !!seq into map[string]string` | `routes` is a YAML list. | Use `routes: { name: http://host:port }`. |

2222| Proxy exits with `open /data/tls.key: permission denied` | The key is `0600`; the proxy container runs non-root. | `chmod 644 data/tls.key`. |

from line 26

2626

2727## OAuth fails behind a source-IP allowlist

2828

29OAuth flows fail when your authorization server's source-IP allowlist blocks Anthropic's back end from reaching `/token`, `/register`, and the discovery endpoints. If you'd rather not allowlist Anthropic's egress ranges, you can route the backend-to-backend OAuth calls through the tunnel while keeping the browser-facing `/authorize` endpoint on your existing public hostname.

29OAuth flows fail when your authorization server’s source-IP allowlist blocks Anthropic’s back end from reaching `/token`, `/register`, and the discovery endpoints. If you’d rather not allowlist Anthropic’s egress ranges, you can route the backend-to-backend OAuth calls through the tunnel while keeping the browser-facing `/authorize` endpoint on your existing public hostname.

3030

3131<Steps>

3232 <Step title="Add a proxy route for the authorization server">

from line 40

4040 </Step>

4141

4242 <Step title="Serve split-endpoint discovery metadata">

43 Your authorization server's `/.well-known/oauth-authorization-server` response should point `authorization_endpoint` at your existing allowlisted hostname and everything else at the tunnel:

43 Your authorization server’s `/.well-known/oauth-authorization-server` response should point `authorization_endpoint` at your existing allowlisted hostname and everything else at the tunnel:

4444

4545 ```json

4646 {

from line 54

5454 </Step>

5555

5656 <Step title="Point the MCP server at the tunnel issuer">

57 Your MCP server's `/.well-known/oauth-protected-resource` response should reference the tunnel hostname as its authorization server:

57 Your MCP server’s `/.well-known/oauth-protected-resource` response should reference the tunnel hostname as its authorization server:

5858

5959 ```json

6060 {

from line 65

6565 </Step>

6666</Steps>

6767

68With this configuration, the user's browser requests `/authorize` on your existing hostname (which your allowlist already includes), whereas Anthropic's back end reaches `/token`, `/register`, and the discovery documents through the tunnel.

68With this configuration, the user’s browser requests `/authorize` on your existing hostname (which your allowlist already includes), whereas Anthropic’s back end reaches `/token`, `/register`, and the discovery documents through the tunnel.

6969

7070## Setup component authentication failures

7171

from line 73

7373

7474Tunnels-specific causes:

7575

76* The chart's default audience is `api.anthropic.com` (no scheme). If your rule's audience is `https://api.anthropic.com`, set `api.wif.audience` to match.

77* A `403` from the Tunnels API after a successful exchange means the rule's scope doesn't include `workspace:manage_tunnels`, or the rule's service account isn't a member of the tunnel's workspace. Set the scope and add the service account to the workspace.

76* The chart’s default audience is `api.anthropic.com` (no scheme). If your rule’s audience is `https://api.anthropic.com`, set `api.wif.audience` to match.

77* A `403` from the Tunnels API after a successful exchange means the rule’s scope doesn’t include `workspace:manage_tunnels`, or the rule’s service account isn’t a member of the tunnel’s workspace. Set the scope and add the service account to the workspace.

7878

79On Helm, the setup component runs as a pre-install hook Job. On failure, the Job is left behind for inspection (`kubectl logs job/mcp-tunnel-setup -n mcp-tunnel`). Helm doesn't manage hook resources, so delete it before retrying:

79On Helm, the setup component runs as a pre-install hook Job. On failure, the Job is left behind for inspection (`kubectl logs job/mcp-tunnel-setup -n mcp-tunnel`). Helm doesn’t manage hook resources, so delete it before retrying:

8080

8181```bash

8282helm uninstall mcp-tunnel -n mcp-tunnel

from line 83

8383kubectl -n mcp-tunnel delete job mcp-tunnel-setup

8484```

8585

86## Tunnel won't connect

86## Tunnel won’t connect

8787

8888Check the cloudflared logs first. Common causes:

8989

from line 94

9494

9595## Certificate errors

9696

97When Anthropic rejects the proxy's certificate during inner TLS, the proxy logs `tls handshake failed`. Verify that:

97When Anthropic rejects the proxy’s certificate during inner TLS, the proxy logs `tls handshake failed`. Verify that:

9898

9999* The server certificate has not expired.

100* The certificate's Subject Alternative Name matches `*.<tunnel-domain>`.

100* The certificate’s Subject Alternative Name matches `*.<tunnel-domain>`.

101101* The signing CA is registered with Anthropic for this tunnel.

102102

103103See the [certificate requirements](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/reference#certificate-requirements) for the full validation rules.

from line 106

106106

107107For SSRF protection, the proxy only dials addresses in the RFC1918 private ranges (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`) by default. Only IPv4 is supported for the proxy-to-upstream connection. (The cloudflared-to-edge egress range in [Network requirements](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview#network-requirements) is a different hop.)

108108

109If the proxy logs `IP validation failed: <ip> is not a private address`, the upstream hostname resolved outside that set. On Kubernetes, some managed distributions allocate the Service CIDR outside RFC1918; if `kubectl get svc kubernetes -n default -o jsonpath='{.spec.clusterIP}'` returns an address outside the private ranges, look up your cluster's Service CIDR and add it.

110110

111111If the address is legitimate, add the narrowest covering CIDR to `upstream.allowed_ips`. Setting `allowed_ips` **replaces** the RFC1918 default rather than extending it, so include the private ranges your other upstream MCP servers use:

112112