feat: handle "suggestions" better

mcp/review.ts

@@ -189,7 +189,10 @@ export const CreatePullRequestReview = type({
     line: type.number.describe("Line number to comment on (end line for multi-line ranges)."),
     side: type.enumerated("LEFT", "RIGHT").describe("LEFT (old code) or RIGHT (new code). Defaults to RIGHT.").optional(),
     body: type.string.describe("Explanatory comment text").optional(),
-    suggestion: type.string.describe("Full replacement code. MUST preserve exact indentation.").optional(),
+    suggestion: type.string.describe(
+      "Optional replacement code shown as a fenced code block below the comment body. " +
+      "Prefer putting the fix directly in 'body' as a markdown code block instead."
+    ).optional(),
     start_line: type.number.describe("Start line for multi-line ranges.").optional(),
   })
     .array()
@@ -204,7 +207,10 @@ export function CreatePullRequestReviewTool(ctx: ToolContext) {
       "Submit a review for an existing pull request. " +
       "Reviews with no body AND no comments are silently skipped. " +
       "IMPORTANT: 95%+ of feedback should be in 'comments' with file paths and line numbers. " +
-      "Only use 'body' for a 1-2 sentence summary. Use 'suggestion' to propose replacement code. " +
+      "Only use 'body' for a 1-2 sentence summary. " +
+      "For every actionable issue, the comment 'body' should explain the problem AND include a markdown " +
+      "code block showing the corrected code. For example: " +
+      "'SQL injection: id is interpolated directly into the query string.\\n\\n```ts\\nconst result = await db.query(\\'SELECT * FROM users WHERE id = $1\\', [id]);\\n```'. " +
       "The first submission may error once with a diff-coverage nudge — retry with the same arguments. " +
       "Inline comments can ONLY target files and lines that appear in the PR diff.",
     parameters: CreatePullRequestReview,