docs(mcp): rewrite tool descriptions for investigation focus and expand README

Update all MCP tool descriptions to accurately reflect read-only
investigation capabilities per MCP best practices:
- Replace generic "Manage" with specific verbs (inspect, query, list)
- Add contextual detail about what each tool returns and when to use it
- Describe the webhook data model (requests → events → attempts)

Expand README MCP section with:
- Available tools table showing all 11 tools
- Claude Desktop configuration alongside Cursor
- Seven example prompts demonstrating investigation workflows

https://claude.ai/code/session_01Y2eJZgKG78nDyN6Uw2tWQx

Author: claude

README.md

@@ -530,9 +530,24 @@ For complete command and flag reference, see [REFERENCE.md](REFERENCE.md).
 
 ### Event Gateway MCP
 
-The CLI includes an [MCP](https://modelcontextprotocol.io/) (Model Context Protocol) server that exposes Hookdeck Event Gateway as tools for AI and agent workflows. You don't run it yourself—you add it to your MCP client (e.g. Cursor, Claude), and the editor starts the server when it needs Hookdeck tools (list/inspect connections, sources, destinations, events, requests, attempts, issues, metrics; login when unauthenticated).
+The CLI includes an [MCP](https://modelcontextprotocol.io/) (Model Context Protocol) server for investigating webhook traffic in production. It exposes read-only tools that let AI agents query your Hookdeck Event Gateway — inspect connections, trace requests through events and delivery attempts, review issues, and pull aggregate metrics.
 
-**Configure your client** (e.g. Cursor: `~/.cursor/mcp.json` or project-level config):
+**Configure your MCP client** (Cursor, Claude Desktop, or any MCP-compatible host):
+
+Cursor (`~/.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "hookdeck": {
+      "command": "hookdeck",
+      "args": ["gateway", "mcp"]
+    }
+  }
+}
+```
+
+Claude Desktop (`claude_desktop_config.json`):
 
 ```json
 {
@@ -545,7 +560,50 @@ The CLI includes an [MCP](https://modelcontextprotocol.io/) (Model Context Proto
 }
 ```
 
-The client runs `hookdeck gateway mcp` (stdio) as the server process. After configuration, the host can use tools such as `hookdeck_connections_list`, `hookdeck_events_list`, and `hookdeck_login`. For the full tool reference, see [REFERENCE.md](REFERENCE.md) or run `hookdeck gateway mcp --help`.
+The client starts `hookdeck gateway mcp` as a stdio subprocess. If you haven't authenticated yet, the `hookdeck_login` tool is available to log in via the browser.
+
+#### Available tools
+
+| Tool | Description |
+|------|-------------|
+| `hookdeck_projects` | List projects or switch the active project for this session |
+| `hookdeck_connections` | Inspect connections and control delivery flow (list, get, pause, unpause) |
+| `hookdeck_sources` | Inspect inbound webhook sources |
+| `hookdeck_destinations` | Inspect webhook delivery destinations |
+| `hookdeck_transformations` | Inspect JavaScript transformations applied to payloads |
+| `hookdeck_requests` | Query inbound requests — list, get details, raw body, linked events |
+| `hookdeck_events` | Query processed events — list, get details, raw payload body |
+| `hookdeck_attempts` | Query delivery attempts — retry history, response codes, errors |
+| `hookdeck_issues` | Inspect aggregated failure signals (delivery failures, transform errors, backpressure) |
+| `hookdeck_metrics` | Query aggregate metrics — counts, failure rates, queue depth over time |
+| `hookdeck_help` | Discover available tools and their actions |
+
+#### Example prompts
+
+Once the MCP server is configured, you can ask your agent questions like:
+
+```
+"Are any of my webhooks failing right now?"
+→ Agent uses hookdeck_issues to list open issues, then hookdeck_events to inspect recent failures.
+
+"Show me the last 10 events for my Stripe source and check if any failed."
+→ Agent uses hookdeck_sources to find the Stripe source, then hookdeck_events filtered by source and status.
+
+"What's the error rate for my API destination over the last 24 hours?"
+→ Agent uses hookdeck_metrics with measures like failed_count and count, grouped by destination.
+
+"Trace request req_abc123 — what events did it produce, and did they all deliver successfully?"
+→ Agent uses hookdeck_requests to get the request, then the events action to list generated events.
+
+"Why is my checkout webhook returning 500s? Show me the latest attempt details."
+→ Agent uses hookdeck_events filtered by status FAILED, then hookdeck_attempts to inspect delivery details.
+
+"Pause the connection between Stripe and my staging endpoint while I debug."
+→ Agent uses hookdeck_connections to find and pause the connection.
+
+"Compare failure rates across all my destinations this week."
+→ Agent uses hookdeck_metrics with dimensions set to destination_id and measures like error_rate.
+```
 
 ### Manage connections
 

pkg/gateway/mcp/tool_help.go

@@ -35,17 +35,17 @@ func helpOverview(client *hookdeck.Client) *mcpsdk.CallToolResult {
 
 Current project: %s
 
-hookdeck_projects     — List or switch projects (actions: list, use)
-hookdeck_connections  — Manage connections/webhook routes (actions: list, get, pause, unpause)
-hookdeck_sources      — Manage inbound webhook sources (actions: list, get)
-hookdeck_destinations — Manage webhook delivery destinations (actions: list, get)
-hookdeck_transformations — Manage JavaScript transformations (actions: list, get)
-hookdeck_requests     — Query inbound webhook requests (actions: list, get, raw_body, events, ignored_events)
-hookdeck_events       — Query events (actions: list, get, raw_body)
-hookdeck_attempts     — Query delivery attempts (actions: list, get)
-hookdeck_issues       — Inspect issues (actions: list, get)
-hookdeck_metrics      — Query metrics (actions: events, requests, attempts, transformations)
-hookdeck_help         — This help text
+hookdeck_projects        — List or switch projects (actions: list, use)
+hookdeck_connections     — Inspect connections and control delivery flow (actions: list, get, pause, unpause)
+hookdeck_sources         — Inspect inbound webhook sources (actions: list, get)
+hookdeck_destinations    — Inspect webhook delivery destinations (actions: list, get)
+hookdeck_transformations — Inspect JavaScript transformations (actions: list, get)
+hookdeck_requests        — Query inbound webhook requests (actions: list, get, raw_body, events, ignored_events)
+hookdeck_events          — Query processed webhook events (actions: list, get, raw_body)
+hookdeck_attempts        — Query delivery attempts (actions: list, get)
+hookdeck_issues          — Inspect aggregated failure signals (actions: list, get)
+hookdeck_metrics         — Query aggregate metrics (actions: events, requests, attempts, transformations)
+hookdeck_help            — This help text
 
 Use hookdeck_help with topic="<tool_name>" for detailed help on a specific tool.`, projectInfo)
 
@@ -63,13 +63,13 @@ Parameters:
   action      (string, required) — "list" or "use"
   project_id  (string)           — Required for "use" action`,
 
-	"hookdeck_connections": `hookdeck_connections — Manage connections (webhook routes)
+	"hookdeck_connections": `hookdeck_connections — Inspect connections and control delivery flow
 
 Actions:
   list    — List connections with optional filters
   get     — Get a single connection by ID
-  pause   — Pause a connection
-  unpause — Unpause a connection
+  pause   — Pause a connection (stops event delivery)
+  unpause — Resume a paused connection
 
 Parameters:
   action         (string, required) — list, get, pause, or unpause
@@ -81,7 +81,7 @@ Parameters:
   limit          (integer)          — Max results (list, default 100)
   next/prev      (string)           — Pagination cursors (list)`,
 
-	"hookdeck_sources": `hookdeck_sources — Manage inbound webhook sources
+	"hookdeck_sources": `hookdeck_sources — Inspect inbound webhook sources
 
 Actions:
   list — List sources with optional filters
@@ -94,7 +94,7 @@ Parameters:
   limit   (integer)          — Max results (list, default 100)
   next/prev (string)         — Pagination cursors (list)`,
 
-	"hookdeck_destinations": `hookdeck_destinations — Manage webhook delivery destinations
+	"hookdeck_destinations": `hookdeck_destinations — Inspect webhook delivery destinations
 
 Actions:
   list — List destinations with optional filters
@@ -107,7 +107,7 @@ Parameters:
   limit   (integer)          — Max results (list, default 100)
   next/prev (string)         — Pagination cursors (list)`,
 
-	"hookdeck_transformations": `hookdeck_transformations — Manage JavaScript transformations
+	"hookdeck_transformations": `hookdeck_transformations — Inspect JavaScript transformations
 
 Actions:
   list — List transformations with optional filters
@@ -178,7 +178,7 @@ Parameters:
   dir       (string)           — "asc" or "desc" (list)
   next/prev (string)           — Pagination cursors (list)`,
 
-	"hookdeck_issues": `hookdeck_issues — Inspect issues
+	"hookdeck_issues": `hookdeck_issues — Inspect aggregated failure signals
 
 Actions:
   list — List issues with optional filters
@@ -195,7 +195,7 @@ Parameters:
   limit            (integer)          — Max results (list, default 100)
   next/prev        (string)           — Pagination cursors (list)`,
 
-	"hookdeck_metrics": `hookdeck_metrics — Query metrics
+	"hookdeck_metrics": `hookdeck_metrics — Query aggregate metrics
 
 Actions:
   events          — Event metrics (auto-routes to queue-depth, pending, or by-issue as needed)
@@ -216,7 +216,7 @@ Parameters:
   status         (string)             — Filter by status
   issue_id       (string)             — Filter by issue (events only)`,
 
-	"hookdeck_help": `hookdeck_help — Describe available tools
+	"hookdeck_help": `hookdeck_help — Get an overview of available tools or detailed help for a specific tool
 
 Parameters:
   topic  (string) — Tool name for detailed help (e.g. "hookdeck_events"). Omit for overview.`,

pkg/gateway/mcp/tools.go

@@ -22,7 +22,7 @@ func toolDefs(client *hookdeck.Client) []struct {
 		{
 			tool: &mcpsdk.Tool{
 				Name:        "hookdeck_projects",
-				Description: "List available Hookdeck projects or switch the active project for this session.",
+				Description: "List available Hookdeck projects or switch the active project for this session. Use this to see which project you're querying and to change project context.",
 				InputSchema: schema(map[string]prop{
 					"action":     {Type: "string", Desc: "Action to perform: list or use", Enum: []string{"list", "use"}},
 					"project_id": {Type: "string", Desc: "Project ID (required for use action)"},
@@ -33,7 +33,7 @@ func toolDefs(client *hookdeck.Client) []struct {
 		{
 			tool: &mcpsdk.Tool{
 				Name:        "hookdeck_connections",
-				Description: "Manage connections (webhook routes) that link sources to destinations.",
+				Description: "Inspect webhook connections (routes linking sources to destinations). List connections with filters, get details by ID, or pause/unpause a connection's delivery pipeline.",
 				InputSchema: schema(map[string]prop{
 					"action":         {Type: "string", Desc: "Action: list, get, pause, or unpause", Enum: []string{"list", "get", "pause", "unpause"}},
 					"id":             {Type: "string", Desc: "Connection ID (required for get/pause/unpause)"},
@@ -51,7 +51,7 @@ func toolDefs(client *hookdeck.Client) []struct {
 		{
 			tool: &mcpsdk.Tool{
 				Name:        "hookdeck_sources",
-				Description: "Manage inbound webhook sources.",
+				Description: "List and inspect inbound webhook sources. Returns source configuration including URL, verification settings, and allowed HTTP methods.",
 				InputSchema: schema(map[string]prop{
 					"action": {Type: "string", Desc: "Action: list or get", Enum: []string{"list", "get"}},
 					"id":     {Type: "string", Desc: "Source ID (required for get)"},
@@ -66,7 +66,7 @@ func toolDefs(client *hookdeck.Client) []struct {
 		{
 			tool: &mcpsdk.Tool{
 				Name:        "hookdeck_destinations",
-				Description: "Manage webhook delivery destinations.",
+				Description: "List and inspect webhook delivery destinations. Returns destination configuration including URL, authentication, and rate limiting settings.",
 				InputSchema: schema(map[string]prop{
 					"action": {Type: "string", Desc: "Action: list or get", Enum: []string{"list", "get"}},
 					"id":     {Type: "string", Desc: "Destination ID (required for get)"},
@@ -81,7 +81,7 @@ func toolDefs(client *hookdeck.Client) []struct {
 		{
 			tool: &mcpsdk.Tool{
 				Name:        "hookdeck_transformations",
-				Description: "Manage JavaScript transformations applied to webhook payloads.",
+				Description: "List and inspect JavaScript transformations applied to webhook payloads. Returns transformation code and configuration for debugging payload processing.",
 				InputSchema: schema(map[string]prop{
 					"action": {Type: "string", Desc: "Action: list or get", Enum: []string{"list", "get"}},
 					"id":     {Type: "string", Desc: "Transformation ID (required for get)"},
@@ -96,7 +96,7 @@ func toolDefs(client *hookdeck.Client) []struct {
 		{
 			tool: &mcpsdk.Tool{
 				Name:        "hookdeck_requests",
-				Description: "Query inbound webhook requests received by Hookdeck.",
+				Description: "Query inbound webhook requests (raw data received by Hookdeck before routing). List with filters, get details, inspect the raw body, or view the events and ignored events generated from a request.",
 				InputSchema: schema(map[string]prop{
 					"action":         {Type: "string", Desc: "Action: list, get, raw_body, events, or ignored_events", Enum: []string{"list", "get", "raw_body", "events", "ignored_events"}},
 					"id":             {Type: "string", Desc: "Request ID (required for get/raw_body/events/ignored_events)"},
@@ -114,7 +114,7 @@ func toolDefs(client *hookdeck.Client) []struct {
 		{
 			tool: &mcpsdk.Tool{
 				Name:        "hookdeck_events",
-				Description: "Query events (processed webhook deliveries).",
+				Description: "Query events (webhook deliveries routed through connections). List with filters by status, source, destination, or date range. Get event details or inspect the raw payload body.",
 				InputSchema: schema(map[string]prop{
 					"action":          {Type: "string", Desc: "Action: list, get, or raw_body", Enum: []string{"list", "get", "raw_body"}},
 					"id":              {Type: "string", Desc: "Event ID (required for get/raw_body)"},
@@ -139,7 +139,7 @@ func toolDefs(client *hookdeck.Client) []struct {
 		{
 			tool: &mcpsdk.Tool{
 				Name:        "hookdeck_attempts",
-				Description: "Query delivery attempts for webhook events.",
+				Description: "Query delivery attempts (each HTTP request made to deliver an event to its destination). Filter by event to see retry history, response status codes, and error details.",
 				InputSchema: schema(map[string]prop{
 					"action":   {Type: "string", Desc: "Action: list or get", Enum: []string{"list", "get"}},
 					"id":       {Type: "string", Desc: "Attempt ID (required for get)"},
@@ -156,7 +156,7 @@ func toolDefs(client *hookdeck.Client) []struct {
 		{
 			tool: &mcpsdk.Tool{
 				Name:        "hookdeck_issues",
-				Description: "List and inspect Hookdeck issues (delivery failures, transformation errors, etc.).",
+				Description: "List and inspect Hookdeck issues — aggregated failure signals such as repeated delivery failures, transformation errors, and backpressure alerts. Use this to identify systemic problems across your webhooks.",
 				InputSchema: schema(map[string]prop{
 					"action":           {Type: "string", Desc: "Action: list or get", Enum: []string{"list", "get"}},
 					"id":               {Type: "string", Desc: "Issue ID (required for get)"},
@@ -175,7 +175,7 @@ func toolDefs(client *hookdeck.Client) []struct {
 		{
 			tool: &mcpsdk.Tool{
 				Name:        "hookdeck_metrics",
-				Description: "Query metrics for events, requests, attempts, and transformations.",
+				Description: "Query aggregate metrics over a time range. Get counts, failure rates, error rates, queue depth, and pending event data for events, requests, attempts, and transformations. Supports grouping by dimensions like source, destination, or connection.",
 				InputSchema: schema(map[string]prop{
 					"action":         {Type: "string", Desc: "Metric type: events, requests, attempts, or transformations", Enum: []string{"events", "requests", "attempts", "transformations"}},
 					"start":          {Type: "string", Desc: "Start datetime (ISO 8601, required)"},
@@ -195,7 +195,7 @@ func toolDefs(client *hookdeck.Client) []struct {
 		{
 			tool: &mcpsdk.Tool{
 				Name:        "hookdeck_help",
-				Description: "Describe available tools and their actions.",
+				Description: "Get an overview of all available Hookdeck tools or detailed help for a specific tool. Use this when unsure which tool to use for a task.",
 				InputSchema: schema(map[string]prop{
 					"topic": {Type: "string", Desc: "Tool name for detailed help (e.g. hookdeck_events). Omit for overview."},
 				}),