Lesson 9 - Step 2 of 5

Prompt Definition

Learn the structure of prompt definitions including name, description, and arguments.

Prompt Structure

Every MCP prompt has a specific structure. Understanding this structure is essential for creating well-defined prompts that clients can discover and use effectively.

The Prompt Object

A prompt definition contains these fields:

json 
{
    "name": "code-review",
    "description": "Review code for potential issues and improvements",
    "arguments": [
        {
            "name": "code",
            "description": "The code to review",
            "required": true
        },
        {
            "name": "language",
            "description": "Programming language (e.g., python, javascript)",
            "required": true
        },
        {
            "name": "focus",
            "description": "What to focus on: security, performance, style, or all",
            "required": false
        }
    ]
}

Field Definitions

Field Type Description
name string Unique identifier for the prompt (required)
description string Human-readable description (optional but recommended)
arguments array List of argument definitions (optional)

Argument Structure

Each argument in the arguments array has this structure:

json 
{
    "name": "language",
    "description": "The programming language of the code",
    "required": true
}
Field Type Description
name string Argument identifier (required)
description string What this argument is for (optional)
required boolean Whether the argument must be provided (optional, defaults to false)

Defining Prompts in Python

Here's how to define a collection of prompts in your MCP server:

python 
"""
prompts.py - MCP Prompt definitions
"""

# Define all available prompts
PROMPTS = {
    "code-review": {
        "name": "code-review",
        "description": "Review code for bugs, style issues, and improvements",
        "arguments": [
            {
                "name": "code",
                "description": "The code to review",
                "required": True
            },
            {
                "name": "language",
                "description": "Programming language (python, javascript, etc.)",
                "required": True
            },
            {
                "name": "focus",
                "description": "Review focus: security, performance, style, or all",
                "required": False
            }
        ]
    },
    "explain-code": {
        "name": "explain-code",
        "description": "Explain what a piece of code does in plain English",
        "arguments": [
            {
                "name": "code",
                "description": "The code to explain",
                "required": True
            },
            {
                "name": "detail_level",
                "description": "Level of detail: brief, normal, or detailed",
                "required": False
            }
        ]
    },
    "summarize": {
        "name": "summarize",
        "description": "Summarize text content concisely",
        "arguments": [
            {
                "name": "text",
                "description": "The text to summarize",
                "required": True
            },
            {
                "name": "max_length",
                "description": "Maximum length in sentences (default: 3)",
                "required": False
            }
        ]
    }
}
Naming Conventions

Use lowercase names with hyphens for prompts (e.g., code-review). This matches the convention used in MCP tools and makes prompts easy to reference in commands.

Prompts Without Arguments

Some prompts don't need arguments. They provide a fixed template for common tasks:

python 
# A prompt with no arguments
PROMPTS["git-commit-help"] = {
    "name": "git-commit-help",
    "description": "Get help writing a good git commit message",
    "arguments": []  # No arguments needed
}

# Or simply omit the arguments field
PROMPTS["brainstorm"] = {
    "name": "brainstorm",
    "description": "Start a creative brainstorming session"
    # arguments field is optional
}

Best Practices for Prompt Design

  • Clear names — Use descriptive, action-oriented names
  • Helpful descriptions — Explain what the prompt does and when to use it
  • Minimal required arguments — Only mark arguments as required if truly necessary
  • Default values — Mention defaults in argument descriptions
  • Consistent naming — Use the same argument names across related prompts
Argument Values Are Always Strings

MCP prompt arguments are passed as strings. If you need numeric values, parse them in your prompt handler. Describe expected formats in the argument description.

What's Next?

Now that you understand how prompts are defined, let's implement the prompts/list method so clients can discover your prompts.