> ## Documentation Index
> Fetch the complete documentation index at: https://mcp-use.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://mcp-use.com/docs/feedback

```json
{
  "path": "/python/server/prompts",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Prompts

> Define and expose prompts from your MCP server

Prompts are reusable message templates that help AI agents interact with your server effectively. They provide structured ways to guide conversations and standardize common interactions.

## Example

```python theme={null}
@server.prompt(
    name="code_review",
    title="Code Review",
    description="Generate a code review prompt for a given language and focus area",
)
def code_review_prompt(language: str, focus: str = "general") -> str:
    """Generate a code review prompt."""
    focus_instructions = {
        "general": "for overall quality, readability, and best practices.",
        "security": "focusing on security vulnerabilities and potential exploits.",
        "performance": "focusing on performance optimizations and efficiency.",
    }
    instruction = focus_instructions.get(focus, focus_instructions["general"])
    return f"Please review the following {language} code {instruction}"
```

## Anatomy of a Prompt

When a client calls `prompts/list`, the server returns metadata for each prompt including its arguments. Here's the JSON-RPC response that the example above produces when a client calls `prompts/list`:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "prompts": [
      {
        "name": "code_review",
        "title": "Code Review",
        "description": "Generate a code review prompt for a given language and focus area",
        "arguments": [
          {
            "name": "language",
            "required": true
          },
          {
            "name": "focus",
            "required": false
          }
        ]
      }
    ]
  }
}
```

Here's what maps to what:

| Python                                    | MCP Schema                               | Notes                                    |
| ----------------------------------------- | ---------------------------------------- | ---------------------------------------- |
| `name="code_review"`                      | `"name"`                                 | Falls back to function name if omitted   |
| `title="Code Review"`                     | `"title"`                                | Human-readable display name              |
| `description="Generate a code review..."` | `"description"`                          | Falls back to docstring if omitted       |
| `language: str` (no default)              | `{"name": "language", "required": true}` | Parameters without defaults are required |
| `focus: str = "general"`                  | `{"name": "focus", "required": false}`   | Parameters with defaults are optional    |
| `context: Context`                        | *(not in schema)*                        | Automatically excluded                   |

### Argument Descriptions

You can add descriptions to prompt arguments the same way as tools, using `Annotated` and `Field`:

```python theme={null}
from typing import Annotated
from pydantic import Field

@server.prompt(name="code_review")
def code_review_prompt(
    language: Annotated[str, Field(description="The programming language of the code")],
    focus: Annotated[str, Field(description="Review focus area", default="general")],
) -> str:
    """Generate a code review prompt."""
    return f"Please review the following {language} code for {focus}."
```

This adds `description` to each argument in the response:

```json theme={null}
{
  "arguments": [
    {
      "name": "language",
      "description": "The programming language of the code",
      "required": true
    },
    {
      "name": "focus",
      "description": "Review focus area",
      "required": false
    }
  ]
}
```

## Minimal Definition

At minimum, a prompt only needs a function:

```python theme={null}
@server.prompt()
def greeting() -> str:
    """A friendly greeting prompt."""
    return "Hello! How can I help you today?"
```

The function name becomes the prompt name, and the docstring becomes the description.

## Using Context

Access the MCP context for advanced features. Add a `Context` parameter — it's automatically excluded from the prompt's arguments:

```python theme={null}
from mcp_use.server import Context

@server.prompt(name="contextual")
async def contextual_prompt(context: Context) -> str:
    """A prompt that uses context information."""
    return "Based on the current context, please..."
```

## Multi-Message Prompts

Return structured messages for complex prompts:

```python theme={null}
from mcp.types import PromptMessage, TextContent

@server.prompt(name="interview")
def interview_prompt(role: str) -> list[PromptMessage]:
    """Generate an interview prompt sequence."""
    return [
        PromptMessage(
            role="user",
            content=TextContent(
                type="text",
                text=f"I'm interviewing for a {role} position.",
            ),
        ),
        PromptMessage(
            role="assistant",
            content=TextContent(
                type="text",
                text=f"I'll help you prepare for your {role} interview. Let's start with common questions.",
            ),
        ),
    ]
```

## Async Prompts

Prompts can be async for dynamic content generation:

```python theme={null}
@server.prompt(name="daily_brief")
async def daily_brief() -> str:
    """Generate a daily briefing prompt."""
    from datetime import datetime
    today = datetime.now().strftime("%A, %B %d")
    return f"Good morning! Today is {today}. What would you like to accomplish?"
```

## Prompts vs Tools vs Resources

| Aspect     | Prompts                          | Tools            | Resources            |
| ---------- | -------------------------------- | ---------------- | -------------------- |
| Purpose    | Guide interactions               | Perform actions  | Expose data          |
| Returns    | Message templates                | Action results   | Content/data         |
| Use case   | Conversation starters, templates | Operations       | Files, configs       |
| Invocation | User selects prompt              | Agent calls tool | Agent reads resource |