Using Prompts Effectively

+15 Mana ✨
MCP Prompts Best Practices(DOCUMENTATION)MCP Server Development(DOCUMENTATION)

Introduction

Knowing how prompts work is one thing — knowing when and how to use them effectively is another. This lesson explores the design decisions behind exposing functionality as a prompt versus a tool, practical patterns for prompt-driven workflows, and best practices for creating prompts that deliver consistent results.

Key Concepts

The key question when designing an MCP server is: should this be a prompt or a tool?

  • Use a prompt when the user initiates a structured workflow and the LLM needs guidance on how to approach a task (code review, data analysis, report generation).
  • Use a tool when the LLM needs to perform an action during its reasoning (fetch data, run a query, call an API).

Prompts are workflow starters — they set the stage for the LLM's work. Tools are capabilities — they extend what the LLM can do.

Real World Context

A database server might expose both prompts and tools. The analyze_table prompt starts a workflow: "Here is the schema for table X, analyze its indexing strategy and suggest improvements." The run_query tool lets the LLM execute SQL during that analysis. The prompt frames the task; the tool executes specific actions within it.

Deep Dive

Prompts as workflow starters are particularly powerful for recurring tasks:

  • Code review: A prompt that includes the file content, coding standards, and a structured review format
  • Data analysis: A prompt that provides a dataset schema and asks for statistical insights
  • Incident investigation: A prompt that includes error logs and asks for root cause analysis

Here is a workflow-starter prompt for code review:

json
{
  "name": "code_review",
  "description": "Structured code review following team standards",
  "arguments": [
    {
      "name": "file_path",
      "description": "Path to the file to review",
      "required": true
    },
    {
      "name": "focus",
      "description": "Review focus: security, performance, or style",
      "required": false
    }
  ]
}

The optional focus argument lets the user tailor the review without writing custom instructions.

Dynamic prompts adapt their output based on arguments and server state. A daily_report prompt might query the server's database to include today's metrics in the generated messages. The prompt template is static, but the content it produces is fresh.

Here is how a dynamic prompt response might look:

json
{
  "description": "Daily metrics report",
  "messages": [
    {
      "role": "user",
      "content": {
        "type": "text",
        "text": "Analyze today's metrics and highlight anomalies:\n\nActive users: 12,847 (up 15%)\nError rate: 2.3% (up 0.8%)\nP95 latency: 450ms (up 120ms)\n\nProvide a summary and recommended actions."
      }
    }
  ]
}

The data is injected by the server at retrieval time, making the prompt dynamic.

Best practices for prompt design include:

  1. Be specific about output format: Include examples of expected output in the prompt messages
  2. Use few-shot examples: Multi-turn messages with examples dramatically improve consistency
  3. Keep prompts focused: One prompt per task. A "do everything" prompt leads to mediocre results
  4. Make arguments intuitive: Use clear names and provide descriptions. Mark truly required arguments; give sensible defaults to optional ones
  5. Version your prompts: As your team's practices evolve, update prompt templates to reflect current standards

Common Pitfalls

  • Exposing too many prompts: A long list overwhelms users. Curate your prompts to the most valuable workflows.
  • Using prompts where tools are better: If the LLM needs to decide autonomously, it should be a tool. Prompts require user selection.
  • Static prompts that go stale: If a prompt references team standards or data formats, keep it updated as those change.

Best Practices

  • Design prompts around user workflows, not server capabilities. Ask "what does the user want to accomplish?" not "what can the server do?"
  • Combine prompts with tools: a prompt starts the workflow, tools execute actions within it.
  • Test prompts with different argument values to ensure they produce good results across the range of inputs.
  • Document each prompt's purpose and expected outcomes in its description field.

Summary

Prompts are most effective as workflow starters for recurring tasks like code review, data analysis, and reporting. They differ from tools in that users select them deliberately rather than the LLM invoking them autonomously. Dynamic prompts inject real-time data into templates, and well-designed arguments make prompts flexible without sacrificing consistency. Combining prompts with tools creates powerful, user-driven workflows.

Code Examples

json
{
  "name": "code_review",
  "description": "Structured code review following team standards",
  "arguments": [
    {
      "name": "file_path",
      "description": "Path to the file to review",
      "required": true
    },
    {
      "name": "focus",
      "description": "Review focus: security, performance, or style",
      "required": false
    }
  ]
}
✓ Completed