mcp: clarify event payload via raw_body, not request tool

- Update hookdeck_events tool description to state that raw_body returns
  the event payload directly; agents should not use hookdeck_requests
  when they already have an event id.
- Clarify in schema that get returns metadata/headers only; raw_body
  returns the payload.
- Update help text for hookdeck_events to match.

Made-with: Cursor

Author: leggetter

pkg/gateway/mcp/tool_help.go

@@ -143,8 +143,8 @@ Parameters:
 
 Actions:
   list     — List events with optional filters
-  get      — Get a single event by ID
-  raw_body — Get the raw body of an event
+  get      — Get a single event by ID (metadata and headers only; no payload)
+  raw_body — Get the event payload (body) directly by event ID. Use this when you need the payload; no need to call hookdeck_requests.
 
 Parameters:
   action          (string, required) — list, get, or raw_body

pkg/gateway/mcp/tools.go

@@ -114,10 +114,10 @@ func toolDefs(client *hookdeck.Client) []struct {
 		{
 			tool: &mcpsdk.Tool{
 				Name:        "hookdeck_events",
-				Description: "Query events (processed deliveries routed through connections to destinations). List with filters by status, source, destination, or date range. Get event details or inspect the raw payload body.",
+				Description: "Query events (processed deliveries routed through connections to destinations). List with filters by status, source, destination, or date range. Get event details (get) or the event payload (raw_body). Use action raw_body with the event id to get the payload directly — do not use hookdeck_requests for the payload when you already have an event id.",
 				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)"},
+					"action":          {Type: "string", Desc: "Action: list, get, or raw_body. Use raw_body to get the event payload (body); get returns metadata and headers only.", Enum: []string{"list", "get", "raw_body"}},
+					"id":              {Type: "string", Desc: "Event ID (required for get/raw_body). Use with raw_body to fetch the event payload without querying the request."},
 					"connection_id":   {Type: "string", Desc: "Filter by connection (list, maps to webhook_id)"},
 					"source_id":       {Type: "string", Desc: "Filter by source (list)"},
 					"destination_id":  {Type: "string", Desc: "Filter by destination (list)"},