📄 claude/api/prompt-tools-improve

File: prompt-tools-improve.md | Updated: 11/15/2025

Source: https://docs.claude.com/en/api/prompt-tools-improve

Agent Skills are now available! Learn more about extending Claude's capabilities with Agent Skills .

Claude Docs home pagelight logodark logo

US

English

Search...

Ctrl K

Search...

Navigation

Prompt tools

Improve a prompt

Home Developer Guide API Reference Model Context Protocol (MCP) Resources Release Notes

cURL

cURL

Copy

curl -X POST https://api.anthropic.com/v1/experimental/improve_prompt \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "anthropic-beta: prompt-tools-2025-04-02" \
     --header "content-type: application/json" \
     --data \
'{
    "messages": [{"role": "user", "content": [{"type": "text", "text": "Create a recipe for {{food}}"}]}],
    "system": "You are a professional chef",
    "feedback": "Make it more detailed and include cooking times",
    "target_model": "claude-3-7-sonnet-20250219"
}'

200

4XX

Copy

{
  "messages": [\
    {\
      "content": [\
        {\
          "text": "<improved prompt>",\
          "type": "text"\
        }\
      ],\
      "role": "user"\
    },\
    {\
      "content": [\
        {\
          "text": "<assistant prefill>",\
          "type": "text"\
        }\
      ],\
      "role": "assistant"\
    }\
  ],
  "system": "",
  "usage": [\
    {\
      "input_tokens": 490,\
      "output_tokens": 661\
    }\
  ]
}

POST

/

v1

/

experimental

/

improve_prompt

cURL

cURL

Copy

curl -X POST https://api.anthropic.com/v1/experimental/improve_prompt \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "anthropic-beta: prompt-tools-2025-04-02" \
     --header "content-type: application/json" \
     --data \
'{
    "messages": [{"role": "user", "content": [{"type": "text", "text": "Create a recipe for {{food}}"}]}],
    "system": "You are a professional chef",
    "feedback": "Make it more detailed and include cooking times",
    "target_model": "claude-3-7-sonnet-20250219"
}'

200

4XX

Copy

{
  "messages": [\
    {\
      "content": [\
        {\
          "text": "<improved prompt>",\
          "type": "text"\
        }\
      ],\
      "role": "user"\
    },\
    {\
      "content": [\
        {\
          "text": "<assistant prefill>",\
          "type": "text"\
        }\
      ],\
      "role": "assistant"\
    }\
  ],
  "system": "",
  "usage": [\
    {\
      "input_tokens": 490,\
      "output_tokens": 661\
    }\
  ]
}

The prompt tools APIs are in a closed research preview. Request to join the closed research preview .

​

Before you begin

The prompt tools are a set of APIs to generate and improve prompts. Unlike our other APIs, this is an experimental API: you’ll need to request access, and it doesn’t have the same level of commitment to long-term support as other APIs. These APIs are similar to what’s available in the Anthropic Workbench , and are intended for use by other prompt engineering platforms and playgrounds.

​

Getting started with the prompt improver

To use the prompt generation API, you’ll need to:

  1. Have joined the closed research preview for the prompt tools APIs
  2. Use the API directly, rather than the SDK
  3. Add the beta header prompt-tools-2025-04-02

This API is not available in the SDK

​

Improve a prompt

Headers

​

anthropic-beta

string[]

Optional header to specify the beta version(s) you want to use.

To use multiple betas, use a comma separated list like beta1,beta2 or specify the header multiple times for each beta.

​

x-api-key

string

required

Your unique API key for authentication.

This key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the Console . Each key is scoped to a Workspace.

Body

application/json

​

messages

InputMessage · object[]

required

The prompt to improve, structured as a list of message objects.

Each message in the messages array must:

  • Contain only text-only content blocks
  • Not include tool calls, images, or prompt caching blocks

As a simple text prompt:

[  {    "role": "user",     "content": [      {        "type": "text",        "text": "Concise recipe for {{food}}"      }    ]  }]

With example interactions to guide improvement:

[  {    "role": "user",     "content": [      {        "type": "text",        "text": "Concise for {{food}}.\n\nexample\mandu: Put the mandu in the air fryer at 380F for 7 minutes."      }    ]  }]

Note that only contiguous user messages with text content are allowed. Assistant prefill is permitted, but other content types will cause validation errors.

Show child attributes

Examples:

[  {    "content": [      {        "text": "<generated prompt>",        "type": "text"      }    ],    "role": "user"  }]

​

feedback

string | null

Feedback for improving the prompt.

Use this parameter to share specific guidance on what aspects of the prompt should be enhanced or modified.

Example:

{  "messages": [...],  "feedback": "Make the recipes shorter"}

When not set, the API will improve the prompt using general prompt engineering best practices.

Examples:

"Make it more detailed and include cooking times"

​

system

string | null

The existing system prompt to incorporate, if any.

{  "system": "You are a professional meal prep chef",  [...]}

Note that while system prompts typically appear as separate parameters in standard API calls, in the improve_prompt response, the system content will be incorporated directly into the returned user message.

Examples:

"You are a professional chef"

​

target_model

string | null

default:""

The model this prompt will be used for. This optional parameter helps us understand which models our prompt tools are being used with, but it doesn't currently affect functionality.

Example:

"claude-3-7-sonnet-20250219"

Required string length: 1 - 256

Examples:

"claude-3-7-sonnet-20250219"

Response

200

application/json

Successful Response

​

messages

InputMessage · object[]

required

Contains the result of the prompt improvement process in a list of message objects.

Includes a user-role message with the improved prompt text and may optionally include an assistant-role message with a prefill. These messages follow the standard Messages API format and can be used directly in subsequent API calls.

Show child attributes

Examples:

[  {    "content": [      {        "text": "<improved prompt>",        "type": "text"      }    ],    "role": "user"  },  {    "content": [      {        "text": "<assistant prefill>",        "type": "text"      }    ],    "role": "assistant"  }]

​

system

string

required

Currently, the system field is always returned as an empty string (""). In future iterations, this field may contain generated system prompts.

Directions similar to what would normally be included in a system prompt are included in messages when improving a prompt.

Examples:

""

​

usage

object

required

Usage information

Show child attributes

Was this page helpful?

YesNo

Generate a prompt Templatize a prompt

Assistant

Responses are generated using AI and may contain mistakes.