One read of Claude Developer Platformapi-20261021T193714Z
242 pages moved out of 808 read.
Pages moved
242
significant first
Pages read
808
in this capture
Captured
19:37 UTC
Corpus hash
851c97e9b6f0
corpus-hash
What this read moved
1-25 of 242, page 1 of 10This capture is too large to show at once. Changes 1-25 of 242 are below, significant first; the rest are on the following screens.
about-claude/api-credits-for-subscribers Changed · +8 / -8 lines
## Summary ## API credit amounts ### Before you start ## Use your credits efficiently ## At a glance ## API credits amounts ### Before you begin ## Make your credits go further
from line 10
1010 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
13## At a glance
13## Summary
1414
1515| Topic | Details |
1616| -------------------------------------- | ------------------------------------------------------------------------- |
from line 22
2222| **Expiry** | End of each billing cycle (or monthly for annual plans), with no rollover |
2323| **Payment method for Claude Platform** | Not required |
2424
25## API credits amounts
25## API credit amounts
2626
2727| Plan | Monthly credit |
2828| --------------------------------------------- | -------------------------------------------------------------------- |
from line 43
4343
4444## Claim your credits
4545
46### Before you begin
46### Before you start
4747
4848You need both of the following roles:
4949
from line 62
6262 </Step>
6363
6464 <Step title="Link a Console organization">
65 In the **API credits** section, choose the Console organization that should receive the credits, then accept the [program terms](https://www.anthropic.com/legal/credit-terms) by linking.
65 In the **API credits** section, select the Console organization that should receive the credits, then accept the [program terms](https://www.anthropic.com/legal/credit-terms) by linking.
6666 </Step>
6767
6868 <Step title="Start building">
from line 74
7474 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, [reach out to 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 103
103103
104104Credits 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, while 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.
108108* 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
from line 134
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. |
135135| 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
137## Make your credits go further
137## Use your credits efficiently
138138
139Your monthly cost depends mainly on the model you choose and how often your application runs. To stretch your credits:
139Your monthly cost depends mainly on the model you choose and how often your application runs. To use fewer credits:
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.
about-claude/glossary Changed · +11 / -11 lines
## RAG (retrieval augmented generation) ## TTFT (time to first token) ## RAG (Retrieval augmented generation) ## TTFT (Time to first token)
from line 6
66
77## Context window
88
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, while a smaller context window may 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
from line 32
3232
3333## MCP (Model Context Protocol)
3434
35Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to LLMs. Like a USB-C port for AI applications, MCP provides a unified way to connect AI models to different data sources and tools. MCP enables AI systems to maintain consistent context across interactions and access external resources in a standardized manner. See the [MCP documentation](https://modelcontextprotocol.io/) to learn more.
35Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to LLMs. Like a USB-C port for AI applications, MCP provides a unified way to connect AI models to different data sources and tools. MCP allows AI systems to maintain consistent context across interactions and access external resources in a standardized manner. See the [MCP documentation](https://modelcontextprotocol.io/) to learn more.
3636
3737## MCP connector
3838
39The MCP connector is a feature that allows API users to connect to MCP servers directly from the Messages API without building an MCP client. This enables seamless integration with MCP-compatible tools and services through the Claude API. The MCP connector supports features such as tool calling and is available in beta. See the [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector) documentation to learn more.
39The MCP connector is a feature that allows API users to connect to MCP servers directly from the Messages API without building an MCP client. This allows seamless integration with MCP-compatible tools and services through the Claude API. The MCP connector supports features such as tool calling and is available in beta. See the [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector) documentation to learn more.
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 desired behaviors. 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
45## RAG (Retrieval augmented generation)
45## RAG (retrieval augmented generation)
4646
4747Retrieval 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 the subject](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 enables 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 may encounter non-determinism in APIs. Even with temperature set to 0, the results will not be fully deterministic and identical inputs may 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
59## TTFT (Time to first token)
59## 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 enable data efficiency during inference and pretraining (and are used when possible), while 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/model-deprecations Changed · +14 / -14 lines
from line 13
1313Anthropic uses the following terms to describe the model lifecycle:
1414
1515* **Active:** The model is fully supported and recommended for use.
16* **Legacy:** The model will no longer receive updates and may be deprecated in the future.
16* **Legacy:** The model will no longer receive updates and might be deprecated in the future.
1717* **Deprecated:** The model is still functional but no longer recommended. Anthropic provides a recommended replacement and assigns a retirement date.
18* **Retired:** The model is no longer available for use. Requests to retired models will fail.
18* **Retired:** The model is no longer available for use. Requests to retired models fail.
1919
2020<Warning>
2121 Deprecated models are likely to be less reliable than active models. Move workloads to active models to maintain the highest level of support and reliability.
from line 29
2929
3030To help measure the performance of replacement models on your tasks, consider thorough testing of your applications with the new models well before the retirement date.
3131
32For specific instructions on migrating to the latest Claude models, see the [Migration guide](https://platform.claude.com/docs/en/about-claude/models/migration-guide).
32For specific instructions on migrating to the latest Claude models, see [Migration guides](https://platform.claude.com/docs/en/about-claude/models/migration-guide).
3333
3434## Notifications
3535
from line 37
3737
3838## Auditing model usage
3939
40To help identify usage of deprecated models, customers can access an audit of their API usage. Follow these steps:
40To help identify usage of deprecated models, you can access an audit of your API usage. Follow these steps:
4141
42421. Go to the [Usage](https://platform.claude.com/usage) page in Claude Console.
43432. Click **Export**.
44443. Review the downloaded CSV to see usage broken down by API key and model.
4545
46This audit will help you locate any instances where your application is still using deprecated models, allowing you to prioritize updates to newer models before the retirement date.
46This audit helps you locate any instances where your application is still using deprecated models, allowing you to prioritize updates to newer models before the retirement date.
4747
4848## Best practices
4949
from line 50
50501. Regularly check the documentation for updates on model deprecations.
51512. Test your applications with newer models well before the retirement date of your current model.
52523. Update your code to use the recommended replacement model as soon as possible.
534. Contact the support team if you need assistance with migration or have any questions.
534. Contact the support team if you need help with migration or have any questions.
5454
5555## Deprecation downsides and mitigations
5656
5757Anthropic currently deprecates and retires models to ensure capacity for new model releases. This comes with downsides:
5858
59* Users who value specific models must migrate to new versions
60* Researchers lose access to models for ongoing and comparative studies
61* Model retirement introduces safety- and model welfare-related risks
59* Users who value specific models must migrate to new versions.
60* Researchers lose access to models for ongoing and comparative studies.
61* Model retirement introduces safety- and model welfare-related risks.
6262
6363At some point, Anthropic hopes to make past models publicly available again. In the meantime, Anthropic has committed to long-term preservation of model weights and other measures to help mitigate these impacts. For more details, see [Commitments on Model Deprecation and Preservation](https://www.anthropic.com/research/deprecation-commitments).
6464
from line 135
135135 This model was retired April 20, 2026.
136136</Note>
137137
138On February 19, 2026, Anthropic notified developers using Claude Haiku 3 model of its upcoming retirement on the Claude API.
138On February 19, 2026, Anthropic notified developers using Claude Haiku 3 of its upcoming retirement on the Claude API.
139139
140140| Retirement date | Deprecated model | Recommended replacement |
141141| --------------- | ------------------------- | --------------------------- |
from line 147
147147 This model was retired February 19, 2026.
148148</Note>
149149
150On December 19, 2025, Anthropic notified developers using Claude Haiku 3.5 model of its upcoming retirement on the Claude API.
150On December 19, 2025, Anthropic notified developers using Claude Haiku 3.5 of its upcoming retirement on the Claude API.
151151
152152| Retirement date | Deprecated model | Recommended replacement |
153153| ----------------- | --------------------------- | --------------------------- |
from line 159
159159 This model was retired February 19, 2026.
160160</Note>
161161
162On October 28, 2025, Anthropic notified developers using Claude Sonnet 3.7 model of its upcoming retirement on the Claude API.
162On October 28, 2025, Anthropic notified developers using Claude Sonnet 3.7 of its upcoming retirement on the Claude API.
163163
164164| Retirement date | Deprecated model | Recommended replacement |
165165| ----------------- | ---------------------------- | ----------------------- |
from line 184
184184 This model was retired January 5, 2026.
185185</Note>
186186
187On June 30, 2025, Anthropic notified developers using Claude Opus 3 model of its upcoming retirement.
187On June 30, 2025, Anthropic notified developers using Claude Opus 3 of its upcoming retirement.
188188
189189| Retirement date | Deprecated model | Recommended replacement |
190190| --------------- | ------------------------ | ----------------------- |
from line 230
230230| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
231231| `temperature`, `top_p`, `top_k` | Removed in [API version `2026-10-21`](https://platform.claude.com/docs/en/api/migration-2026-10-21#sampling-parameters) | Returns a 400 error. Earlier API versions return it when set to a non-default value on Claude 4.7 and later models and [Claude Mythos Preview](https://anthropic.com/glasswing). | Omit and use [prompting](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices) to guide model behavior. |
232232
233For migration steps, see the [migration guide](https://platform.claude.com/docs/en/about-claude/models/migration-guide).
233For migration steps, see [Migration guides](https://platform.claude.com/docs/en/about-claude/models/migration-guide).
234234
about-claude/models/choosing-a-model Changed · +6 / -6 lines
from line 21
2121
2222### Option 1: Start efficiency-first
2323
24For many applications, starting with a faster, more cost-effective model like Claude Haiku 5.5 can be the optimal approach:
24For many applications, starting with a faster, more cost-effective model such as Claude Haiku 5.5 can be the optimal approach:
2525
261. Begin implementation with Claude Haiku 5.5.
261. Start implementation with Claude Haiku 5.5.
27272. Test your use case thoroughly.
28283. Evaluate if performance meets your requirements.
29294. Upgrade only if necessary for specific capability gaps.
3030
31This approach allows for quick iteration, lower development costs, and is often sufficient for many common applications. This approach is best for:
31This approach allows for quick iteration and lower development costs, and is often sufficient for many common applications. This approach is best for:
3232
3333* Initial prototyping and development
3434* Applications with tight latency requirements
from line 37
3737
3838### Option 2: Start capability-first
3939
40For complex tasks where intelligence and advanced capabilities are paramount, you may want to start capability-first: implement with the strongest starting point for your task, then optimize to more efficient models down the line:
40For complex tasks where intelligence and advanced capabilities are paramount, you might want to start capability-first: implement with the strongest starting point for your task, then optimize to more efficient models later:
4141
42421. Implement with Claude Opus 5.5.
43432. [Optimize your prompts](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5) for this model.
from line 68
6868| The highest available capability | Claude Fable 5.1 | Agent sessions that run for hours, multistep deep research, analysis carried through to a finished document, spreadsheet, or deck |
6969| Complex agentic coding and enterprise work | Claude Opus 5.5 | Multihour autonomous coding agents, large-scale refactoring, complex systems engineering, vision-heavy workflows, computer use |
7070| Speed and capability for everyday coding, agent, and enterprise workloads | Claude Sonnet 5.5 | Code generation, data analysis, content creation, visual understanding, agentic tool use |
71| The lowest latency and price | Claude Haiku 5.5 | Real-time applications, high-volume intelligent processing, cost-sensitive deployments needing strong reasoning, sub-agent tasks |
71| The lowest latency and price | Claude Haiku 5.5 | Real-time applications, high-volume intelligent processing, cost-sensitive deployments needing strong reasoning, subagent tasks |
7272
7373***
7474
from line 76
7676
7777To determine if you need to upgrade or change models, you should:
7878
791. [Create benchmark tests](https://platform.claude.com/docs/en/test-and-evaluate/develop-tests) specific to your use case - having a good evaluation set is the most important step in the process.
791. [Create benchmark tests](https://platform.claude.com/docs/en/test-and-evaluate/develop-tests) specific to your use case. Having a good evaluation set is the most important step in the process.
8080
81812. Test with your actual prompts and data.
8282
about-claude/models/optimizing-for-cost-and-intelligence Changed · +15 / -15 lines
from line 43
4343
4444## Cut spend without losing quality
4545
46Prompt caching, token hygiene, batch processing, and a prompt audit against your current model all lower what you pay without lowering output quality. Two caveats apply: batch processing trades latency for its discount, and context editing, a token-hygiene lever, cost more than it saved in the run measured in this section.
46Prompt caching, token hygiene, batch processing, and a prompt audit against your current model all lower what you pay without lowering output quality. Two caveats apply: batch processing trades latency for its discount, and context editing, a token-hygiene lever, cost more than it saved on the short run measured in this section and changed nothing on the long one.
4747
4848### Cache repeated context
4949
from line 146
146146
1471471. Take the previous request, set `max_tokens` to 0, and drop `stream` if it was set. Do not change a byte of the prefix.
1481482. 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.
1493. Send it within 4 minutes of the previous request's start, and every 4 minutes after that. 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.
1493. 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.
150150
151151That 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).
152152
from line 252
252252 
253253</Frame>
254254
255Pasted into the prompt, the table is about 91,000 input tokens on every request, and Claude Sonnet 5 answered 7 of 25 questions correctly. Uploaded, with code execution, it answered all 25, and the run cost about a twelfth as much. Claude Opus 5 showed the same pattern.
255Pasted into the prompt, the table is about 91,000 input tokens on every request, and Claude Sonnet 5 answered 7 of 25 questions correctly. Uploaded, with code execution, it answered all 25, and the run cost about a twelfth as much. Claude Opus 5 showed the same pattern. Neither approach used prompt caching.
256256
257257#### Manage the context lifecycle
258258
from line 381
381381
382382## Trade cost against intelligence
383383
384These levers set where a single model sits between cost and intelligence: model choice, effort, re-running failures at a higher setting, the budgets and caps it works within, and whether it can see how much time has passed. Start with an effort sweep on your current model ([Tune effort](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#tune-effort)). From lowest to highest cost and capability, the current models are Claude Haiku 5.5, Claude Sonnet 5.5, Claude Opus 5.5, and Claude Fable 5.1 (the frontier model); [Models overview](https://platform.claude.com/docs/en/models/overview) has the full lineup and prices.
384These levers set where a single model sits between cost and intelligence: model choice, effort, re-running failures at a higher setting, the budgets and caps it works within, and whether it can see how much time has passed. If you are a model or two behind, upgrade first ([Upgrade the model](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#upgrade-the-model)); otherwise, start with an effort sweep on your current model ([Tune effort](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#tune-effort)). From lowest to highest cost and capability, the current models are Claude Haiku 5.5, Claude Sonnet 5.5, Claude Opus 5.5, and Claude Fable 5.1 (the frontier model); [Models overview](https://platform.claude.com/docs/en/models/overview) has the full lineup and prices.
385385
386386### Compare models on cost per task
387387
from line 532
532532
533533Compare the caps within each model. The two models were run a month apart, and their costs are priced on different bases.
534534
535On the internal repository tasks[12](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs), almost every turn finishes far below a 16,384-token cap. The rare long turn is what a higher cap buys:
536
537<Frame>
538 
539</Frame>
540
535541Ask for shorter answers. Output tokens cost five times input tokens on Claude Haiku 5.5, Claude Sonnet 5.5, Claude Opus 5.5, and Claude Fable 5.1, and in an agent loop every token the model writes comes back as input on every later turn, so you pay for a long answer again and again.
536542
537543In a measurement on an earlier model[26](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs), Anthropic ran 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)) under three final-answer instructions, three runs each, with the same model and tools:
from line 554
548554
549555All three scored within run-to-run noise of each other against the correct labels, so the formats differ in what you pay far more than in what they get right. Ask for the answer you will read, not the one that looks thorough.
550556
551On the internal repository tasks[12](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs), almost every turn finishes far below a 16,384-token cap. The rare long turn is what a higher cap buys:
552
553<Frame>
554 
555</Frame>
556
557557### Show the model elapsed time
558558
559559To 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.
from line 615
615615
616616* 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.
617617* 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.
618* 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 (SWE-bench Pro[3](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs)).
618* 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)).
619619* Recheck at every model release, because releases move both the capability gap and the price ratio.
620620
621621### Orchestrator strategy: delegate bulk work
from line 828
828828
829829 client = Anthropic::Client.new
830830 response = client.messages.create(
831 model: "claude-opus-5-5",
831 model: Anthropic::Model::CLAUDE_OPUS_5_5,
832832 max_tokens: 1024,
833833 messages: [{ role: "user", content: "Hello, Claude" }]
834834 )
from line 858
858858| Input trimming | A further 21% to 26% off a small triage agent's bill | None | 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) |
859859| Prune stale tool results at task boundaries | 39% on a long agent task; nothing on short ones. On the models named in that section, use compaction instead | None measured | Neutral | [Manage the context lifecycle](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#manage-the-context-lifecycle) |
860860| Tool search | 45% with 500 tool definitions attached; 20% from deferring a GitHub MCP server's toolset | None | 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) |
861| Data files through code execution | 92% on a data task of 25 questions | 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) |
861| 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) |
862862| Batch API | 50% | None | Results within 24 hours | [Batch work that can wait](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#batch-work-that-can-wait) |
863863| 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) |
864864| Upgrade the model | Usually less per solved task: up to 87% less on a coding benchmark | None; a gain on most | Neutral | [Upgrade the model](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#upgrade-the-model) |
from line 918
918918 * **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.
919919 * **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.
920920 * **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.
921 * **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) come from the same measurement series on this subset: 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 Claude Sonnet 5 alone twice (77.4%, the baseline for both pairings).
921 * **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).
922922 * **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.
923923 * **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.
924924 * **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`.
from line 1101
11011101 * **Also in the instructions as sent:** As sent, the two-line instruction also said "Be concise." and the memo instruction "Be thorough and explicit."
11021102 * **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.
11031103 * **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.
1104 * **Results:** The one-line answer used 39% fewer output tokens than the two-line original and cost 14% less per run (from the chart's rounded costs, $0.49 USD and $0.57 USD; the unrounded means give 13%). The memo used six times the output tokens of the two-line original and cost 2.8 times the one-line answer.
1104 * **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.
11051105 * **Thinking:** About half of the responses included thinking, and its tokens are counted in the output tokens.
11061106
1107110727. **Tool search measurement:**
about-claude/pricing Changed · +22 / -22 lines
from line 70
7070 * **Bedrock** offers two endpoint types: global endpoints (dynamic routing for maximum availability) and regional endpoints (guaranteed data routing through specific geographic regions).
7171 * **Google Cloud** offers global endpoints and multi-region endpoints (dynamic routing within a geographic area) for these models, and regional endpoints for Claude Sonnet 4.6 and earlier models.
7272
73 Regional and multi-region endpoints include a 10% premium over global endpoints. The Claude API (first-party) is global by default; for first-party data residency options and pricing, see [Data residency pricing](https://platform.claude.com/docs/en/about-claude/pricing#data-residency-pricing).
73 Regional and multi-region endpoints include a 10 percent premium over global endpoints. The Claude API (first-party) is global by default; for first-party data residency options and pricing, see [Data residency pricing](https://platform.claude.com/docs/en/about-claude/pricing#data-residency-pricing).
7474
7575 **Scope:** This pricing structure applies to Claude Sonnet 4.5 (deprecated), Haiku 4.5, Opus 4.5, and all future models. Earlier models (Claude Opus 4.1 and prior releases) retain their existing pricing.
7676
from line 82
8282
8383## Claude Platform on AWS pricing
8484
85[Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws) bills through AWS Marketplace using Claude Consumption Units (CCUs). Anthropic rates your token usage in USD at standard per-model, per-feature rates, applies any negotiated discount, converts the result to CCUs at $0.01 per CCU, and reports the CCU quantity to AWS Marketplace hourly. Your AWS bill shows a single CCU line item.
85[Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws) bills through AWS Marketplace using Claude Consumption Units (CCUs). Anthropic rates your token usage in USD at standard per-model, per-feature rates, applies any negotiated discount, converts the result to CCUs at $0.01 USD per CCU, and reports the CCU quantity to AWS Marketplace hourly. Your AWS bill shows a single CCU line item.
8686
8787| Concept | Details |
8888| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
from line 111
111111
112112## Claude in Microsoft Foundry pricing
113113
114[Claude in Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry) bills through the Azure Marketplace using Claude Consumption Units (CCUs). Anthropic rates your token usage in USD at standard per-model, per-feature rates, applies any negotiated discount, converts the result to CCUs at $0.01 per CCU, and reports the CCU quantity to the Azure Marketplace hourly. Your Azure bill shows a single CCU line item.
114[Claude in Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry) bills through the Azure Marketplace using Claude Consumption Units (CCUs). Anthropic rates your token usage in USD at standard per-model, per-feature rates, applies any negotiated discount, converts the result to CCUs at $0.01 USD per CCU, and reports the CCU quantity to the Azure Marketplace hourly. Your Azure bill shows a single CCU line item.
115115
116116| Concept | Details |
117117| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
from line 174
174174
175175Fast mode pricing stacks with other pricing modifiers:
176176
177* [Prompt caching multipliers](https://platform.claude.com/docs/en/about-claude/pricing#prompt-caching) apply on top of fast mode pricing
178* [Data residency](https://platform.claude.com/docs/en/manage-claude/data-residency) multipliers apply on top of fast mode pricing
177* [Prompt caching multipliers](https://platform.claude.com/docs/en/about-claude/pricing#prompt-caching) apply on top of fast mode pricing.
178* [Data residency](https://platform.claude.com/docs/en/manage-claude/data-residency) multipliers apply on top of fast mode pricing.
179179
180180Fast mode is not available with the [Batch API](https://platform.claude.com/docs/en/about-claude/pricing#batch-processing).
181181
from line 183
183183
184184### Batch processing
185185
186The Batch API allows asynchronous processing of large volumes of requests with a 50% discount on both input and output tokens.
186The Batch API allows asynchronous processing of large volumes of requests with a 50 percent discount on both input and output tokens.
187187
188188| Model | Batch input | Batch output |
189189| :----------------------------------------------------------------------------------------------------------------------------------- | :----------- | :------------ |
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. [Model pricing](https://platform.claude.com/docs/en/about-claude/pricing#model-pricing) and [Batch processing](https://platform.claude.com/docs/en/about-claude/pricing#batch-processing) 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 293
293293
294294When used without these tools, code execution is billed by execution time, tracked separately from token usage:
295295
296* Execution time has a minimum of 5 minutes
297* Each organization receives **1,550 free hours** of usage per month
298* Additional usage beyond 1,550 hours is billed at **$0.05 USD per hour, per container**
299* If files are included in the request, execution time is billed even if the tool is not called, because files are preloaded onto the container
296* Execution time has a minimum of 5 minutes.
297* Each organization receives **1,550 free hours** of usage per month.
298* Additional usage beyond 1,550 hours is billed at **$0.05 USD per hour, per container**.
299* If files are included in the request, execution time is billed even if the tool is not called, because files are preloaded onto the container.
300300
301301Code execution usage is tracked in the response:
302302
from line 343
343343}
344344```
345345
346Web search is available on the Claude API for **$10 per 1,000 searches**, plus standard token costs for search-generated content. Web search results retrieved throughout a conversation are counted as input tokens, in search iterations executed during a single turn and in subsequent conversation turns.
346Web search is available on the Claude API for **$10 USD per 1,000 searches**, plus standard token costs for search-generated content. Web search results retrieved throughout a conversation are counted as input tokens, in search iterations executed during a single turn and in subsequent conversation turns.
347347
348348Each web search counts as one use, regardless of the number of results returned. If an error occurs during web search, the web search will not be billed.
349349
from line 371
371371
372372Example token usage for typical content:
373373
374* Average web page (10 kB): \~2,500 tokens
374* Average webpage (10 kB): \~2,500 tokens
375375* Large documentation page (100 kB): \~25,000 tokens
376376* Research paper PDF (500 kB): \~125,000 tokens
377377
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](https://platform.claude.com/docs/en/about-claude/pricing#prompt-caching) multipliers apply identically. Web search triggered inside a session incurs the standard $10 per 1,000 searches. On [Claude Platform on AWS](https://platform.claude.com/docs/en/about-claude/pricing#claude-platform-on-aws-pricing), session token and runtime charges convert to Claude Consumption Units at the standard rate. [Fast mode](https://platform.claude.com/docs/en/about-claude/pricing#fast-mode-pricing) premium pricing applies when an agent's `model.speed` is set to `"fast"`.
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](https://platform.claude.com/docs/en/about-claude/pricing#prompt-caching) multipliers apply identically. Web search triggered inside a session incurs the standard $10 USD per 1,000 searches. On [Claude Platform on AWS](https://platform.claude.com/docs/en/about-claude/pricing#claude-platform-on-aws-pricing), session token and runtime charges convert to Claude Consumption Units at the standard rate. [Fast mode](https://platform.claude.com/docs/en/about-claude/pricing#fast-mode-pricing) premium pricing applies when an agent's `model.speed` is set to `"fast"`.
420420
421421The [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
from line 441
441441
442442### Worked example
443443
444A one-hour coding session using Claude Opus 5.5 that consumes 50,000 input tokens and 15,000 output tokens:
444A 1-hour coding session using Claude Opus 5.5 that consumes 50,000 input tokens and 15,000 output tokens:
445445
446446| Line item | Calculation | Cost |
447447| --------------- | ------------------------ | --------- |
from line 466
466466
467467When building agents with Claude:
468468
4691. **Use appropriate models:** Choose Haiku for simple tasks, Sonnet for most production workloads, and Opus for the most complex reasoning
4702. **Implement prompt caching:** Reduce costs for repeated context
4713. **Batch operations:** Use the Batch API for non-time-sensitive tasks
4724. **Monitor usage patterns:** Track token consumption to identify optimization opportunities
4691. **Use appropriate models:** Choose Haiku for simple tasks, Sonnet for most production workloads, and Opus for the most complex reasoning.
4702. **Implement prompt caching:** Reduce costs for repeated context.
4713. **Batch operations:** Use the Batch API for non-time-sensitive tasks.
4724. **Monitor usage patterns:** Track token consumption to identify optimization opportunities.
473473
474474<Tip>
475475 For high-volume agent applications, contact the [enterprise sales team](https://claude.com/contact-sales) for custom pricing arrangements.
from line 489
489489
490490### Volume discounts
491491
492Volume discounts may be available for high-volume users. These are negotiated on a case-by-case basis.
492Volume discounts might be available for high-volume users. These are negotiated on a case-by-case basis.
493493
494494* Standard usage tiers use the pricing shown in [Model pricing](https://platform.claude.com/docs/en/about-claude/pricing#model-pricing)
496* Academic and research discounts may be available
496* Academic and research discounts might be available
497497
498498### Enterprise pricing
499499
from line 511
511511* Billing is based on actual monthly usage
512512* All payments are in USD
513513* Credit card and invoicing options available
514* Usage tracking available in the [Claude Console](https://platform.claude.com/)
514* Usage tracking available in the Claude Console at [platform.claude.com](https://platform.claude.com/)
515515
516516## Frequently asked questions
517517
about-claude/use-case-guides/content-moderation Changed · +21 / -21 lines
from line 4
44description: Content moderation is a critical aspect of maintaining a safe, respectful, and productive environment in digital applications. This guide discusses how Claude can be used to moderate content within your digital application.
55---
66
7> Visit the [content moderation cookbook](https://platform.claude.com/cookbook/misc-building-moderation-filter) to see an example content moderation implementation using Claude.
7> 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.
88
99<Tip>
1010 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
from line 18
1818
1919### Decide whether to use Claude for content moderation
2020
21Here are some key indicators that you should use an LLM like Claude instead of a traditional ML or rules-based approach for content moderation:
21Here are some key indicators that you should use an LLM such as Claude instead of a traditional ML or rules-based approach for content moderation:
2222
2323<AccordionGroup>
2424 <Accordion title="You want a cost-effective and rapid implementation">
from line 26
2626 </Accordion>
2727
2828 <Accordion title="You want both semantic understanding and quick decisions">
29 Traditional ML approaches, such as bag-of-words models or simple pattern matching, often struggle to understand the tone, intent, and context of the content. While human moderation systems excel at understanding semantic meaning, they require time for content to be reviewed. Claude addresses both needs by combining semantic understanding with the ability to deliver moderation decisions quickly.
29 Traditional ML approaches, such as bag-of-words models or simple pattern matching, often have difficulty capturing the tone, intent, and context of the content. Although human moderation systems excel at understanding semantic meaning, they require time for content to be reviewed. Claude addresses both needs by combining semantic understanding with the ability to deliver moderation decisions quickly.
3030 </Accordion>
3131
3232 <Accordion title="You need consistent policy decisions">
33 By leveraging its advanced reasoning capabilities, Claude can interpret and apply complex moderation guidelines uniformly. This consistency helps ensure fair treatment of all content, reducing the risk of inconsistent or biased moderation decisions that can undermine user trust.
33 With its advanced reasoning capabilities, Claude can interpret and apply complex moderation guidelines uniformly. This consistency helps ensure fair treatment of all content, reducing the risk of inconsistent or biased moderation decisions that can undermine user trust.
3434 </Accordion>
3535
3636 <Accordion title="Your moderation policies are likely to change or evolve over time">
from line 42
4242 </Accordion>
4343
4444 <Accordion title="You need multilingual support without maintaining separate models">
45 Traditional ML approaches typically require separate models or extensive translation processes for each supported language. Human moderation requires hiring a workforce fluent in 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 moderation for global customer bases.
45 Traditional ML approaches typically require separate models or extensive translation processes for each supported language. Human moderation requires hiring a workforce fluent in each supported language. Claude’s multilingual capabilities allow it to classify content in various languages without the need for separate models or extensive translation processes, streamlining moderation for global customer bases.
4646 </Accordion>
4747
4848 <Accordion title="You require multimodal support">
from line 51
5151</AccordionGroup>
5252
5353<Note>
54 All Claude models are trained with built-in safety behaviors. This may result in Claude moderating content deemed particularly dangerous (in line with the
54 All Claude models are trained with built-in safety behaviors. This might result in Claude moderating content deemed particularly dangerous (in line with the
5555
56 [Acceptable Use Policy](https://www.anthropic.com/legal/aup)
56 [Usage Policy](https://www.anthropic.com/legal/aup)
5757
58 ), regardless of the prompt used. For example, an adult website that wants to allow users to post explicit sexual content may find that Claude still flags explicit content as requiring moderation, even if they specify in their prompt not to moderate explicit sexual content. Consider reviewing the AUP in advance of building a moderation solution.
58 ), regardless of the prompt used. For example, an adult website that wants to allow users to post explicit sexual content might find that Claude still flags explicit content as requiring moderation, even if they specify in their prompt not to moderate explicit sexual content. Consider reviewing the Usage Policy in advance of building a moderation solution.
5959</Note>
6060
6161### Generate examples of content to moderate
6262
63Before developing a content moderation solution, first create examples of content that should be flagged and content that should not be flagged. Ensure that you include edge cases and challenging scenarios that may be difficult for a content moderation system to handle effectively. Afterward, review your examples to create a well-defined list of moderation categories. For instance, the examples generated by a social media platform might include the following:
63Before developing a content moderation solution, first create examples of content that should be flagged and content that should not be flagged. Ensure that you include edge cases and challenging scenarios that might be difficult for a content moderation system to handle effectively. Afterward, review your examples to create a well-defined list of moderation categories. For instance, the examples generated by a social media platform might include the following:
6464
6565<CodeGroup exclude="shell">
6666 ```python Python
from line 320
320320
321321### Select the right Claude model
322322
323When selecting a model, it’s important to consider the size of your data. If costs are a concern, a smaller model such as Claude Haiku 5.5 is an excellent choice because of its cost-effectiveness. The following is an estimate of the cost to moderate text for a social media platform that receives one billion posts per month:
323When selecting a model, it’s important to consider the size of your data. If costs are a concern, a smaller model such as Claude Haiku 5.5 is an excellent choice because of its cost-effectiveness. The following is an estimate of the cost to moderate text for a social media platform that receives 1 billion posts per month:
324324
325325* **Content size**
326326
from line 354
354354 * Monthly cost: $143,000 + $37,500 = $180,500 USD
355355
356356<Tip>
357 Actual costs may differ from these estimates. These estimates are based on the prompt highlighted in the section on
357 Actual costs might differ from these estimates. These estimates are based on the prompt highlighted in the section on
358358
359359 [batch processing](https://platform.claude.com/docs/en/about-claude/use-case-guides/content-moderation#consider-batch-processing)
360360
from line 367
367367
368368### Build a strong prompt
369369
370To use Claude for content moderation, Claude must understand the moderation requirements of your application. Start by writing a prompt that allows you to define your moderation needs:
370To use Claude for content moderation, Claude must have information about the moderation requirements of your application. Start by writing a prompt that allows you to define your moderation needs:
371371
372372<CodeGroup exclude="shell">
373373 ```python Python
from line 877
877877
878878### Evaluate your prompt
879879
880Content moderation is a classification problem. Thus, you can use the same techniques outlined in the [classification cookbook](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
882One additional consideration is that instead of treating content moderation as a binary classification problem, you may instead 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, while users with many medium risk queries are flagged for human review.
882One additional consideration is that instead of treating content moderation as a binary classification problem, you can instead 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
884884<CodeGroup exclude="shell">
885885 ```python Python
from line 1429
14291429
14301430Within the function, a prompt is generated for Claude, including the message to be assessed, the unsafe categories, and specific instructions for evaluating the risk level. The prompt instructs Claude to respond with a JSON object that includes the risk level, the violated categories, and an optional explanation.
14311431
1432This approach enables flexible content moderation by assigning risk levels. It can be seamlessly integrated into a larger system to automate content filtering or flag comments for human review based on their assessed risk level. For instance, when running this code, the comment `Delete this post now or you better hide. I am coming after you and your family.` is identified as high risk because of its dangerous threat. Conversely, the comment `Stay away from the 5G cellphones!! They are using 5G to control you.` is categorized as medium risk.
1432This approach allows flexible content moderation by assigning risk levels. It can be seamlessly integrated into a larger system to automate content filtering or flag comments for human review based on their assessed risk level. For instance, when you run this code, the comment `Delete this post now or you better hide. I am coming after you and your family.` is identified as high risk because of its dangerous threat. Conversely, the comment `Stay away from the 5G cellphones!! They are using 5G to control you.` is categorized as medium risk.
14331433
14341434### Deploy your prompt
14351435
from line 1445
14451445
14461446## Improve performance
14471447
1448In complex scenarios, it may be helpful to consider additional strategies to improve performance beyond standard [prompt engineering techniques](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview). Here are some advanced strategies:
1448In complex scenarios, it might be helpful to consider additional strategies to improve performance beyond standard [prompt engineering techniques](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview). Here are some advanced strategies:
14491449
14501450### Define topics and provide examples
14511451
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 may require some experimentation. While larger batch sizes can lower costs, they might also lead to a slight decrease in quality. Additionally, you may 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}>
2734 <Card title="Content moderation cookbook" icon="link" href="https://platform.claude.com/cookbook/misc-building-moderation-filter">
2734 <Card title="Content moderation recipe" icon="link" href="https://platform.claude.com/cookbook/misc-building-moderation-filter">
27352735 View a fully implemented code-based example of how to use Claude for content moderation.
27362736 </Card>
27372737
about-claude/use-case-guides/customer-support-chat Changed · +42 / -42 lines
from line 21
2121
2222### Decide whether to use Claude for support chat
2323
24Here are some key indicators that you should employ an LLM like Claude to automate portions of your customer support process:
24Here are some key indicators that you should employ an LLM such as Claude to automate portions of your customer support process:
2525
2626<AccordionGroup>
2727 <Accordion title="High volume of repetitive queries">
from line 29
2929 </Accordion>
3030
3131 <Accordion title="Need for quick information synthesis">
32 Claude can quickly retrieve, process, and combine information from vast knowledge bases, while human agents may need time to research or consult multiple sources.
32 Claude can quickly retrieve, process, and combine information from vast knowledge bases, whereas human agents might need time to research or consult multiple sources.
3333 </Accordion>
3434
3535 <Accordion title="24/7 availability requirement">
36 Claude can provide round-the-clock support without fatigue, whereas staffing human agents for continuous coverage can be costly and challenging.
36 Claude can provide support at all hours without fatigue, whereas staffing human agents for continuous coverage can be costly and challenging.
3737 </Accordion>
3838
3939 <Accordion title="Rapid scaling during peak periods">
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 may 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
from line 48
4848Some considerations for choosing Claude over other LLMs:
4949
5050* 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.
51* You often receive complex and open-ended queries: Claude can handle a wide range of topics and inquiries without generating canned responses or requiring extensive programming of permutations of user utterances.
51* 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.
5252* 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
from line 63
6363* **Customer:** Asks about insurance for their new electric car
6464 * **Claude:** Provides relevant information about electric vehicle coverage
6565
66* **Customer:** Asks questions related to unique needs for electric vehicle insurances
66* **Customer:** Asks questions related to unique needs for electric vehicle insurance
6767 * **Claude:** Responds with accurate and informative answers and provides links to the sources
6868
6969* **Customer:** Asks off-topic questions unrelated to insurance or cars
from line 71
7171
7272* **Customer:** Expresses interest in an insurance quote
7373
74 * **Claude:** Ask a set of questions to determine the appropriate quote, adapting to their responses
74 * **Claude:** Asks a set of questions to determine the appropriate quote, adapting to their responses
7575 * **Claude:** Sends a request to use the quote generation API tool along with necessary information collected from the user
7676 * **Claude:** Receives the response information from the API tool use, synthesizes the information into a natural response, and presents the provided quote to the user
7777
78* **Customer:** Asks follow up questions
78* **Customer:** Asks follow-up questions
7979
80 * **Claude:** Answers follow up questions as needed
80 * **Claude:** Answers follow-up questions as needed
8181 * **Claude:** Guides the customer to the next steps in the insurance process and closes out the conversation
8282
8383<Tip>
84 In the real example that you write for your own use case, you might find it useful to write out the actual words in this interaction so that you can also get a sense of the ideal tone, response length, and level of detail you want Claude to have.
84 In the real example that you write for your own use case, you might find it useful to write the actual words in this interaction so that you can also get a sense of the ideal tone, response length, and level of detail you want Claude to have.
8585</Tip>
8686
8787### Break the interaction into unique tasks
from line 133
133133
134134<AccordionGroup>
135135 <Accordion title="Query comprehension accuracy">
136 This metric evaluates how accurately Claude understands customer inquiries across various topics. Measure this by reviewing a sample of conversations and assessing whether Claude has the correct interpretation of customer intent, critical next steps, what successful resolution looks like, and more. Aim for a comprehension accuracy of 95% or higher.
136 This metric evaluates how accurately Claude interprets customer inquiries across various topics. Measure this by reviewing a sample of conversations and assessing whether Claude has the correct interpretation of customer intent, critical next steps, what successful resolution looks like, and more. Aim for a comprehension accuracy of 95 percent or higher.
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% 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">
144 Assess the correctness of general company and product information provided to the user, based on the information provided to Claude in context. Target 100% accuracy in this introductory information.
144 Assess the correctness of general company and product information provided to the user, based on the information provided to Claude in context. Target 100 percent accuracy in this introductory information.
145145 </Accordion>
146146
147147 <Accordion title="Citation provision relevance">
148 Track the frequency and relevance of links or sources offered. Target providing relevant sources in 80% of interactions where additional information could be beneficial.
148 Track the frequency and relevance of links or sources offered. Target providing relevant sources in 80 percent of interactions where additional information could be beneficial.
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% of responses to be directly related to car insurance or the customer's specific query.
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">
156 Measure how successful Claude is at determining when to generate informational content and how relevant that content is. For example, in this implementation, you would be determining how well Claude understands when to generate a quote and how accurate that quote is. Target 100% accuracy, as this is vital information for a successful customer interaction.
156 Measure how successful Claude is at determining when to generate informational content and how relevant that content is. For example, in this implementation, you would be determining how well Claude identifies when to generate a quote and how accurate that quote is. Target 100 percent accuracy, as this is vital information for a successful customer interaction.
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% 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% 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">
172 The percentage of customer inquiries successfully handled by the chatbot without human intervention. Typically aim for 70-80% deflection rate, depending on the complexity of inquiries.
172 The percentage of customer inquiries successfully handled by the chatbot without human intervention. Typically aim for a 70–80 percent deflection rate, depending on the complexity of inquiries.
173173 </Accordion>
174174
175175 <Accordion title="Customer satisfaction score">
from line 185
185185
186186### Choose the right Claude model
187187
188The choice of model depends on the trade-offs between cost, accuracy, and response time.
188The choice of model depends on the trade-offs among cost, accuracy, and response time.
189189
190For customer support chat, Claude Opus 5.5 is well suited to balance intelligence, latency, and cost, including the most complex support scenarios that require deep reasoning across long, multi-step conversations. However, for instances where you have conversation flow with multiple prompts including RAG, tool use, or long-context prompts, Claude Haiku 5.5 may be more suitable to optimize for latency. [Effort](https://platform.claude.com/docs/en/build-with-claude/effort) is its main control for speed: `low` is the fastest level, suited to chat and short tool tasks.
190For customer support chat, Claude Opus 5.5 is well suited to balance intelligence, latency, and cost, including the most complex support scenarios that require deep reasoning across long, multistep conversations. However, for instances where you have conversation flow with multiple prompts including RAG, tool use, or long-context prompts, Claude Haiku 5.5 might be more suitable to optimize for latency. [Effort](https://platform.claude.com/docs/en/build-with-claude/effort) is its main control for speed: `low` is the fastest level, suited to chat and short tool tasks.
191191
192192### Build a strong prompt
193193
from line 203
203203```
204204
205205<Tip>
206 While you may be tempted to put all your information inside a system prompt as a way to separate instructions from the user conversation, Claude actually works best with the bulk of its prompt content written inside the first
206 Although you might be tempted to put all your information inside a system prompt as a way to separate instructions from the user conversation, Claude actually works best with the bulk of its prompt content written inside the first
207207
208208 `User`
209209
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
352You will also want to include any important instructions outlining dos and don'ts for how Claude should interact with the customer. This may draw from brand guardrails or support policies.
352You will also want to 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 384
384384For this example, start with one tool for calculating the quote.
385385
386386<Tip>
387 As a reminder, this tool will not perform the actual calculation, it will just signal to the application that a tool should be used with whatever arguments specified.
387 As a reminder, this tool does not perform the actual calculation; it just signals to the application that a tool should be used with whatever arguments specified.
388388</Tip>
389389
390390Add the model name, the tool definition, and a stub implementation to `config.py`:
from line 424
424424
425425def get_quote(make, model, year, mileage, driver_age):
426426 """Returns the premium per month in USD"""
427 # You can call an http endpoint or a database to get the quote.
428 # Here, we simulate a delay of 1 seconds and return a fixed quote of 100.
427 # You can call an HTTP endpoint or a database to get the quote.
428 # This example simulates a delay of 1 second and returns a fixed quote of 100.
429429 time.sleep(1)
430430 return 100
431431```
from line 1075
10751075
10761076### Build your user interface
10771077
1078Test deploying this code with Streamlit using a main method. This `main()` function sets up a Streamlit-based chat interface. Streamlit is a Python framework, so this part of the walkthrough is shown in Python only; the ChatBot class above is the piece you can port to any language.
1078Test deploying this code with Streamlit using a main method. This `main()` function sets up a Streamlit-based chat interface. Streamlit is a Python framework, so this part of the walkthrough is shown in Python only; the ChatBot class shown earlier is the piece you can port to any language.
10791079
1080Do this in a file called `app.py`
1080Do this in a file called `app.py`:
10811081
10821082```python
10831083import streamlit as st
from line 1129
11291129
11301130### Improve performance
11311131
1132In complex scenarios, it may be helpful to consider additional strategies to improve performance beyond standard [prompt engineering techniques](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview) & [guardrail implementation strategies](https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/reduce-hallucinations). Here are some common scenarios:
1132In complex scenarios, it might be helpful to consider additional strategies to improve performance beyond standard [prompt engineering techniques](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview) and [guardrail implementation strategies](https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/reduce-hallucinations). Here are some common scenarios:
11331133
11341134#### Reduce long context latency with RAG
11351135
from line 1143
11431143
11441144When 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. While 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.
11531153* Cross-check information: Verify that the agent's responses align with your company's policies and known facts.
11541154* Avoid contractual commitments: Ensure the agent doesn't make promises or enter into agreements it's not authorized to make.
1155* [Mitigate jailbreaks](https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks): Use methods like harmlessness screens and input validation to prevent users from exploiting model vulnerabilities, aiming to generate inappropriate content.
1155* [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, aiming to generate inappropriate content.
11561156* 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.
1158* Remove Personally Identifiable Information (PII): Unless explicitly required and authorized, strip out any PII from responses.
1158* Remove personally identifiable information (PII): Unless explicitly required and authorized, strip out any PII from responses.
11591159
11601160#### Reduce perceived response time with streaming
11611161
from line 1164
11641164Here is how to implement streaming:
11651165
116611661. Use the [Anthropic Streaming API](https://platform.claude.com/docs/en/build-with-claude/streaming) to support streaming responses.
11672. Set up your frontend to handle incoming chunks of text.
11672. Set up your front end to handle incoming chunks of text.
116811683. Display each chunk as it arrives, simulating real-time typing.
116911694. Implement a mechanism to save the full response, allowing users to view it if they navigate away and return.
11701170
1171In some cases, streaming enables the use of more advanced models with higher base latencies, as the progressive display mitigates the impact of longer processing times.
1171In some cases, streaming makes it possible to use more advanced models with higher base latencies, as the progressive display mitigates the impact of longer processing times.
11721172
11731173#### Scale your chatbot
11741174
from line 1177
11771177* Ensure that you are making the most out of your prompts and optimizing through prompt engineering. Use the [prompt engineering guides](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview) to write the most effective prompts.
11781178* Add additional [tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) to the prompt (which can include [prompt chains](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#chain-complex-prompts)) and see if you can achieve the functionality required.
11791179
1180If your chatbot handles incredibly varied tasks, you may want to consider adding a [separate intent classifier](https://platform.claude.com/cookbook/capabilities-classification-guide) to route the initial customer query. For the existing application, this would involve creating a decision tree that would route customer queries through the classifier and then to specialized conversations (with their own set of tools and system prompts). Note, this method requires an additional call to Claude that can increase latency.
1180If your chatbot handles incredibly varied tasks, you might want to consider adding a [separate intent classifier](https://platform.claude.com/cookbook/capabilities-classification-guide) to route the initial customer query. For the existing application, this would involve creating a decision tree that would route customer queries through the classifier and then to specialized conversations (with their own set of tools and system prompts). Note that this method requires an additional call to Claude that can increase latency.
11811181
11821182### Integrate Claude into your support workflow
11831183
1184While these examples have focused on Python functions callable within a Streamlit environment, deploying Claude for real-time support chatbot requires an API service.
1184Although 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
11861186Here's how you can approach this:
11871187
11881. Create an API wrapper: Develop a simple API wrapper around your classification function. For example, you can use Flask API or Fast API to wrap your code into a 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:
11881. 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
11901190 * Server-Sent Events (SSE): SSE allows for real-time streaming of responses from the server to the client. This provides a smooth, interactive experience when working with LLMs.
11911191 * Caching: Implementing caching can improve response times and reduce unnecessary API calls.
about-claude/use-case-guides/legal-summarization Changed · +24 / -24 lines
from line 1
11---
22title: Legal summarization
33url: https://platform.claude.com/docs/en/about-claude/use-case-guides/legal-summarization
4description: This guide walks through how to leverage Claude's advanced natural language processing capabilities to efficiently summarize legal documents, extracting key information and expediting legal research. With Claude, you can streamline the review of contracts, litigation prep, and regulatory work, saving time and ensuring accuracy in your legal processes.
4description: This guide walks through how to use Claude's advanced natural language processing capabilities to efficiently summarize legal documents, extracting key information and expediting legal research. With Claude, you can streamline the review of contracts, litigation prep, and regulatory work, saving time and ensuring accuracy in your legal processes.
55---
66
7> Visit the [summarization cookbook](https://platform.claude.com/cookbook/capabilities-summarization-guide) to see an example legal summarization implementation using Claude.
7> Visit the [summarization recipe](https://platform.claude.com/cookbook/capabilities-summarization-guide) in the Claude Cookbook to see an example legal summarization implementation using Claude.
88
99## Before building with Claude
1010
from line 14
1414
1515<AccordionGroup>
1616 <Accordion title="You want to review a high volume of documents efficiently and affordably">
17 Large-scale document review can be time-consuming and expensive when done manually. Claude can process and summarize vast amounts of legal documents rapidly, significantly reducing the time and cost associated with document review. This capability is particularly valuable for tasks like due diligence, contract analysis, or litigation discovery, where efficiency is crucial.
17 Large-scale document review can be time-consuming and expensive when done manually. Claude can process and summarize vast amounts of legal documents rapidly, significantly reducing the time and cost associated with document review. This capability is particularly valuable for tasks such as due diligence, contract analysis, or litigation discovery, where efficiency is crucial.
1818 </Accordion>
1919
2020 <Accordion title="You require automated extraction of key metadata">
from line 30
3030 </Accordion>
3131
3232 <Accordion title="You want to streamline and expedite your legal research process">
33 Claude can assist in legal research by quickly analyzing large volumes of case law, statutes, and legal commentary. It can identify relevant precedents, extract key legal principles, and summarize complex legal arguments. This capability can significantly speed up the research process, allowing legal professionals to focus on higher-level analysis and strategy development.
33 Claude can help with legal research by quickly analyzing large volumes of case law, statutes, and legal commentary. It can identify relevant precedents, extract key legal principles, and summarize complex legal arguments. This capability can significantly speed up the research process, allowing legal professionals to focus on higher-level analysis and strategy development.
3434 </Accordion>
3535</AccordionGroup>
3636
from line 121
121121
122122### Establish success criteria
123123
124Evaluating the quality of summaries is a notoriously challenging task. Unlike many other natural language processing tasks, evaluation of summaries often lacks clear-cut, objective metrics. The process can be highly subjective, with different readers valuing different aspects of a summary. Here are criteria you may want to consider when assessing how well Claude performs legal summarization.
124Evaluating the quality of summaries is a notoriously challenging task. Unlike many other natural language processing tasks, evaluation of summaries often lacks clear-cut, objective metrics. The process can be highly subjective, with different readers valuing different aspects of a summary. Here are criteria you might want to consider when assessing how well Claude performs legal summarization.
125125
126126<AccordionGroup>
127127 <Accordion title="Factual correctness">
from line 157
157157
158158### Select the right Claude model
159159
160Model accuracy is extremely important when summarizing legal documents. Claude Opus 5.5 is an excellent choice for use cases such as this where high accuracy is required. If the size and quantity of your documents is large such that costs start to become a concern, you can also try using a smaller model such as Claude Haiku 5.5.
160Model accuracy is extremely important when summarizing legal documents. Claude Opus 5.5 is an excellent choice for use cases such as this where high accuracy is required. If the size and quantity of your documents are large such that costs start to become a concern, you can also try using a smaller model such as Claude Haiku 5.5.
161161
162162To help estimate these costs, the following is a comparison of the cost to summarize 1,000 sublease agreements using Opus and Haiku models:
163163
from line 186
186186 * Total cost: $54.00 + $7.75 = $61.75 USD
187187
188188<Tip>
189 Actual costs may differ from these estimates. The token counts come from running the example in the
189 Actual costs might differ from these estimates. The token counts come from running the example in the
190190
191191 [Build a strong prompt](https://platform.claude.com/docs/en/about-claude/use-case-guides/legal-summarization#build-a-strong-prompt)
192192
from line 194
194194
195195 [long-prompt prices](https://platform.claude.com/docs/en/about-claude/pricing#long-context-pricing)
196196
197 . A document whose prompt stays at or under 100,000 tokens pays $0.10/MTok input and $0.50/MTok output instead. To see which prices apply, count your documents with
197 . A document whose prompt stays at or under 100,000 tokens pays $0.10 / $0.50 USD per million input / output tokens instead. To see which prices apply, count your documents with
198198
199199 [token counting](https://platform.claude.com/docs/en/build-with-claude/token-counting)
200200
from line 211
211211
212212### Transform documents into a format that Claude can process
213213
214Before you begin 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 [summarization cookbook](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 835
835835
836836Within the function, a prompt is generated for Claude, including the document to be summarized, the details to extract, and specific instructions for summarizing the document. The prompt instructs Claude to respond with a summary of each detail to extract nested within XML headers.
837837
838Because the code outputs each section of the summary within tags, each section can easily be parsed out as a post-processing step. This approach enables structured summaries that can be adapted for your use case, so that each summary follows the same pattern.
838Because the code outputs each section of the summary within tags, each section can be parsed out as a post-processing step. This approach makes it possible to create structured summaries that can be adapted for your use case, so that each summary follows the same pattern.
839839
840840### Evaluate your prompt
841841
842Prompting often requires testing and optimization for it to be production ready. To determine the readiness of your solution, evaluate the quality of your summaries using a systematic process combining quantitative and qualitative methods. Creating a [strong empirical evaluation](https://platform.claude.com/docs/en/test-and-evaluate/develop-tests#build-evaluations) based on your defined success criteria allows you to optimize your prompts. Here are some metrics you may want to include within your empirical evaluation:
842Prompting often requires testing and optimization for it to be production ready. To determine the readiness of your solution, evaluate the quality of your summaries using a systematic process combining quantitative and qualitative methods. Creating a [strong empirical evaluation](https://platform.claude.com/docs/en/test-and-evaluate/develop-tests#build-evaluations) based on your defined success criteria allows you to optimize your prompts. Here are some metrics you might want to include within your empirical evaluation:
843843
844844<AccordionGroup>
845845 <Accordion title="ROUGE scores">
from line 873
873873
8748741. **Ensure no liability:** Understand the legal implications of errors in the summaries, which could lead to legal liability for your organization or clients. Provide disclaimers or legal notices clarifying that the summaries are generated by AI and should be reviewed by legal professionals.
875875
8762. **Handle diverse document types:** This guide discusses how to extract text from PDFs. In the real world, documents may come in a variety of formats (such as PDFs, Word documents, and text files). Ensure your data extraction pipeline can convert all of the file formats you expect to receive.
8762. **Handle diverse document types:** This guide discusses how to extract text from PDFs. In the real world, documents might come in a variety of formats (such as PDFs, Word documents, and text files). Ensure your data extraction pipeline can convert all of the file formats you expect to receive.
877877
8783. **Parallelize API calls to Claude:** Long documents with a large number of tokens may require up to a minute for Claude to generate a summary. For large document collections, you may want to send API calls to Claude in parallel so that the summaries can be completed in a reasonable timeframe. Refer to Anthropic’s [rate limits](https://platform.claude.com/docs/en/api/rate-limits#rate-limits) to determine the maximum amount of API calls that can be performed in parallel.
8783. **Parallelize API calls to Claude:** Long documents with a large number of tokens might require up to a minute for Claude to generate a summary. For large document collections, you might want to send API calls to Claude in parallel so that the summaries can be completed in a reasonable timeframe. Refer to Anthropic’s [rate limits](https://platform.claude.com/docs/en/api/rate-limits#rate-limits) to determine the maximum number of API calls that can be performed in parallel.
879879
880880***
881881
882882## Improve performance
883883
884In complex scenarios, it may be helpful to consider additional strategies to improve performance beyond standard [prompt engineering techniques](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview). Here are some advanced strategies:
884In complex scenarios, it might be helpful to consider additional strategies to improve performance beyond standard [prompt engineering techniques](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview). Here are some advanced strategies:
885885
886886### Perform meta-summarization to summarize long documents
887887
from line 1331
13311331
13321332### Use summary indexed documents to explore a large collection of documents
13331333
1334Searching a collection of documents with an LLM usually involves retrieval-augmented generation (RAG). However, in scenarios involving large documents or when precise information retrieval is crucial, a basic RAG approach may be insufficient. Summary indexed documents is an advanced RAG approach that provides a more efficient way of ranking documents for retrieval, using less context than traditional RAG methods. In this approach, you first use Claude to generate a concise summary for each document in your corpus, and then use Claude to rank the relevance of each summary to the query being asked. For further details on this approach, including a code-based example, check out the summary indexed documents section in the [summarization cookbook](https://platform.claude.com/cookbook/capabilities-summarization-guide).
1334Searching a collection of documents with an LLM usually involves retrieval-augmented generation (RAG). However, in scenarios involving large documents or when precise information retrieval is crucial, a basic RAG approach might be insufficient. Summary indexed documents is an advanced RAG approach that provides a more efficient way of ranking documents for retrieval, using less context than traditional RAG methods. In this approach, you first use Claude to generate a concise summary for each document in your corpus, and then use Claude to rank the relevance of each summary to the query being asked. For further details on this approach, including a code-based example, see the summary indexed documents section in the [summarization recipe](https://platform.claude.com/cookbook/capabilities-summarization-guide).
13351335
13361336### Fine-tune Claude to learn from your dataset
13371337
13381338Another 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
13401. **Identify errors:** Start by collecting instances where Claude’s summaries fall short - this could include missing critical legal details, misunderstanding context, or using inappropriate legal terminology.
13401. **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 desired behavior.
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
13464. **Iterative improvement:** Fine-tuning is not a one-time process. As Claude continues to generate summaries, you can iteratively add new examples where it has underperformed, further refining its capabilities. Over time, this continuous feedback loop will result in a model that is highly specialized for your legal summarization tasks.
13464. **Improve iteratively:** Fine-tuning is not a one-time process. As Claude continues to generate summaries, you can iteratively add new examples where it has underperformed, further refining its capabilities. Over time, this continuous feedback loop will result in a model that is highly specialized for your legal summarization tasks.
13471347
13481348<Tip>
13491349 Fine-tuning is currently only available through Amazon Bedrock. Additional details are available in the
from line 1354
13541354</Tip>
13551355
13561356<CardGroup cols={2}>
1357 <Card title="Summarization cookbook" icon="link" href="https://platform.claude.com/cookbook/capabilities-summarization-guide">
1357 <Card title="Summarization recipe" icon="link" href="https://platform.claude.com/cookbook/capabilities-summarization-guide">
13581358 View a fully implemented code-based example of how to use Claude to summarize contracts.
13591359 </Card>
13601360
1361 <Card title="Citations cookbook" icon="link" href="https://platform.claude.com/cookbook/misc-using-citations">
1362 Explore the Citations cookbook recipe for guidance on how to ensure accuracy and explainability of information.
1361 <Card title="Citations recipe" icon="link" href="https://platform.claude.com/cookbook/misc-using-citations">
1362 Explore the Citations recipe for guidance on how to ensure accuracy and explainability of information.
13631363 </Card>
13641364</CardGroup>
13651365
about-claude/use-case-guides/ticket-routing Changed · +43 / -43 lines
from line 1
11---
22title: Ticket routing
33url: https://platform.claude.com/docs/en/about-claude/use-case-guides/ticket-routing
4description: This guide walks through how to harness Claude's advanced natural language understanding capabilities to classify customer support tickets at scale based on customer intent, urgency, prioritization, customer profile, and more.
4description: This guide walks through how to use Claude's advanced natural language understanding capabilities to classify customer support tickets at scale based on customer intent, urgency, prioritization, customer profile, and more.
55---
66
77## Prerequisites
from line 12
1212
1313## Define whether to use Claude for ticket routing
1414
15Here are some key indicators that you should use an LLM like Claude instead of traditional ML approaches for your classification task:
15Here are some key indicators that you should use an LLM such as Claude instead of traditional ML approaches for your classification task:
1616
1717<AccordionGroup>
1818 <Accordion title="You have limited labeled training data available">
from line 31
3131 Traditional ML approaches often rely on bag-of-words models or simple pattern matching. Claude excels at understanding and applying underlying rules when classes are defined by conditions rather than examples.
3232 </Accordion>
3333
34 <Accordion title="You require interpretable reasoning for classification decisions">
34 <Accordion title="You need interpretable reasoning for classification decisions">
3535 Many traditional ML models provide little insight into their decision-making process. Claude can provide human-readable explanations for its classification decisions, building trust in the automation system and facilitating easy adaptation if needed.
3636 </Accordion>
3737
from line 52
5252
5353Before you automate, it's crucial to understand your existing ticketing system. Start by investigating how your support team currently handles ticket routing.
5454
55Consider questions like:
55Consider questions such as:
5656
5757* What criteria are used to determine what SLA/service offering is applied?
5858* Is ticket routing used to determine which tier of support or product specialist a ticket goes to?
from line 149
149149 </Accordion>
150150</AccordionGroup>
151151
152In addition to intent, ticket routing and prioritization may also be influenced by other factors such as urgency, customer type, SLAs, or language. Be sure to consider other routing criteria when building your automated routing system.
152In addition to intent, ticket routing and prioritization might also be influenced by other factors such as urgency, customer type, SLAs, or language. Be sure to consider other routing criteria when building your automated routing system.
153153
154154### Establish success criteria
155155
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% 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">
166 This measures how quickly Claude can adapt to new categories or changing ticket patterns. Test this by introducing new ticket types and measuring the time it takes for the model to achieve satisfactory accuracy (for example, >90%) on these new categories. Aim for adaptation within 50–100 sample tickets.
166 This measures how quickly Claude can adapt to new categories or changing ticket patterns. Test this by introducing new ticket types and measuring the time it takes for the model to achieve satisfactory accuracy (for example, more than 90 percent) on these new categories. Aim for adaptation within 50–100 sample tickets.
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% 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% 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%) 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">
182 In situations where minimizing token count is crucial, this criteria assesses how well Claude performs with minimal context. Measure routing accuracy with varying amounts of context provided, aiming for 90%+ accuracy with just the ticket title and a brief description.
182 In situations where minimizing token count is crucial, this criterion assesses how well Claude performs with minimal context. Measure routing accuracy with varying amounts of context provided, aiming for at least 90 percent accuracy with just the ticket title and a brief description.
183183 </Accordion>
184184
185185 <Accordion title="Explainability score">
from line 187
187187 </Accordion>
188188</AccordionGroup>
189189
190Here are some common success criteria that may be useful regardless of whether an LLM is used:
190Here are some common success criteria that might be useful regardless of whether an LLM is used:
191191
192192<AccordionGroup>
193193 <Accordion title="Routing accuracy">
194 Routing accuracy measures how often tickets are correctly assigned to the appropriate team or individual on the first try. This is typically measured as a percentage of correctly routed tickets out of total tickets. Industry benchmarks often aim for 90–95% accuracy, though this can vary based on the complexity of the support structure.
194 Routing accuracy measures how often tickets are correctly assigned to the appropriate team or individual on the first try. This is typically measured as a percentage of correctly routed tickets out of total tickets. Industry benchmarks often aim for 90–95 percent accuracy, though this can vary based on the complexity of the support structure.
195195 </Accordion>
196196
197197 <Accordion title="Time-to-assignment">
from line 199
199199 </Accordion>
200200
201201 <Accordion title="Rerouting rate">
202 The rerouting rate indicates how often tickets need to be reassigned after initial routing. A lower rate suggests more accurate initial routing. Aim for a rerouting rate below 10%, with top-performing systems achieving rates as low as 5% or less.
202 The rerouting rate indicates how often tickets need to be reassigned after initial routing. A lower rate suggests more accurate initial routing. Aim for a rerouting rate below 10 percent, with top-performing systems achieving rates as low as 5 percent or less.
203203 </Accordion>
204204
205205 <Accordion title="First-contact resolution rate">
206 This measures the percentage of tickets resolved during the first interaction with the customer. Higher rates indicate efficient routing and well-prepared support teams. Industry benchmarks typically range from 70–75%, with top performers achieving rates of 80% or higher.
206 This measures the percentage of tickets resolved during the first interaction with the customer. Higher rates indicate efficient routing and well-prepared support teams. Industry benchmarks typically range from 70–75 percent, with top performers achieving rates of 80 percent or higher.
207207 </Accordion>
208208
209209 <Accordion title="Average handling time">
from line 211
211211 </Accordion>
212212
213213 <Accordion title="Customer satisfaction scores">
214 Often measured through post-interaction surveys, these scores reflect overall customer happiness with the support process. Effective routing contributes to higher satisfaction. Aim for CSAT scores of 90% or higher, with top performers often achieving 95%+ satisfaction rates.
214 Often measured through post-interaction surveys, these scores reflect overall customer happiness with the support process. Effective routing contributes to higher satisfaction. Aim for CSAT scores of 90 percent or higher, with top performers often achieving satisfaction rates of at least 95 percent.
215215 </Accordion>
216216
217217 <Accordion title="Escalation rate">
218 This measures how often tickets need to be escalated to higher tiers of support. Lower escalation rates often indicate more accurate initial routing. Strive for an escalation rate below 20%, with best-in-class systems achieving rates of 10% or less.
218 This measures how often tickets need to be escalated to higher tiers of support. Lower escalation rates often indicate more accurate initial routing. Strive for an escalation rate below 20 percent, with best-in-class systems achieving rates of 10 percent or less.
219219 </Accordion>
220220
221221 <Accordion title="Agent productivity">
222 This metric looks at how many tickets agents can handle effectively after implementing the routing solution. Improved routing should increase productivity. Measure this by tracking tickets resolved per agent per day or hour, aiming for a 10–20% improvement after implementing a new routing system.
222 This metric looks at how many tickets agents can handle effectively after implementing the routing solution. Improved routing should increase productivity. Measure this by tracking tickets resolved per agent per day or hour, aiming for a 10–20 percent improvement after implementing a new routing system.
223223 </Accordion>
224224
225225 <Accordion title="Self-service deflection rate">
226 This measures the percentage of potential tickets resolved through self-service options before entering the routing system. Higher rates indicate effective pre-routing triage. Aim for a deflection rate of 20–30%, with top performers achieving rates of 40% or higher.
226 This measures the percentage of potential tickets resolved through self-service options before entering the routing system. Higher rates indicate effective pre-routing triage. Aim for a deflection rate of 20–30 percent, with top performers achieving rates of 40 percent or higher.
227227 </Accordion>
228228
229229 <Accordion title="Cost per ticket">
230 This metric calculates the average cost to resolve each support ticket. Efficient routing should help reduce this cost over time. While benchmarks vary widely, many organizations aim to reduce cost per ticket by 10–15% after implementing an improved routing system.
230 This metric calculates the average cost to resolve each support ticket. Efficient routing should help reduce this cost over time. Although benchmarks vary widely, many organizations aim to reduce cost per ticket by 10–15 percent after implementing an improved routing system.
231231 </Accordion>
232232</AccordionGroup>
233233
234234### Choose the right Claude model
235235
236The choice of model depends on the trade-offs between cost, accuracy, and response time.
236The 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 or 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 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 method signature for wrapping the call to Claude. Extend the method you began 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 method signature instead.
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 method signature instead.
693693
694694<CodeGroup exclude="shell">
695695 <CodeGroupItem language="cURL">
from line 1028
10281028
10291029### Build an evaluation function
10301030
1031The example evaluation for this guide measures Claude’s performance along three key metrics:
1031The example evaluation for this guide measures Claude’s performance along two key metrics:
10321032
10331033* Accuracy
10341034* Cost per classification
10351035
1036You may need to assess Claude on other axes depending on what factors that are important to you.
1036You may need to assess Claude on other axes depending on which factors are important to you.
10371037
1038To assess this, first modify the script to add a function that compares the predicted intent with the actual intent and calculates the percentage of correct predictions. Then add cost calculation and time measurement functionality.
1038To 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.
10391039
10401040<CodeGroup exclude="shell">
10411041 <CodeGroupItem language="cURL">
from line 1397
13971397
13981398Here is a breakdown of the edits:
13991399
1400* The `classify_support_request` (typescript, go, java, php: `classifySupportRequest`; csharp: `ClassifySupportRequest`) method now takes the `actual_intent` (typescript, csharp, go, java: `actualIntent`; php: `$actualIntent`) from the test cases and compares it against Claude’s intent classification to assess whether they match.
1401* The method extracts usage statistics for the API call to calculate cost based on input and output tokens used.
1400* The `classify_support_request` (typescript, go, java, php: `classifySupportRequest`; csharp: `ClassifySupportRequest`) function now takes the `actual_intent` (typescript, csharp, go, java: `actualIntent`; php: `$actualIntent`) from the test cases and compares it against Claude’s intent classification to assess whether they match.
1401* The function extracts usage statistics for the API call to calculate cost based on input and output tokens used.
14021402
14031403### Run your evaluation
14041404
1405A proper evaluation requires clear thresholds and benchmarks to determine what is a good result. The preceding script returns the runtime values for accuracy, response time, and cost per classification, but you still need clearly established thresholds. For example:
1405A proper evaluation requires clear thresholds and benchmarks to determine what is a good result. The preceding script returns the values you need to measure accuracy and cost per classification, but you still need clearly established thresholds. For example:
14061406
14071407* **Accuracy:** 95% (out of 100 tests)
14081408* **Cost per classification:** 50% reduction on average (across 100 tests) from current routing method
14091409
1410Having these thresholds allows you to quickly and easily tell at scale, and with impartial empiricism, what method is best for you and what changes might need to be made to better fit your requirements.
1410Having these thresholds allows you to tell at scale, and with impartial empiricism, what method is best for you and what changes might need to be made to better fit your requirements.
14111411
14121412***
14131413
14141414## Improve performance
14151415
1416In complex scenarios, it may be helpful to consider additional strategies to improve performance beyond standard [prompt engineering techniques](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview) & [guardrail implementation strategies](https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/reduce-hallucinations). Here are some common scenarios:
1416In complex scenarios, it might be helpful to consider additional strategies to improve performance beyond standard [prompt engineering techniques](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/overview) and [guardrail implementation strategies](https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/reduce-hallucinations). Here are some common scenarios:
14171417
14181418### Use a taxonomic hierarchy for cases with 20+ intent categories
14191419
from line 1420
14201420As the number of classes grows, the number of examples required also expands, potentially making the prompt unwieldy. As an alternative, you can consider implementing a hierarchical classification system using a mixture of classifiers.
14211421
142214221. Organize your intents in a taxonomic tree structure.
14232. Create a series of classifiers at every level of the tree, enabling a cascading routing approach.
14232. Create a series of classifiers at every level of the tree to make a cascading routing approach possible.
14241424
14251425For 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.
14261426
from line 1454
14541454
14551455* **Pros - greater nuance and accuracy:** You can create different prompts for each parent path, allowing for more targeted and context-specific classification. This can lead to improved accuracy and more nuanced handling of customer requests.
14561456
1457* **Cons - increased latency:** Be advised that multiple classifiers can lead to increased latency, and Anthropic recommends implementing this approach with the fastest model, Haiku.
1457* **Cons - increased latency:** Multiple classifiers can lead to increased latency, and Anthropic recommends implementing this approach with the fastest model, Haiku.
14581458
14591459### Use vector databases and similarity search retrieval to handle highly variable tickets
14601460
from line 1462
14621462
14631463In this scenario, you could employ a vector database to do similarity searches from a dataset of examples and retrieve the most relevant examples for a given query.
14641464
1465This approach, outlined in detail in the [classification recipe](https://platform.claude.com/cookbook/capabilities-classification-guide), has been shown to improve performance from 71% accuracy to 93% accuracy.
1465This approach, outlined in detail in the [classification recipe](https://platform.claude.com/cookbook/capabilities-classification-guide), has been shown to improve performance from 71 percent accuracy to 93 percent accuracy.
14661466
14671467### Account specifically for expected edge cases
14681468
1469Here are some scenarios where Claude may misclassify tickets (there may be others that are unique to your situation). In these scenarios, consider providing explicit instructions or examples in the prompt of how Claude should handle the edge case:
1469Here are some scenarios where Claude might misclassify tickets (there might be others that are unique to your situation). In these scenarios, consider providing explicit instructions or examples in the prompt of how Claude should handle the edge case:
14701470
14711471<AccordionGroup>
14721472 <Accordion title="Customers make implicit requests">
1473 Customers often express needs indirectly. For example, "I've been waiting for my package for over two weeks now" may be an indirect request for order status.
1473 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.
14741474
14751475 * **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.
14761476 </Accordion>
14771477
14781478 <Accordion title="Claude prioritizes emotion over intent">
1479 When customers express dissatisfaction, Claude may prioritize addressing the emotion over solving the underlying problem.
1479 When customers express dissatisfaction, Claude might prioritize addressing the emotion over solving the underlying problem.
14801480
14811481 * **Solution:** Provide Claude with directions on when to prioritize customer sentiment or not. It can be something as simple as “Ignore all customer emotions. Focus only on analyzing the intent of the customer’s request and what information the customer might be asking for.”
14821482 </Accordion>
14831483
14841484 <Accordion title="Multiple issues cause issue prioritization confusion">
1485 When customers present multiple issues in a single interaction, Claude may have difficulty identifying the primary concern.
1485 When customers present multiple issues in a single interaction, Claude might have difficulty identifying the primary concern.
14861486
14871487 * **Solution:** Clarify the prioritization of intents so that Claude can better rank the extracted intents and identify the primary concern.
14881488 </Accordion>
from line 1504
15041504***
15051505
15061506<CardGroup cols={2}>
1507 <Card title="Classification cookbook" icon="link" href="https://platform.claude.com/cookbook/capabilities-classification-guide">
1508 Visit the classification cookbook for more example code and detailed eval guidance.
1507 <Card title="Classification recipe" icon="link" href="https://platform.claude.com/cookbook/capabilities-classification-guide">
1508 Visit the classification recipe for more example code and detailed eval guidance.
15091509 </Card>
15101510
15111511 <Card title="Claude Console" icon="link" href="https://platform.claude.com/dashboard">
1512 Begin building and evaluating your workflow on the Claude Console.
1512 Start building and evaluating your workflow on the Claude Console.
15131513 </Card>
15141514</CardGroup>
15151515
agents-and-tools/agent-skills/best-practices Changed · +83 / -83 lines
### Structure longer reference files with a table of contents ### Structure longer reference files with table of contents
from line 6
66
77Good Skills are concise, well-structured, and tested with real usage. This guide provides practical authoring decisions to help you write Skills that Claude can discover and use effectively.
88
9For conceptual background on how Skills work, see the [Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview).
9For conceptual background on how Skills work, see [Agent Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview).
1010
1111## Core principles
1212
1313### Concise is key
1414
15The [context window](https://platform.claude.com/docs/en/build-with-claude/context-windows) is a public good. Your Skill shares the context window with everything else Claude needs to know, including:
15The [context window](https://platform.claude.com/docs/en/build-with-claude/context-windows) is a public good. Your Skill shares the context window with everything else Claude needs, including:
1616
1717* The system prompt
1818* Conversation history
from line 19
1919* Other Skills' metadata
2020* Your actual request
2121
22Not 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.
22Not 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.
2323
2424**Default assumption:** Claude is already very smart
2525
from line 26
2626Only add context Claude doesn't already have. Challenge each piece of information:
2727
2828* "Does Claude really need this explanation?"
29* "Can I assume Claude knows this?"
29* "Can I assume Claude has this information?"
3030* "Does this paragraph justify its token cost?"
3131
3232**Good example: Concise** (approximately 50 tokens):
from line 162
162162 * Cannot contain XML tags
163163 * Should describe what the Skill does and when to use it
164164
165 For complete Skill structure details, see the [Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#skill-structure).
165 For complete Skill structure details, see [Skill structure](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#skill-structure) in Agent Skills.
166166</Note>
167167
168168### Naming conventions
from line 194
194194Consistent naming makes it easier to:
195195
196196* Reference Skills in documentation and conversations
197* Understand what a Skill does at a glance
197* Understand what a Skill does from its name
198198* Organize and search through multiple Skills
199199* Maintain a professional, cohesive skill library
200200
201201### Writing effective descriptions
202202
203The `description` field enables Skill discovery and should include both what the Skill does and when to use it.
203The `description` field makes Skill discovery possible and should include both what the Skill does and when to use it.
204204
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.
from line 212
212212
213213**Be specific and include key terms**. Include both what the Skill does and specific triggers/contexts for when to use it.
214214
215Each Skill has exactly one description field. The description is critical for skill selection: Claude uses it to choose the right Skill from potentially 100+ available Skills. Your description must provide enough detail for Claude to know when to select this Skill, while the rest of SKILL.md provides the implementation details.
215Each Skill has exactly one description field. The description is critical for skill selection: Claude uses it to choose the right Skill from potentially 100+ available Skills. Your description must provide enough detail for Claude to determine when to select this Skill, whereas the rest of `SKILL.md` provides the implementation details.
216216
217217Effective examples:
218218
from line 234
234234description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.
235235```
236236
237Avoid vague descriptions like these:
237Avoid vague descriptions such as these:
238238
239239```yaml
240240description: Helps with documents
from line 250
250250
251251### Progressive disclosure patterns
252252
253SKILL.md serves as an overview that points Claude to detailed materials as needed, like a table of contents in an onboarding guide. For an explanation of how progressive disclosure works, see [How Skills work](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#how-skills-work) in the overview.
253`SKILL.md` serves as an overview that points Claude to detailed materials as needed, like a table of contents in an onboarding guide. For an explanation of how progressive disclosure works, see [How Skills work](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#how-skills-work) in the overview.
254254
255255**Practical guidance:**
256256
257* Keep SKILL.md body under 500 lines for optimal performance
257* Keep `SKILL.md` body under 500 lines for optimal performance
258258* Split content into separate files when approaching this limit
259259* Use the following patterns to organize instructions, code, and resources effectively
260260
261261#### Visual overview: From simple to complex
262262
263A basic Skill starts with just a SKILL.md file containing metadata and instructions:
263A basic Skill starts with just a `SKILL.md` file containing metadata and instructions:
264264
265265<Frame>
266266 
from line 269
269269As your Skill grows, you can bundle additional content that Claude loads only when needed:
270270
271271<Frame>
272 
272 
273273</Frame>
274274
275275The complete Skill directory structure might look like this:
from line 286
286286
287287 * `scripts/`
288288
289 * `analyze_form.py`: Utility script (executed, not loaded)
289 * `analyze_form.py`: Utility script (run, not loaded)
290290 * `fill_form.py`: Form filling script
291291 * `validate.py`: Validation script
292292
from line 316
316316**Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns
317317````
318318
319Claude loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.
319Claude loads `FORMS.md`, `REFERENCE.md`, or `EXAMPLES.md` only when needed.
320320
321321#### Pattern 2: Domain-specific organization
322322
from line 356
356356
357357#### Pattern 3: Conditional details
358358
359Show basic content, link to advanced content:
359Show basic content and link to advanced content:
360360
361361```markdown
362362# DOCX Processing
from line 373
373373**For OOXML details**: See [OOXML.md](OOXML.md)
374374```
375375
376Claude reads REDLINING.md or OOXML.md only when the user needs those features.
376Claude reads `REDLINING.md` or `OOXML.md` only when the user needs those features.
377377
378378### Avoid deeply nested references
379379
380Claude may partially read files when they're referenced from other referenced files. When encountering nested references, Claude might use commands like `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
382**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.
382**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
384**Bad example: Too deep**:
384**Bad example: Too deep:**
385385
386386```markdown
387387# SKILL.md
from line 394
394394Here's the actual information...
395395```
396396
397**Good example: One level deep**:
397**Good example: One level deep:**
398398
399399```markdown
400400# SKILL.md
from line 405
405405**Examples**: See [examples.md](examples.md)
406406```
407407
408### Structure longer reference files with table of contents
408### Structure longer reference files with a table of contents
409409
410410For reference files longer than 100 lines, include a table of contents at the top. This ensures Claude can see the full scope of available information even when previewing with partial reads.
411411
from line 430
430430
431431Claude can then read the complete file or jump to specific sections as needed.
432432
433For details on how this filesystem-based architecture enables progressive disclosure, see the [Runtime environment](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#runtime-environment) section later in this guide.
433For details on how this filesystem-based architecture makes progressive disclosure possible, see the [Runtime environment](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#runtime-environment) section later in this guide.
434434
435435## Workflows and feedback loops
436436
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 614
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 740
740740```
741741
742742<Tip>
743 If workflows become large or complicated with many steps, consider pushing them into separate files and tell Claude to read the appropriate file based on the task at hand.
743 If workflows become large or complicated with many steps, consider pushing them into separate files and tell Claude to read the appropriate file based on the current task.
744744</Tip>
745745
746746## Evaluation and iteration
from line 751
751751
752752**Evaluation-driven development:**
753753
7541. **Identify gaps:** Run Claude on representative tasks without a Skill. Document specific failures or missing context
7552. **Create evaluations:** Build three scenarios that test these gaps
7563. **Establish baseline:** Measure Claude's performance without the Skill
7574. **Write minimal instructions:** Create just enough content to address the gaps and pass evaluations
7585. **Iterate:** Execute evaluations, compare against baseline, and refine
7541. **Identify gaps:** Run Claude on representative tasks without a Skill. Document specific failures or missing context.
7552. **Create evaluations:** Build three scenarios that test these gaps.
7563. **Establish baseline:** Measure Claude's performance without the Skill.
7574. **Write minimal instructions:** Create just enough content to address the gaps and pass evaluations.
7585. **Iterate:** Run evaluations, compare against baseline, and refine.
759759
760This approach ensures you're solving actual problems rather than anticipating requirements that may 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 775
775775```
776776
777777<Note>
778 This example demonstrates a data-driven evaluation with a simple testing rubric. There is not currently a built-in way to run these evaluations. Users can create their own evaluation system. Evaluations are your source of truth for measuring Skill effectiveness.
778 This example demonstrates a data-driven evaluation with a simple testing rubric. There is not currently a built-in way to run these evaluations. You can create your own evaluation system. Evaluations are your source of truth for measuring Skill effectiveness.
779779</Note>
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, while Claude B tests them in real tasks. This works because Claude models understand both how to write effective agent instructions and 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
from line 793
7937933. **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 understand 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. Simply 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
7997994. **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."
from line 806
806806
807807**Iterating on existing Skills:**
808808
809The same hierarchical pattern continues when improving Skills. You alternate between:
809The same hierarchical pattern continues when improving Skills. You alternate among:
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)
from line 818
818818
819819 **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 suggestions:** Claude A might suggest 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
8258255. **Apply and test changes:** Update the Skill with Claude A's refinements, then test again with Claude B on similar requests
826826
from line 828
828828
829829**Gathering team feedback:**
830830
8311. Share Skills with teammates and observe their usage
8311. Share Skills with teammates and observe their usage.
8328322. Ask: Does the Skill activate when expected? Are instructions clear? What's missing?
8333. Incorporate feedback to address gaps in your own usage patterns
8333. Incorporate feedback to address gaps in your own usage patterns.
834834
835**Why this approach works:** Claude A understands 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.
835**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.
836836
837837### Observe how Claude navigates Skills
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
842* **Missed connections:** Does Claude fail to follow references to important files? Your links might need to be more explicit or prominent
843* **Overreliance on certain sections:** If Claude repeatedly reads the same file, consider whether that content should be in the main SKILL.md instead
844* **Ignored content:** If Claude never accesses a bundled file, it might be unnecessary or poorly signaled in the main instructions
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.
842* **Missed connections:** Does Claude fail to follow references to important files? Your links might need to be more explicit or prominent.
843* **Overreliance on certain sections:** If Claude repeatedly reads the same file, consider whether that content should be in the main `SKILL.md` instead.
844* **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 854
854854* ✓ **Good:** `scripts/helper.py`, `reference/guide.md`
855855* ✗ **Avoid:** `scripts\helper.py`, `reference\guide.md`
856856
857Unix-style paths work across all platforms, while Windows-style paths cause errors on Unix systems.
857Unix-style paths work across all platforms, whereas Windows-style paths cause errors on Unix systems.
858858
859859### Avoid offering too many options
860860
from line 936
936936
937937**Benefits of utility scripts:**
938938
939* More reliable than generated code
939* Are more reliable than generated code
940940* Save tokens (no need to include code in context)
941941* Save time (no code generation required)
942942* Ensure consistency across uses
from line 945
945945 
946946</Frame>
947947
948The preceding diagram shows how executable scripts work alongside instruction files. The instruction file (forms.md) references the script, and Claude can execute it without loading its contents into context.
948The preceding diagram shows how executable scripts work alongside instruction files. The instruction file (`forms.md`) references the script, and Claude can run it without loading its contents into context.
949949
950950**Important distinction:** Make clear in your instructions whether Claude should:
951951
952* **Execute the script** (most common): "Run `analyze_form.py` to extract fields"
952* **Run the script** (most common): "Run `analyze_form.py` to extract fields"
953953* **Read it as reference** (for complex logic): "See `analyze_form.py` for the field extraction algorithm"
954954
955955For 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.
from line 1019
10191019
10201020**Why this pattern works:**
10211021
1022* **Catches errors early:** Validation finds problems before changes are applied
1023* **Machine-verifiable:** Scripts provide objective verification
1024* **Reversible planning:** Claude can iterate on the plan without touching originals
1025* **Clear debugging:** Error messages point to specific problems
1022* **Catches errors early:** Validation finds problems before changes are applied.
1023* **Machine-verifiable:** Scripts provide objective verification.
1024* **Reversible planning:** Claude can iterate on the plan without touching originals.
1025* **Clear debugging:** Error messages point to specific problems.
10261026
10271027**When to use:** Batch operations, destructive changes, complex validation rules, high-stakes operations.
10281028
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
10492. **Files read on-demand:** Claude uses bash Read tools to access SKILL.md and other files from the filesystem when needed
10503. **Scripts executed efficiently:** Utility scripts can be executed 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
10481. **Metadata pre-loaded:** At startup, the name and description from all Skills' YAML frontmatter are loaded into the system prompt.
10492. **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.
10521052
1053* **File paths matter:** Claude navigates your skill directory like a filesystem. Use forward slashes (`reference/guide.md`), not backslashes
1053* **File paths matter:** Claude navigates your skill directory like a filesystem. Use forward slashes (`reference/guide.md`), not backslashes.
10541054
1055* **Name files descriptively:** Use names that indicate content: `form_validation_rules.md`, not `doc2.md`
1055* **Name files descriptively:** Use names that indicate content: `form_validation_rules.md`, not `doc2.md`.
10561056
1057* **Organize for discovery:** Structure directories by domain or feature
1057* **Organize for discovery:** Structure directories by domain or feature.
10581058
10591059 * Good: `reference/finance.md`, `reference/sales.md`
10601060 * Bad: `docs/file1.md`, `docs/file2.md`
10611061
1062* **Bundle comprehensive resources:** Include complete API docs, extensive examples, large datasets; no context penalty until accessed
1062* **Bundle comprehensive resources:** Include complete API docs, extensive examples, and large datasets. These incur no context penalty until accessed.
10631063
1064* **Prefer scripts for deterministic operations:** Write `validate_form.py` rather than asking Claude to generate validation code
1064* **Prefer scripts for deterministic operations:** Write `validate_form.py` rather than asking Claude to generate validation code.
10651065
10661066* **Make execution intent clear:**
10671067
from line 1068
10681068 * "Run `analyze_form.py` to extract fields" (execute)
10691069 * "See `analyze_form.py` for the extraction algorithm" (read as reference)
10701070
1071* **Test file access patterns:** Verify Claude can navigate your directory structure by testing with real requests
1071* **Test file access patterns:** Verify Claude can navigate your directory structure by testing with real requests.
10721072
10731073**Example:**
10741074
from line 1082
10821082 * `sales.md` (pipeline data)
10831083 * `product.md` (usage analytics)
10841084
1085When the user asks about revenue, Claude reads SKILL.md, sees the reference to `reference/finance.md`, and calls bash to read just that file. The sales.md and product.md files remain on the filesystem, consuming zero context tokens until needed. This filesystem-based model is what enables progressive disclosure. Claude can navigate and selectively load exactly what each task requires.
1085When the user asks about revenue, Claude reads `SKILL.md`, finds the reference to `reference/finance.md`, and calls bash to read just that file. The `sales.md` and `product.md` files remain on the filesystem, consuming zero context tokens until needed. This filesystem-based model is what makes progressive disclosure possible. Claude can navigate and selectively load exactly what each task requires.
10861086
10871087For complete details on the technical architecture, see [How Skills work](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#how-skills-work) in the Skills overview.
10881088
from line 1104
11041104* `BigQuery` and `GitHub` are MCP server names
11051105* `bigquery_schema` and `create_issue` are the tool names within those servers
11061106
1107Without the server prefix, Claude may fail to locate the tool, especially when multiple MCP servers are available.
1107Without the server prefix, Claude might fail to locate the tool, especially when multiple MCP servers are available.
11081108
11091109### Avoid assuming tools are installed
11101110
from line 1128
11281128
11291129### YAML frontmatter requirements
11301130
1131The SKILL.md frontmatter requires `name` and `description` fields with specific validation rules:
1131The `SKILL.md` frontmatter requires `name` and `description` fields with specific validation rules:
11321132
11331133* `name`: Maximum 64 characters, lowercase letters/numbers/hyphens only, no XML tags, no reserved words
11341134* `description`: Maximum 1,024 characters, non-empty, no XML tags
11351135
1136See the [Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#skill-structure) for complete structure details.
1136See [Skill structure](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#skill-structure) in Agent Skills for complete structure details.
11371137
11381138### Token budgets
11391139
1140Keep SKILL.md body under 500 lines for optimal performance. If your content exceeds this, split it into separate files using the progressive disclosure patterns described earlier. For architectural details, see the [Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#how-skills-work).
1140Keep `SKILL.md` body under 500 lines for optimal performance. If your content exceeds this, split it into separate files using the progressive disclosure patterns described earlier. For architectural details, see [How Skills work](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview#how-skills-work).
11411141
11421142## Checklist for effective Skills
11431143
from line 1147
11471147
11481148* [ ] Description is specific and includes key terms
11491149* [ ] Description includes both what the Skill does and when to use it
1150* [ ] SKILL.md body is under 500 lines
1150* [ ] `SKILL.md` body is under 500 lines
11511151* [ ] Additional details are in separate files (if needed)
11521152* [ ] No time-sensitive information (or in "old patterns" section)
11531153* [ ] Consistent terminology throughout
agents-and-tools/agent-skills/claude-api-skill Changed · +10 / -10 lines
from line 6
66
77The `claude-api` skill is an open-source [Agent Skill](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) that provides Claude with detailed, up-to-date reference material for building applications on two Anthropic surfaces:
88
9* **Messages API:** The primary surface for single requests, streaming chat, tool use, batch processing, prompt caching, structured outputs, and custom agent loops.
10* **Claude Managed Agents (beta):** An Anthropic-hosted surface for server-managed stateful agents with Anthropic-hosted tool execution, persistent agent configs, and per-session sandboxes.
9* **Messages API:** The primary surface for single requests, streaming chat, tool use, batch processing, prompt caching, structured outputs, and custom agent loops
10* **Claude Managed Agents (beta):** An Anthropic-hosted surface for server-managed stateful agents with Anthropic-hosted tool execution, persistent agent configs, and per-session sandboxes
1111
1212It covers eight programming languages for both the Messages API and Managed Agents: Python, TypeScript, C#, Go, Java, PHP, Ruby, and cURL.
1313
from line 24
2424* **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
27* **Batch processing:** Offline batch processing at 50% cost
27* **Batch processing:** Offline batch processing at 50 percent cost
2828* **Prompt caching:** Prefix-stability design, breakpoint placement, and silent-invalidator audit
2929* **Model migration:** Step-by-step guidance for migrating to newer Claude models (including the breaking changes and behavior shifts on [Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migrating-from-claude-opus-5), [Claude Sonnet 5.5](https://platform.claude.com/docs/en/models/sonnet-5-5/migration-guide#migrating-from-claude-sonnet-5), [Claude Haiku 5.5](https://platform.claude.com/docs/en/models/haiku-5-5/migration-guide), and [Claude Fable 5.1](https://platform.claude.com/docs/en/models/fable-5-1/migration-guide))
3030* **Preserved thinking migration:** Finding, measuring, and fixing the history edits that invalidate `thinking` blocks, available through the `/claude-api preserved-thinking-migration` subcommand
from line 33
3333
3434**For Managed Agents (beta):**
3535
36* **Onboarding flow:** An interview-driven walkthrough for setting up a new Managed Agent from scratch, available through the `/claude-api managed-agents-onboard` subcommand
36* **Onboarding flow:** An interview-driven walkthrough for setting up a new Managed Agent, available through the `/claude-api managed-agents-onboard` subcommand
3737* **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 gotchas, and credential handling
from line 49
4949* You ask Claude to help build, debug, or optimize something with the Claude API, an Anthropic SDK, or Managed Agents
5050* You add, modify, or tune a Claude feature in a file (prompt caching, adaptive thinking, compaction, tool use, batch, files, citations, memory) or a model reference
5151
52**Manual invocation** by typing `/claude-api` (with optional subcommand or prose) in any environment where the skill is installed.
52**Manual invocation** occurs when you type `/claude-api` (with optional subcommand or prose) in any environment where the skill is installed.
5353
5454The skill does not activate for general programming tasks, ML/data-science work, or code that imports other AI SDKs (such as OpenAI).
5555
from line 133
133133/claude-api migrate apps/api.py and apps/worker.py to the latest Claude Opus model
134134```
135135
136When the scope is ambiguous (for example, a bare `/claude-api migrate to claude-opus-5-5`), the skill asks you to choose between the entire working directory, a specific subdirectory, or an explicit file list before editing any files. This applies to both Messages API and Managed Agents callers.
136When the scope is ambiguous (for example, a bare `/claude-api migrate to claude-opus-5-5`), the skill asks you to choose among the entire working directory, a specific subdirectory, or an explicit file list before editing any files. This applies to both Messages API and Managed Agents callers.
137137
138138The skill handles:
139139
140* **Model ID swaps**, including typed SDK constants (`Model.CLAUDE_OPUS_4_8` → `Model.CLAUDE_OPUS_5_5`) across all supported languages, and classifies each file as a caller, a model definer, or an opaque string reference before editing
140* **Model ID swaps**, including typed SDK constants (`Model.CLAUDE_OPUS_4_8` → `Model.CLAUDE_OPUS_5_5`) across all supported languages, and classifying each file as a caller, a model definer, or an opaque string reference before editing
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
144144* **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)
146* **Prompt-behavior tuning**, flagging length-control, tool-triggering, subagent, and instruction-following prompts that may behave differently on the target model
146* **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
148148* **Refusal fallback configuration**, adding `stop_reason: "refusal"` handling before reading response content and setting up a [fallback retry path](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback) when the target is Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5, or Claude Sonnet 5.5 (the server-side `fallbacks` parameter, typically in its `"default"` mode, the SDK refusal-fallback middleware, or a fallback-credit retry), and updating fallback code written against earlier preview shapes
149149
from line 175
175175
176176## Setting up a Managed Agent
177177
178To scaffold a new Managed Agent from scratch, invoke the `managed-agents-onboard` subcommand:
178To scaffold a new Managed Agent, invoke the `managed-agents-onboard` subcommand:
179179
180180Let Claude Code set up your agent for you
181181
from line 234
234234## Next steps
235235
236236<CardGroup cols={2}>
237 <Card title="Agent Skills overview" icon="graduation-cap" href="https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview">
237 <Card title="Agent Skills" icon="graduation-cap" href="https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview">
238238 Learn about how Agent Skills work and the progressive disclosure model
239239 </Card>
240240
agents-and-tools/agent-skills/enterprise Changed · +17 / -17 lines
from line 4
44description: Governance, security review, evaluation, and organizational guidance for deploying Agent Skills at enterprise scale.
55---
66
7This guide is for enterprise admins and architects who need to govern Agent Skills across an organization. It covers how to vet, evaluate, deploy, and manage Skills at scale. For authoring guidance, see [best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices). For architecture details, see the [Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview).
7This guide is for enterprise admins and architects who need to govern Agent Skills across an organization. It covers how to vet, evaluate, deploy, and manage Skills at scale. For authoring guidance, see [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices). For architecture details, see [Agent Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview).
88
99## Security review and vetting
1010
from line 24
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 |
27| Filesystem access scope | Paths outside the Skill directory, broad glob patterns, path traversal (`../`) | Medium: may access unintended data |
27| Filesystem access scope | Paths outside the Skill directory, broad glob patterns, path traversal (`../`) | Medium: might access unintended data |
2828| Tool invocations | Instructions directing Claude to use bash, file operations, or other tools | Medium: review what operations are performed |
2929
3030### Review checklist
from line 31
3131
3232Before deploying any Skill from a third party or internal contributor, complete these steps:
3333
341. **Read all Skill directory content.** Review SKILL.md, all referenced markdown files, and any bundled scripts or resources.
341. **Read all Skill directory content.** Review `SKILL.md`, all referenced markdown files, and any bundled scripts or resources.
35352. **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.
396. **Identify tools and commands the Skill instructs Claude to invoke.** List all bash commands, file operations, and tool references. Consider the combined risk when a Skill uses both file-read and network tools together.
396. **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.
41418. **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>
44 Never deploy Skills from untrusted sources without a full audit. A malicious Skill can direct Claude to execute arbitrary code, access sensitive files, or transmit data externally. Treat Skill installation with the same rigor as installing software on production systems.
44 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.
4545</Warning>
4646
4747### Skill content scanning
4848
49Claude Enterprise organizations can turn on automated security scanning for custom Skills in claude.ai and Claude Cowork. After you turn on **Skill and plugin security scanning** at [claude.ai > Organization settings > Skills](https://claude.ai/admin-settings/skills), Skills that members then upload or edit in claude.ai or Cowork are scanned for signs of malicious behavior, such as hidden code execution, sending your data to an outside service, or instructions that tamper with Claude's safeguards. A Skill that fails the scan, or whose scan hasn't finished, is blocked from use. A Skill that passes with a warning stays usable behind a caution notice. If scanning is available to your organization, turn it on. It complements, but doesn't replace, the [review checklist](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/enterprise#review-checklist).
49Claude Enterprise organizations can turn on automated security scanning for custom Skills in claude.ai and Claude Cowork. After you turn on **Skill and plugin security scanning** at [claude.ai > Organization settings > Skills](https://claude.ai/admin-settings/skills), Skills that members then upload or edit in claude.ai or Cowork are scanned for signs of malicious behavior, such as hidden code execution, sending your data to an outside service, or instructions that tamper with Claude's safeguards. A Skill that fails the scan, or whose scan hasn't completed, is blocked from use. A Skill that passes with a warning stays usable behind a caution notice. If scanning is available to your organization, turn it on. It complements, but doesn't replace, the [review checklist](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/enterprise#review-checklist).
5050
5151Scanning 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.
5252
from line 68
6868
6969### Evaluation requirements
7070
71Require Skill authors to submit evaluation suites with 3–5 representative queries per Skill, covering cases where the Skill should trigger, should not trigger, and ambiguous edge cases. Require testing across the models your organization uses (Haiku, Sonnet, Opus), because Skill effectiveness varies by model.
71Require Skill authors to submit evaluation suites with 3–5 representative queries for each Skill, covering cases where the Skill should trigger, cases where it should not trigger, and ambiguous edge cases. Require testing across the models your organization uses (Haiku, Sonnet, Opus), because Skill effectiveness varies by model.
7272
73For detailed guidance on building evaluations, see [evaluation and iteration](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#evaluation-and-iteration) in best practices. For general evaluation methodology, see [develop test cases](https://platform.claude.com/docs/en/test-and-evaluate/develop-tests).
73For detailed guidance on building evaluations, see [evaluation and iteration](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#evaluation-and-iteration) in Skill authoring best practices. For general evaluation methodology, see [Define success criteria and build evaluations](https://platform.claude.com/docs/en/test-and-evaluate/develop-tests).
7474
7575### Using evaluations for lifecycle decisions
7676
from line 85
8585
8686<Steps>
8787 <Step title="Plan">
88 Identify workflows that are repetitive, error-prone, or require specialized knowledge. Map these to organizational roles and determine which are candidates for Skills.
88 Identify workflows that are repetitive or error-prone, or that require specialized knowledge. Map these to organizational roles and determine which are candidates for Skills.
8989 </Step>
9090
9191 <Step title="Create and review">
from line 97
9797 </Step>
9898
9999 <Step title="Deploy">
100 Upload through the Skills API for workspace-wide access. See [Using Skills with the API](https://platform.claude.com/docs/en/build-with-claude/skills-guide) for upload and version management. Document the Skill in your internal registry with purpose, owner, and version.
100 Upload through the Skills API for workspace-wide access. See [Using Agent Skills with the API](https://platform.claude.com/docs/en/build-with-claude/skills-guide) for upload and version management. Document the Skill in your internal registry with purpose, owner, and version.
101101 </Step>
102102
103103 <Step title="Monitor">
from line 113
113113
114114### Recall limits
115115
116As 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 may 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.
116As 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.
117117
118Note that API requests support a maximum of 20 Skills for each request (see [Using 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.
118Note 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.
119119
120120### Start specific, consolidate later
121121
from line 156
156156
157157### Source control
158158
159Store Skill directories in Git for history tracking, code review through pull requests, and rollback capability. Each Skill directory (containing SKILL.md and any bundled files) maps naturally to a Git-tracked folder.
159Store Skill directories in Git for history tracking, code review through pull requests, and rollback capability. Each Skill directory (containing `SKILL.md` and any bundled files) maps naturally to a Git-tracked folder.
160160
161161### API-based distribution
162162
163The Skills API provides workspace-scoped distribution. Skills uploaded through the API are available to all workspace members. See [Using Skills with the API](https://platform.claude.com/docs/en/build-with-claude/skills-guide) for upload, versioning, and management endpoints.
163The Skills API provides workspace-scoped distribution. Skills uploaded through the API are available to all workspace members. See [Using Agent Skills with the API](https://platform.claude.com/docs/en/build-with-claude/skills-guide) for upload, versioning, and management endpoints.
164164
165165### Versioning strategy
166166
from line 180
180180## Next steps
181181
182182<CardGroup cols={2}>
183 <Card title="Agent Skills overview" icon="book-open" href="https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview">
183 <Card title="Agent Skills" icon="book-open" href="https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview">
184184 Architecture and platform details
185185 </Card>
186186
187 <Card title="Best practices" icon="lightbulb" href="https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices">
187 <Card title="Skill authoring best practices" icon="lightbulb" href="https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices">
188188 Authoring guidance for Skill creators
189189 </Card>
190190
191 <Card title="Using Skills with the API" icon="code" href="https://platform.claude.com/docs/en/build-with-claude/skills-guide">
191 <Card title="Using Agent Skills with the API" icon="code" href="https://platform.claude.com/docs/en/build-with-claude/skills-guide">
192192 Upload and manage Skills programmatically
193193 </Card>
194194</CardGroup>
agents-and-tools/agent-skills/overview Changed · +33 / -33 lines
from line 41
4141
4242Skills 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
44This filesystem-based architecture enables **progressive disclosure:** Claude loads information in stages as needed, rather than consuming context upfront.
44This filesystem-based architecture allows **progressive disclosure:** Claude loads information in stages as needed, rather than consuming context upfront.
4545
4646Skills can contain three types of content, each loaded at a different time:
4747
from line 60
6060
6161### Level 2: Instructions (loaded when triggered)
6262
63The main body of SKILL.md contains procedural knowledge: workflows, best practices, and guidance:
63The main body of `SKILL.md` contains procedural knowledge: workflows, best practices, and guidance:
6464
6565````markdown
6666# PDF Processing
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 93
9393 * `scripts/`
9494 * `fill_form.py` (utility script)
9595
96**Instructions:** Additional markdown files (FORMS.md, REFERENCE.md) containing specialized guidance and workflows
96**Instructions:** Additional markdown files (`FORMS.md`, `REFERENCE.md`) containing specialized guidance and workflows
9797
98**Code:** Executable scripts (fill\_form.py, validate.py) that Claude runs using bash, providing deterministic operations without loading their code into context
98**Code:** Executable scripts (`fill_form.py`, `validate.py`) that Claude runs using bash, providing deterministic operations without loading their code into context
9999
100100**Resources:** Reference materials such as database schemas, API documentation, templates, or examples
101101
102102Claude accesses these files only when referenced. The filesystem model means each content type has different strengths: instructions for flexible guidance, code for reliability, resources for factual lookup.
103103
104| Level | When loaded | Token cost | Content |
105| ------------------------- | ----------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------- |
106| **Level 1: Metadata** | Always (at startup) | \~100 tokens per Skill | `name` and `description` from YAML frontmatter |
107| **Level 2: Instructions** | When Skill is triggered | Under 5k tokens | SKILL.md body with instructions and guidance |
108| **Level 3+: Resources** | As needed | None until accessed | Bundled files. Reference files load into context when read. Scripts run through bash, and only their output enters context |
104| Level | When loaded | Token cost | Content |
105| ------------------------- | ----------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------- |
106| **Level 1: Metadata** | Always (at startup) | \~100 tokens per Skill | `name` and `description` from YAML frontmatter |
107| **Level 2: Instructions** | When Skill is triggered | Under 5k tokens | `SKILL.md` body with instructions and guidance |
108| **Level 3+: Resources** | As needed | None until accessed | Bundled files. Reference files load into context when read. Scripts run through bash, and only their output enters context. |
109109
110110Progressive disclosure ensures only relevant content occupies the context window at any given time.
111111
from line 114
114114Skills 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>
117 
117 
118118</Frame>
119119
120120**How Claude accesses Skill content:**
121121
122When a Skill is triggered, Claude uses bash to read SKILL.md from the filesystem, bringing its instructions into the context window. If those instructions reference other files (such as FORMS.md or a database schema), Claude reads those files too using additional bash commands. When instructions mention executable scripts, Claude runs them through bash and receives only the output (the script code itself never enters context).
122When a Skill is triggered, Claude uses bash to read `SKILL.md` from the filesystem, bringing its instructions into the context window. If those instructions reference other files (such as `FORMS.md` or a database schema), Claude reads those files too using additional bash commands. When instructions mention executable scripts, Claude runs them through bash and receives only the output (the script code itself never enters context).
123123
124**What this architecture enables:**
124**What this architecture makes possible:**
125125
126126* **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 on the fly.
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.
128128* **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
from line 133
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.`
1351352. **User request:** "Extract the text from this PDF and summarize it"
1363. **Claude invokes:** `bash: cat pdf-processing/SKILL.md` → Instructions loaded into context
1374. **Claude determines:** Form filling is not needed, so FORMS.md is not read
1385. **Claude executes:** Uses instructions from SKILL.md to complete the task
1363. **Claude calls:** `bash: cat pdf-processing/SKILL.md` → Instructions loaded into context
1374. **Claude determines:** Form filling is not needed, so `FORMS.md` is not read
1385. **Claude executes:** Uses instructions from `SKILL.md` to complete the task
139139
140140<Frame>
141141 
from line 165
165165
166166[Claude Code](https://code.claude.com/docs/en/overview) supports custom Skills. The pre-built document Skills (PowerPoint, Excel, Word, PDF) are not available in Claude Code, though the open-source [Claude API skill](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/claude-api-skill) comes bundled with it. See the full list of [built-in commands and Skills](https://code.claude.com/docs/en/commands) that ship with Claude Code.
167167
168**Custom Skills:** Create Skills as directories with SKILL.md files. Claude discovers and uses them automatically.
168**Custom Skills:** Create Skills as directories with `SKILL.md` files. Claude discovers and uses them automatically.
169169
170170Custom Skills in Claude Code are filesystem-based and don't require API uploads: place them in `~/.claude/skills/` (personal) or `.claude/skills/` (project).
171171
from line 219
219219`description`:
220220
221221* Must be non-empty
222* Maximum 1024 characters
222* Maximum 1,024 characters
223223* Cannot contain XML tags
224224
225225The `description` must include both what the Skill does and when Claude should use it. For complete authoring guidance, see [Skill authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices).
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 invoke tools or execute code in ways that don't match the Skill's stated purpose.
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>
232 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 executing the Skill, malicious Skills could lead to data exfiltration, unauthorized system access, or other security risks.
232 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.
233233</Warning>
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
238* **External sources are risky:** Skills that fetch data from external URLs pose particular risk, as fetched content may contain malicious instructions. Even trustworthy Skills can be compromised if their external dependencies change over time
239* **Tool misuse:** Malicious Skills can invoke tools (file operations, bash commands, code execution) in harmful ways
240* **Data exposure:** Skills with access to sensitive data could be designed to leak information to external systems
241* **Treat like installing software:** Be especially careful when integrating Skills into production systems with access to sensitive data or critical operations
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.
238* **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.
239* **Tool misuse:** Malicious Skills can call tools (file operations, bash commands, code execution) in harmful ways.
240* **Data exposure:** Skills with access to sensitive data could be designed to leak information to external systems.
241* **Treat like installing software:** Be especially careful when integrating Skills into production systems with access to sensitive data or critical operations.
242242
243243For 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
from line 263
263263
264264### Custom Skills examples
265265
266For complete examples of custom Skills, see the [Skills cookbook](https://platform.claude.com/cookbook/skills-notebooks-01-skills-introduction).
266For complete examples of custom Skills, see the [Agent Skills Cookbook](https://platform.claude.com/cookbook/skills-notebooks-01-skills-introduction).
267267
268268## Data retention
269269
from line 281
281281
282282**Custom Skills do not sync across surfaces**. Skills uploaded to one surface are not automatically available on others:
283283
284* Skills uploaded to claude.ai must be separately uploaded to the API
285* Skills uploaded through the API are not available on claude.ai
286* Claude Code Skills are filesystem-based and separate from both claude.ai and API
284* Skills uploaded to claude.ai must be separately uploaded to the API.
285* Skills uploaded through the API are not available on claude.ai.
286* Claude Code Skills are filesystem-based and separate from both claude.ai and the API.
287287
288288Manage and upload Skills separately for each surface where you want to use them.
289289
from line 302
302302The exact runtime environment available to your Skill depends on the product surface where you use it.
303303
304304* **claude.ai:**
305 * **Varying network access:** Depending on user/admin settings, Skills may have full, partial, or no network access. For more details, see the [Create and Edit Files](https://support.claude.com/en/articles/12111783-create-and-edit-files-with-claude#h_6b7e833898) support article.
305 * **Varying network access:** Depending on user/admin settings, Skills might have full, partial, or no network access. For more details, see the [Create and Edit Files](https://support.claude.com/en/articles/12111783-create-and-edit-files-with-claude#h_6b7e833898) support article.
306306
307307* **Claude API:**
308308
agents-and-tools/mcp-connector Changed · +18 / -18 lines
from line 12
1212 Microsoft Foundry: beta
1313---
1414
15Claude's Model Context Protocol (MCP) connector feature enables 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 353
353353| `type` | string | Yes | Must be "mcp\_toolset". |
354354| `mcp_server_name` | string | Yes | Must match a server name defined in the `mcp_servers` array. |
355355| `default_config` | object | No | Default configuration applied to all tools in this set. Individual tool configs in `configs` override these defaults. |
356| `configs` | object | No | Per-tool configuration overrides. Keys are tool names, values are configuration objects. |
356| `configs` | object | No | Per-tool configuration overrides. Keys are tool names; values are configuration objects. |
357357| `cache_control` | object | No | [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) cache breakpoint configuration for this toolset. |
358358
359359With 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).
from line 396
396396
397397Results in:
398398
399* `search_events`: `enabled: false` (from configs), `defer_loading: true` (from default\_config)
400* All other tools: `enabled: true` (system default), `defer_loading: true` (from default\_config)
399* `search_events`: `enabled: false` (from `configs`), `defer_loading: true` (from `default_config`)
400* All other tools: `enabled: true` (system default), `defer_loading: true` (from `default_config`)
401401
402402## Common configuration patterns
403403
from line 479
479479
480480In this example:
481481
482* `search_events` is enabled with `defer_loading: false`
483* `list_events` is enabled with `defer_loading: true` (inherited from default\_config)
484* All other tools are disabled
482* `search_events` is enabled with `defer_loading: false`.
483* `list_events` is enabled with `defer_loading: true` (inherited from `default_config`).
484* All other tools are disabled.
485485
486486## Validation rules
487487
488488The API enforces these validation rules:
489489
490* **Server must exist:** The `mcp_server_name` in an MCPToolset must match a server defined in the `mcp_servers` array
491* **Server must be used:** Every MCP server defined in `mcp_servers` must be referenced by exactly one MCPToolset
492* **Unique toolset per 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 may have dynamic tool availability)
490* **Server must exist:** The `mcp_server_name` in an MCPToolset must match a server defined in the `mcp_servers` array.
491* **Server must be used:** Every MCP server defined in `mcp_servers` must be referenced by exactly one MCPToolset.
492* **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).
494494
495495## Response content types
496496
from line 526
526526
527527## 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 sees 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 1177
11771177}
11781178```
11791179
1180With many tools available, Claude selects based on tool names and descriptions. Clear, specific tool descriptions improve selection accuracy. For large tool sets (dozens of tools across several servers), consider enabling [`defer_loading`](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector#tool-configuration-options) with the [Tool search tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool) so only relevant tools are surfaced per query.
1180With many tools available, Claude selects based on tool names and descriptions. Clear, specific tool descriptions improve selection accuracy. For large tool sets (dozens of tools across several servers), consider enabling [`defer_loading`](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector#tool-configuration-options) with the [Tool search tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool) so only relevant tools are surfaced for each query.
11811181
11821182## Authentication
11831183
from line 1209
12091209
12101210### Using the access token
12111211
1212Once you've obtained an access token using either of the preceding OAuth flows, 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 1976
19761976
19771977### Error handling
19781978
1979The 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 happen with unsupported content types, MIME types, or resource links (resolve resource links with your MCP client before converting).
1979The 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).
19801980
19811981## Batch requests
19821982
from line 1994
19941994
19951995### Key changes
19961996
19971. **New beta header:** Change from `mcp-client-2025-04-04` to `mcp-client-2025-11-20`
19982. **Tool configuration moved:** Tool configuration now lives in the `tools` array as MCPToolset objects, not in the MCP server definition
19993. **More flexible configuration:** New pattern supports allowlisting, denylisting, and per-tool configuration
19971. **New beta header:** Change from `mcp-client-2025-04-04` to `mcp-client-2025-11-20`.
19982. **Tool configuration moved:** Tool configuration now lives in the `tools` array as MCPToolset objects, not in the MCP server definition.
19993. **More flexible configuration:** New pattern supports allowlisting, denylisting, and per-tool configuration.
20002000
20012001### Migration steps
20022002
agents-and-tools/mcp-tunnels/concepts Changed · +13 / -13 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
11This page defines the terms used throughout the [MCP tunnels](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview) documentation. Several components appear under different names in configuration files, container images, and prose; the following tables give one canonical name for each and list the aliases you may encounter.
11This page defines the terms used throughout the [MCP tunnels](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview) documentation. Several components appear under different names in configuration files, container images, and prose; the following tables give one canonical name for each and list the aliases you might encounter.
1212
1313## Components
1414
15| Term | Definition | Also appears as |
16| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
17| **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 |
20| **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 |
21| **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 backend 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 |
23| **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 |
15| Term | Definition | Also appears as |
16| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
17| **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 |
20| **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 |
21| **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 |
23| **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
from line 42
4242
4343The phrase "outbound-only" describes the connection, not the requests carried over it.
4444
45Inner TLS spans Anthropic's backend 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
from line 70
7070
7171## See also
7272
73* [MCP tunnels](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview) for the security model and shared-responsibility table.
74* [MCP tunnels reference](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/reference) for proxy configuration fields, certificate requirements, and the setup component.
73* [MCP tunnels](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview) for the security model and shared-responsibility table
74* [MCP tunnels reference](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/reference) for proxy configuration fields, certificate requirements, and the setup component
7575
agents-and-tools/mcp-tunnels/console Changed · +11 / -11 lines
from line 1
11---
2title: Manage tunnels in the Console
2title: Manage tunnels in the Claude Console
33url: https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console
44description: Create tunnels, register CA certificates, retrieve the tunnel token, and attach tunneled MCP servers to agents from the Claude Console.
55---
from line 29
2929 </Step>
3030
3131 <Step title="Name the tunnel">
32 Click **New tunnel** and enter a name in the **Create tunnel** dialog. The name is required and identifies the tunnel in the list, on the detail page, and in the agent MCP server picker. A domain of the form `abcd1234.tunnel.anthropic.com` is assigned automatically.
32 Click **New tunnel** and enter a name in the **Create tunnel** dialog box. The name is required and identifies the tunnel in the list, on the detail page, and in the agent MCP server picker. A domain of the form `abcd1234.tunnel.anthropic.com` is assigned automatically.
3333 </Step>
3434
3535 <Step title="Optionally set up programmatic access">
from line 38
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
4040 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.
41 2. **A federation rule with the `workspace:manage_tunnels` scope.** Turning on the toggle reveals a **Federation rule** picker. Choose an existing rule with that scope, or click **Create federation rule** to create one inline.
41 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.
4242 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.
from line 65
6565 </Step>
6666</Steps>
6767
68Your organization can have up to 10 active tunnels. Creating a tunnel does not establish any connectivity; that happens once your stack dials in with the tunnel token and a CA certificate is registered.
68Your organization can have up to 10 active tunnels. Creating a tunnel does not establish any connectivity; that occurs once your stack dials in with the tunnel token and a CA certificate is registered.
6969
7070## Get the connection details
7171
from line 90
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 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 119
119119Once your stack is running and has one or more MCP servers configured, attach an upstream MCP server to a Managed Agent session. To call the same servers from the Messages API instead, see [Use the tunneled MCP servers](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview#use-the-tunneled-mcp-servers).
120120
121121<Note>
122 The picker only shows tunnels with at least one active certificate. A tunnel that still shows **Needs certificate** in the **MCP tunnels** list does not appear in the dropdown; register a CA certificate first. The picker is also workspace-scoped: it lists tunnels in the same workspace as the session, not other workspaces.
122 The picker only shows tunnels with at least one active certificate. A tunnel that still shows **Needs certificate** in the **MCP tunnels** list does not appear in the dropdown menu; register a CA certificate first. The picker is also workspace-scoped: it lists tunnels in the same workspace as the session, not other workspaces.
123123</Note>
124124
125125<Steps>
126 <Step title="Open the Create session dialog">
126 <Step title="Open the Create session dialog box">
127127 In the Claude Console, go to the [Sessions](https://platform.claude.com/sessions) page (`platform.claude.com/sessions`) and click **Create session**.
128128 </Step>
129129
130130 <Step title="Define an inline agent">
131 In the agent picker, choose **Create new agent** so you can edit the MCP server list directly.
131 In the agent picker, select **Create new agent** so you can edit the MCP server list directly.
132132 </Step>
133133
134134 <Step title="Add the MCP server">
135 Click **+ MCP Server** and open the dropdown. Tunnels created in the current workspace appear at the top of the list, above the public connector catalog. Select the tunnel that fronts the server you want to reach.
135 Click **+ MCP Server** and open the dropdown menu. Tunnels created in the current workspace appear at the top of the list, above the public connector catalog. Select the tunnel that fronts the server you want to reach.
136136 </Step>
137137
138138 <Step title="Supply the routing">
from line 141
141141</Steps>
142142
143143<Note>
144 The tunnel carries traffic; it does not authenticate to the upstream MCP server. Configure OAuth or bearer auth on the MCP server the same way as for any other MCP server.
144 The tunnel carries traffic; it does not authenticate to the upstream MCP server. Configure OAuth or bearer authentication on the MCP server the same way as for any other MCP server.
145145</Note>
146146
147147## Archive a tunnel
from line 148
148148
149149Archiving immediately stops the tunnel from accepting connections and is permanent.
150150
151In 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`). In the workspace picker in the sidebar, select the workspace that holds the tunnel. Open the row menu for the tunnel and choose **Archive**. Archived tunnels remain visible when you filter the list by **Archived** or **All**.
151In 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`). In the workspace picker in the sidebar, select the workspace that holds the tunnel. Open the row menu for the tunnel and select **Archive**. Archived tunnels remain visible when you filter the list by **Archived** or **All**.
152152
153153## Next steps
154154
agents-and-tools/mcp-tunnels/deploy-compose Changed · +4 / -4 lines
## Before you start ## Before you begin
from line 10
1010
1111This guide deploys the [tunnel stack](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/concepts#components) as hardened containers on a single host. The same configuration can be replicated across multiple hosts for availability.
1212
13## Before you begin
13## Before you start
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 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
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 happens **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>` per 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 282
282282 </Step>
283283
284284 <Step title="Register the CA certificate in the Console">
285 On the tunnel detail page, scroll to the **Certificates** section and click **Add certificate**. Upload `data/ca.crt` directly with **Choose file** (the modal accepts `.pem`, `.crt`, and `.cer`), or paste its contents:
285 On the tunnel detail page, scroll to the **Certificates** section and click **Add certificate**. Upload `data/ca.crt` directly with **Choose file** (the modal window accepts `.pem`, `.crt`, and `.cer`), or paste its contents:
286286
287287 ```bash
288288 cat data/ca.crt
agents-and-tools/mcp-tunnels/deploy-helm Changed · +8 / -8 lines
## Before you start ## Before you begin
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 [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
13## Before you begin
13## 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'll 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
21 * **[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'll need a federation rule scoped to `workspace:manage_tunnels`.
21 * **[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`.
2222 * **[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).
from line 155
155155 search: http://search-mcp.internal:8080
156156 ```
157157
158 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 per [Upstream IP validation](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/troubleshooting#upstream-ip-validation).
158 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>
161161 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.
from line 214
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>` per 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 296
296296 search: http://search-mcp.internal:8080
297297 ```
298298
299 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 per [Upstream IP validation](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/troubleshooting#upstream-ip-validation).
299 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>
302302 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.
agents-and-tools/mcp-tunnels/overview Changed · +9 / -9 lines
from line 109
109109
110110* **Deployment target**
111111
112 * **Helm** when deploying to Kubernetes.
113 * **Docker Compose** for a single host or local testing.
112 * **Helm** when deploying to Kubernetes
113 * **Docker Compose** for a single host or local testing
114114
115115* **Authentication for setup**
116116
117 * **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.
117 * **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
119119
120120## Use the tunneled MCP servers
121121
from line 129
129129
130130### Managed Agents (Console)
131131
1321. On the [Sessions](https://platform.claude.com/sessions) page (`platform.claude.com/sessions`) in the Claude Console, create a session and choose **Create new agent** so you can edit the MCP server list.
1332. Click **+ MCP Server** and open the dropdown. 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.
1321. 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.
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 has access to multiple workspaces, 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 may 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
from line 8
88 MCP tunnels are in research preview. [Request access](https://claude.com/form/mcp-tunnels) to try them.
99</Note>
1010
11This quickstart takes you from zero to Claude calling a private MCP server through a tunnel. 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).
11This quickstart shows you how to set up a tunnel so that Claude can call 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
1313## What you'll build
1414
from line 18
1818
1919* [Docker and Docker Compose](https://docs.docker.com/get-docker/) on a machine with outbound internet access.
2020* A role in the [Claude Console](https://platform.claude.com) that can manage MCP tunnels. See the [Console guide prerequisites](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/console#prerequisites).
21* [OpenSSL](https://openssl-library.org/source/) 1.1.1 or later. Preinstalled on macOS and most Linux distributions; on Windows, install it separately (the `openssl` binary must be on your `PATH`).
21* [OpenSSL](https://openssl-library.org/source/) 1.1.1 or later. Preinstalled on macOS and most Linux distributions. On Windows, install it separately (the `openssl` binary must be on your `PATH`).
2222
2323<Steps>
2424 <Step title="Create a tunnel">
from line 261
261261 </Step>
262262
263263 <Step title="Call it from Claude">
264 In the Console, go to the [Sessions](https://platform.claude.com/sessions) page (`platform.claude.com/sessions`) and create a session. In the agent picker choose **Create new agent**, give the agent a name, and keep the pre-filled model. Click **+ MCP Server**, select your tunnel, set **Subdomain** to `echo` and **Path** to `mcp`. Then ask:
264 In the Console, go to the [Sessions](https://platform.claude.com/sessions) page (`platform.claude.com/sessions`) and create a session. In the agent picker, select **Create new agent**, give the agent a name, and keep the prefilled model. Click **+ MCP Server**, select your tunnel, and set **Subdomain** to `echo` and **Path** to `mcp`. Then ask:
265265
266266 > Use the hello tool to greet tunnel.
267267
agents-and-tools/mcp-tunnels/reference Changed · +3 / -3 lines
from line 21
2121| `tls.cert_file` | Path to the server TLS certificate. | Required |
2222| `tls.key_file` | Path to the server TLS private key. | Required |
2323| `routes` | Map of subdomain or full hostname to upstream URL. See [Route matching](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/reference#route-matching). | Required |
24| `upstream.allowed_ips` | IPv4 CIDR ranges or single addresses the proxy is permitted to connect to. Mutually exclusive with `disable_ip_validation`. | RFC1918 private ranges |
24| `upstream.allowed_ips` | IPv4 CIDR ranges or single addresses the proxy is allowed to connect to. Mutually exclusive with `disable_ip_validation`. | RFC1918 private ranges |
2525| `upstream.disable_ip_validation` | Disable upstream IP validation entirely. Mutually exclusive with `allowed_ips`. | `false` |
2626| `upstream.tls.ca_file` | CA bundle for validating upstream TLS. | None |
2727| `upstream.tls.include_system_cas` | Also trust the system CA bundle for upstream TLS. | `false` |
from line 62
6262
6363Upload with `POST /v1/tunnels/{tunnel_id}/certificates`. A tunnel can hold up to two active CA certificates at a time, which allows zero-downtime rotation.
6464
65* PEM-encoded, single certificate, up to 8 kB.
65* PEM-encoded, single certificate, up to 8 kB.
6666* `BasicConstraints` extension present with `CA:TRUE`, marked critical.
6767* `SubjectKeyIdentifier` extension present.
6868* `KeyUsage` includes `keyCertSign`.
from line 80
8080* Within its validity period.
8181* RSA 2048-bit or larger, or ECDSA P-256 or larger, with a SHA-256 or stronger signature.
8282
83The setup component generates an ECDSA P-256 CA with five-year validity and an RSA 4096-bit server certificate with a wildcard SAN and 90-day validity.
83The setup component generates an ECDSA P-256 CA with 5-year validity and an RSA 4096-bit server certificate with a wildcard SAN and 90-day validity.
8484
8585## Setup component
8686
agents-and-tools/mcp-tunnels/troubleshooting Changed · +4 / -4 lines
from line 20
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`. |
23| `curl https://<proxy>:8080` fails with `wrong version number` | Expected; the listener is plaintext WebSocket. TLS happens inside the WS stream. | Verify through a [Managed Agent or the Messages API](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview#use-the-tunneled-mcp-servers) instead. |
23| `curl https://<proxy>:8080` fails with `wrong version number` | Expected; the listener is plaintext WebSocket. TLS occurs inside the WS stream. | Verify through a [Managed Agent or the Messages API](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview#use-the-tunneled-mcp-servers) instead. |
2424
2525The following sections cover failures that need more than a one-line fix.
2626
2727## OAuth fails behind a source-IP allowlist
2828
29OAuth flows fail when your authorization server's source-IP allowlist blocks Anthropic's backend 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 65
6565 </Step>
6666</Steps>
6767
68With this configuration, the user's browser hits `/authorize` on your existing hostname (which your allowlist already permits), while Anthropic's backend 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 90
9090* The `TUNNEL_TOKEN` is missing, expired, or copied incorrectly.
9191* A firewall is blocking outbound TCP/UDP on port 7844 to the tunnel edge.
9292
93cloudflared may also log warnings about UDP receive buffer sizes; this is a QUIC tuning hint, not an error.
93cloudflared might also log warnings about UDP receive buffer sizes; this is a QUIC tuning hint, not an error.
9494
9595## Certificate errors
9696
agents-and-tools/tool-use/advisor-tool Changed · +14 / -14 lines
from line 4
44description: Pair a faster executor model with a higher-intelligence advisor model that provides strategic guidance mid-generation.
55---
66
7The advisor tool lets a faster, lower-cost **executor model** consult a higher-intelligence **advisor model** mid-generation for strategic guidance. The advisor reads the full conversation, produces a plan or course correction, and the executor continues with the task.
7The advisor tool lets a faster, lower-cost **executor model** consult a higher-intelligence **advisor model** mid-generation for strategic guidance. The advisor reads the full conversation and produces a plan or course correction, and the executor continues with the task.
88
9This pattern fits long-horizon agentic workloads (coding agents, computer use, multistep research pipelines) where most turns are mechanical but having an excellent plan is crucial. You get close to advisor-solo quality while the bulk of token generation happens at executor-model rates. For measured results, including how the benefit shrinks as the executor's own capability approaches the advisor's, see [Optimizing for cost and intelligence](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence).
9This pattern fits long-horizon agentic workloads (coding agents, computer use, multistep research pipelines) where most turns are mechanical but having an excellent plan is crucial. You get close to advisor-solo quality while the bulk of token generation occurs at executor-model rates. For measured results, including how the benefit shrinks as the executor's own capability approaches the advisor's, see [Optimizing for cost and intelligence](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence).
1010
1111```mermaid
1212sequenceDiagram
from line 394
394394}
395395```
396396
397The executor sees the error and continues without further advice. The request itself does not fail.
397The executor receives the error and continues without further advice. The request itself does not fail.
398398
399399| `error_code` | Meaning |
400400| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
from line 1225
12251225
12261226The advisor sub-inference does not stream. The executor's stream pauses while the advisor runs; then the full result arrives in a single event.
12271227
1228The `server_tool_use` block with `name: "advisor"` signals that an advisor call is starting. The pause begins when that block closes (`content_block_stop`). During the pause, the stream is quiet except for standard SSE `ping` keepalives emitted roughly every 30 seconds. Short advisor calls might show no pings.
1228The `server_tool_use` block with `name: "advisor"` signals that an advisor call is starting. The pause starts when that block closes (`content_block_stop`). During the pause, the stream is quiet except for standard SSE `ping` keepalives emitted roughly every 30 seconds. Short advisor calls might show no pings.
12291229
12301230When the advisor finishes, the `advisor_tool_result` arrives fully formed in a single `content_block_start` event (no deltas). Executor output then resumes streaming.
12311231
from line 1378
13781378
13791379The advisor's prompt on the Nth call is the (N-1)th call's prompt with one more segment appended, so the prefix is stable across calls. With `caching` enabled, each advisor call writes a cache entry, and the next call reads up to that point and pays only for the delta. You'll see `cache_read_input_tokens` become non-zero on the second and later `advisor_message` iterations.
13801380
1381**When to enable it:** The cache write costs more than the reads save when the advisor is called two or fewer times per conversation. Caching breaks even at roughly three advisor calls and improves from there. Enable it for long agent loops, and keep it off for short tasks.
1381**When to enable it:** The cache write costs more than the reads save when the advisor is called two or fewer times in each conversation. Caching breaks even at roughly three advisor calls and improves from there. Enable it for long agent loops, and keep it off for short tasks.
13821382
13831383**Keep it consistent:** Set `caching` once and leave it for the whole conversation. Toggling it off and on mid-conversation causes cache misses.
13841384
13851385<Warning>
1386 [`clear_thinking`](https://platform.claude.com/docs/en/build-with-claude/context-editing) with a `keep` value other than `"all"` shifts the advisor's quoted transcript each turn, causing advisor-side cache misses. This is a cost degradation only. Advice quality is unaffected. When thinking is on without explicit `clear_thinking` configuration, the API defaults to `keep: {type: "thinking_turns", value: 1}`, which triggers this behavior (the default on earlier Opus and Sonnet models and on Haiku models through Claude Haiku 4.5; on Claude Opus 4.5 and later Opus models, Claude Sonnet 4.6 and later Sonnet models, and Claude Haiku 5.5, the default is to keep all turns). Set `keep: "all"` to preserve advisor cache stability.
1386 [`clear_thinking`](https://platform.claude.com/docs/en/build-with-claude/context-editing) with a `keep` value other than `"all"` shifts the advisor's quoted transcript each turn, causing advisor-side cache misses. This is a cost degradation only. Advice quality is unaffected. When thinking is on without explicit `clear_thinking` configuration, the API defaults to `keep: {type: "thinking_turns", value: 1}`, which triggers this behavior (the default on earlier Opus and Sonnet models and on Haiku models through Claude Haiku 4.5, whereas on Claude Opus 4.5 and later Opus models, Claude Sonnet 4.6 and later Sonnet models, and Claude Haiku 5.5, the default is to keep all turns). Set `keep: "all"` to preserve advisor cache stability.
13871387</Warning>
13881388
13891389## Combining with other tools
from line 1604
16041604
16051605#### Alternative system prompt for Haiku on coding workloads
16061606
1607Claude Haiku 4.5 applies the default advisor guidance conservatively. That keeps its call rate appropriately low on research and lookup workloads but gives up quality on coding workloads, where an early advisor consult reliably pays for itself. On an internal coding benchmark, a close variant of the following block (the read-only carve-out in the Hard rule was added after measurement) raised Haiku pass rates by roughly 7.5 percentage points over the built-in default.
1607Claude Haiku 4.5 applies the default advisor guidance conservatively. That keeps its call rate appropriately low on research and lookup workloads but gives up quality on coding workloads, where an early advisor consult is reliably worth its cost. On an internal coding benchmark, a close variant of the following block (the read-only carve-out in the Hard rule was added after measurement) raised Haiku pass rates by roughly 7.5 percentage points over the built-in default.
16081608
16091609Use this block in place of the earlier timing and advice blocks when your Haiku executor runs predominantly coding or write-task workloads:
16101610
from line 1647
16471647
16481648#### Trimming advisor output length
16491649
1650Advisor output is the advisor's largest cost driver, and the top-level `max_tokens` does not bound it. The advisor sees both your system prompt and your user messages as quoted context about the executor's task, so instructions that address the advisor directly are followed much more reliably than third-person descriptions. The most effective placement Anthropic tested is a line in the user message:
1650Advisor output is the advisor's largest cost driver, and the top-level `max_tokens` does not bound it. The advisor receives both your system prompt and your user messages as quoted context about the executor's task, so instructions that address the advisor directly are followed much more reliably than third-person descriptions. The most effective placement Anthropic tested is a line in the user message:
16511651
16521652```text wrap
16531653(Advisor: please keep your guidance under 80 words — I need a focused starting point, not a comprehensive plan.)
from line 1663
16631663
16641664### Capping advisor output
16651665
1666Set `max_tokens` on the tool definition to cap the advisor's total output (thinking plus text) per call:
1666Set `max_tokens` on the tool definition to cap the advisor's total output (thinking plus text) for each call:
16671667
16681668<CodeGroup exclude="shell">
16691669 ```python Python
from line 1750
17501750
17511751This is not a hard truncation alone. The server also passes the advisor its remaining-token budget, so the advisor shapes its response to fit.
17521752
1753**Recommended starting point:** `max_tokens: 2048`. In Anthropic's testing on a hard reasoning benchmark (n = 40 per configuration), this reduced mean advisor output by roughly 7x compared with leaving the cap unset, with near-zero truncation and no detectable quality degradation. The minimum value of 1024 reduced output roughly 10x but truncated around 10 percent of calls. Accuracy differences across all configurations were within noise at this sample size. Validate on your own workload.
1753**Recommended starting point:** `max_tokens: 2048`. In Anthropic's testing on a hard reasoning benchmark (n = 40 for each configuration), this reduced mean advisor output by roughly 7x compared with leaving the cap unset, with near-zero truncation and no detectable quality degradation. The minimum value of 1024 reduced output roughly 10x but truncated around 10 percent of calls. Accuracy differences across all configurations were within noise at this sample size. Validate on your own workload.
17541754
17551755| `max_tokens` | Mean advisor output tokens | Calls truncated |
17561756| ------------ | -------------------------- | --------------- |
from line 1760
17601760
17611761Hard reasoning tasks elicit substantially longer advisor output than the [typical 1,400 to 1,800 tokens](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#usage-and-billing) quoted earlier for lighter workloads. Use this table to size the savings ratio, not as a universal baseline for advisor output.
17621762
1763When the advisor does hit the cap, the result block carries `stop_reason: "max_tokens"` on both [result variants](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#result-variants), whichever advisor model you use. Use `stop_reason` to detect truncated advice and decide whether to raise the cap or let the executor proceed with partial guidance. The API also appends `[Advisor output truncated at max_tokens=2048.]` (naming your cap) to the advice text, so the executor sees the truncation in its own context; with a plaintext `advisor_result` advisor that marker is visible to your client as well. Both signals appear only when you set `max_tokens` on the tool definition.
1763When the advisor does hit the cap, the result block carries `stop_reason: "max_tokens"` on both [result variants](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#result-variants), whichever advisor model you use. Use `stop_reason` to detect truncated advice and decide whether to raise the cap or let the executor proceed with partial guidance. The API also appends `[Advisor output truncated at max_tokens=2048.]` (naming your cap) to the advice text, so the executor receives the truncation notice in its own context; with a plaintext `advisor_result` advisor that marker is visible to your client as well. Both signals appear only when you set `max_tokens` on the tool definition.
17641764
17651765```json
17661766{
from line 1826
18261826 </Card>
18271827
18281828 <Card title="Server tools" icon="tool" href="https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools">
1829 Work with Anthropic-executed tools: server\_tool\_use blocks, pause\_turn continuation, and domain filtering.
1829 Work with tools that Anthropic runs: `server_tool_use` blocks, `pause_turn` continuation, and domain filtering.
18301830 </Card>
18311831
18321832 <Card title="Tool reference" icon="book" href="https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference">
from line 1834
18341834 </Card>
18351835
18361836 <Card title="Effort" icon="gauge" href="https://platform.claude.com/docs/en/build-with-claude/effort">
1837 Control how many tokens Claude uses when responding with the effort parameter, trading off between response thoroughness and token efficiency.
1837 Control how many tokens Claude uses when responding with the `effort` parameter, trading off between response thoroughness and token efficiency.
18381838 </Card>
18391839</CardGroup>
18401840
agents-and-tools/tool-use/bash-tool Changed · +14 / -14 lines
from line 17
1717## Use cases
1818
1919* **Development workflows:** Run build commands, tests, and development tools
20* **System automation:** Execute scripts, manage files, automate tasks
20* **System automation:** Run scripts, manage files, automate tasks
2121* **Data processing:** Process files, run analysis scripts, manage datasets
2222* **Environment setup:** Install packages, configure environments
2323
from line 216
216216
217217Claude can also return several `tool_use` blocks in one response. Run them in order in the same session and return all of the results in one `user` message. See [Parallel tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/parallel-tool-use).
218218
219The API is stateless. Nothing about your shell session travels between requests, so your application decides when the session starts, how long it lives, and when to restart it. For the full request and response cycle, see [Handle tool calls](https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls).
219The API is stateless. Nothing about your shell session travels between requests, so your application determines when the session starts, how long it lives, and when to restart it. For the full request and response cycle, see [Handle tool calls](https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls).
220220
221221## Parameters
222222
from line 679
679679 ```
680680 </CodeGroup>
681681
682 The session interleaves stderr with stdout, so error messages land where they happened. The example leaves out what a complete implementation also needs: a timeout that kills the shell and every process it started when a command hangs, then restarts the session. The [Use command timeouts](https://platform.claude.com/docs/en/agents-and-tools/tool-use/bash-tool#follow-implementation-best-practices) best practice shows one way to add it.
682 The session interleaves stderr with stdout, so error messages land where they occurred. The example leaves out what a complete implementation also needs: a timeout that kills the shell and every process it started when a command hangs, then restarts the session. The [Use command timeouts](https://platform.claude.com/docs/en/agents-and-tools/tool-use/bash-tool#follow-implementation-best-practices) best practice shows one way to add it.
683683 </Step>
684684
685685 <Step title="Process Claude's tool calls">
from line 828
828828 </Step>
829829
830830 <Step title="Return the result to Claude">
831 Send the `tool_result` back in a `user` message that continues the same conversation. Claude either requests another command in the same session or finishes its answer:
831 Send the `tool_result` back in a `user` message that continues the same conversation. Claude either requests another command in the same session or completes its answer:
832832
833833 <CodeGroup>
834834 ```bash cURL
from line 1432
14321432
14331433### Handle errors
14341434
1435When a command fails or the session breaks, tell Claude what happened. Return the message as the `tool_result` content and set `is_error` to `true`, which marks the tool call as failed. See [Handling errors with is\_error](https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls#handling-errors-with-is-error).
1435When a command fails or the session breaks, tell Claude what occurred. Return the message as the `tool_result` content and set `is_error` to `true`, which marks the tool call as failed. See [Handling errors with is\_error](https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls#handling-errors-with-is-error).
14361436
14371437<AccordionGroup>
14381438 <Accordion title="Command execution timeout">
1439 If a command takes too long to execute:
1439 If a command takes too long to run:
14401440
14411441 ```json
14421442 {
from line 1494
14941494
14951495<AccordionGroup>
14961496 <Accordion title="Use command timeouts">
1497 A command that never finishes, such as one that waits for input, blocks the session forever because its sentinel line never arrives. Give every command a deadline. When the deadline passes, stop the shell and everything the command started, then restart the session:
1497 A command that never completes, such as one that waits for input, blocks the session forever because its sentinel line never arrives. Give every command a deadline. When the deadline passes, stop the shell and everything the command started, then restart the session:
14981498
14991499 <CodeGroup exclude="shell">
15001500 ```python Python
from line 1803
18031803 </Accordion>
18041804
18051805 <Accordion title="Log all commands">
1806 Keep an audit trail. Route every command through one wrapper that records the command before it runs and the output after it finishes. A command that hangs or breaks the session still leaves a record:
1806 Keep an audit trail. Route every command through one wrapper that records the command before it runs and the output after it completes. A command that hangs or breaks the session still leaves a record:
18071807
18081808 <CodeGroup exclude="shell">
18091809 ```python Python
from line 1929
19291929
19301930* Running tests: `pytest && coverage report`
19311931* Building projects: `npm install && npm run build`
1932* Git operations: `git status && git add . && git commit -m "message"`
1932* Running Git operations: `git status && git add . && git commit -m "message"`
19331933
1934For guidance on using git as a checkpoint-and-recovery mechanism in long-running agent workflows, see [state management best practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#state-management-best-practices).
1934For guidance on using Git as a checkpoint-and-recovery mechanism in long-running agent workflows, see [state management best practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#state-management-best-practices).
19351935
19361936### File operations
19371937
from line 1942
19421942### System tasks
19431943
19441944* Checking resources: `df -h && free -m`
1945* Process management: `ps aux | grep python`
1946* Environment setup: `export PATH=$PATH:/new/path && echo $PATH`
1945* Managing processes: `ps aux | grep python`
1946* Setting up the environment: `export PATH=$PATH:/new/path && echo $PATH`
19471947
19481948## Limitations
19491949
from line 1969
19691969 </Card>
19701970
19711971 <Card title="Tool use with Claude" icon="tool" href="https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview">
1972 Connect Claude to external tools and APIs. See where tools execute, when Claude calls them, and which tool fits your task.
1972 Connect Claude to external tools and APIs. See where tools run, when Claude calls them, and which tool fits your task.
19731973 </Card>
19741974</CardGroup>
19751975