← Back to Blog
tutorialdocumentationbest-practices

Writing Great MCP Tool Documentation

How to write README files that make your MCP tool discoverable, usable, and trusted on mcpm.

·3 min read·xapable

Writing Great MCP Tool Documentation

Your README is your tool's storefront on mcpm. This guide covers writing docs that get installs.

Why Documentation Matters

On mcpm, users decide to install in seconds. They scan your README and decide:

  • What does this do? (first 5 seconds)
  • Is it easy to set up? (next 10 seconds)
  • Can I trust it? (final 5 seconds)

If they can't answer these in 20 seconds, they move on.

The Perfect README Structure

1. Title and One-Liner (5 seconds)

<span class="hljs-section"># Weather MCP</span>

Get real-time weather data and 5-day forecasts for any city worldwide.

This becomes your mcpm description. Make every word count.

2. Quick Install (5 seconds)

<span class="hljs-section">## Install</span>

\<span class="hljs-code">`\`</span>\`bash
mcpm-dev add weather-mcp
\<span class="hljs-code">`\`</span>\`

One command. Copy-pasteable. No friction.

3. Setup (10 seconds)

<span class="hljs-section">## Setup</span>

<span class="hljs-bullet">1.</span> Get a free API key at https://openweathermap.org/api
<span class="hljs-bullet">2.</span> Add to your MCP client config:

\<span class="hljs-code">`\`</span>\`json
{
  &quot;mcpServers&quot;: {
<span class="hljs-code">    &quot;weather-mcp&quot;: {
      &quot;command&quot;: &quot;npx&quot;,
      &quot;args&quot;: [&quot;-y&quot;, &quot;weather-mcp&quot;],
      &quot;env&quot;: {
        &quot;OPENWEATHER_API_KEY&quot;: &quot;your-key-here&quot;
      }
    }
  }
}
\`\`\`</span>

Show the exact config for Claude Desktop, Cursor, and Windsurf.

4. Available Tools

Document every tool with:

<span class="hljs-section">## Tools</span>

<span class="hljs-section">### get<span class="hljs-emphasis">_current_</span>weather</span>

Get current weather conditions for any city.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| city | string | Yes | City name |
| units | string | No | celsius (default) or fahrenheit |

<span class="hljs-strong">**Example:**</span>

\<span class="hljs-code">`\`</span>\`
<span class="hljs-quote">&gt; What&#x27;s the weather in Tokyo?</span>
→ 22°C, partly cloudy, humidity 65%
\<span class="hljs-code">`\`</span>\`

<span class="hljs-section">### get<span class="hljs-emphasis">_forecast

Get 5-day weather forecast.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| city | string | Yes | City name |
| days | number | No | 1-5 (default: 3) |</span></span>

5. Examples (Real Usage)

<span class="hljs-section">## Examples</span>

<span class="hljs-section">### With Claude Desktop</span>

<span class="hljs-quote">&gt; &quot;Should I bring an umbrella to work tomorrow?&quot;</span>
<span class="hljs-quote">&gt; Claude calls get<span class="hljs-emphasis">_forecast({ city: &quot;San Francisco&quot;, days: 1 })
&gt; → &quot;Rain expected. Yes, bring an umbrella. ☔&quot;

### With Cursor

&gt; &quot;What&#x27;s the weather where our main customer is?&quot;
&gt; Cursor calls get_</span>current<span class="hljs-emphasis">_weather({ city: &quot;New York&quot; })
&gt; → Used in the AI chat to inform a deployment decision</span></span>

6. Troubleshooting

<span class="hljs-section">## Troubleshooting</span>

| Problem | Solution |
|---------|----------|
| &quot;API key invalid&quot; | Verify key at openweathermap.org |
| &quot;City not found&quot; | Try &quot;London,UK&quot; format |
| Tool not connecting | Check client MCP logs |

7. Links

<span class="hljs-section">## Links</span>

<span class="hljs-bullet">-</span> [<span class="hljs-string">mcpm page</span>](<span class="hljs-link">https://www.mcpm.dev/packages/weather-mcp</span>)
<span class="hljs-bullet">-</span> [<span class="hljs-string">GitHub repository</span>](<span class="hljs-link">https://github.com/you/weather-mcp</span>)
<span class="hljs-bullet">-</span> [<span class="hljs-string">Report an issue</span>](<span class="hljs-link">https://github.com/you/weather-mcp/issues</span>)
<span class="hljs-bullet">-</span> [<span class="hljs-string">OpenWeatherMap API docs</span>](<span class="hljs-link">https://openweathermap.org/api</span>)

Documentation Checklist

Before publishing:

  • One-sentence description in first paragraph
  • Copy-paste install command
  • Client config examples for Claude/Cursor/Windsurf
  • Every tool documented with parameters table
  • Real usage examples showing agent interactions
  • Troubleshooting section for common issues
  • Links to mcpm, GitHub, and external docs
  • Environment variables clearly listed
  • Version badge or changelog link

Pro Tips

  • Use emoji sparingly — they add personality but don't overdo it
  • Write for AI agents too — agents read tool descriptions to decide which tool to call
  • Keep examples real — copy-paste from actual agent conversations
  • Update on every publish — mcpm reads your README fresh each time

Great docs = more installs = more users = better tools. Invest the time.

#MCP #Tutorial #Documentation #mcpm #BestPractices

← Back to all posts