write model-facing prompts for first contact

Tool descriptions, field descriptions, and the server instructions now
assume a model that has never seen Gerrit. The instructions carry a
domain primer (change, patch set, labels, submit) plus the typical
tool flow; every change field shows the three identifier forms with
examples; descriptions cross-reference where inputs come from
(list_change_files paths feed get_file_diff and post_comments, comment
ids come from get_change_comments) and disambiguate change messages
from inline comments. post_comments states that publication is
immediate and that line numbers address the new version of the file.

jsonschema struct tags cannot wrap, so lll excludes them: field
description clarity outranks line length.

Author: xobotyi

.golangci.yaml

@@ -259,6 +259,11 @@ linters:
         linters:
           - funlen
           - goconst
+      # Struct tags cannot wrap; jsonschema tags carry model-facing field
+      # descriptions whose clarity outranks line length.
+      - source: 'jsonschema:"'
+        linters:
+          - lll
     paths:
       - .*\.gen\.go$ # ignore generated files
 

cmd/go-gerrit-mcp/main.go

@@ -20,8 +20,17 @@ import (
 
 const serverName = "go-gerrit-mcp"
 
-const instructions = "Gerrit code review over MCP. Tools are gated by capability groups " +
-	"(read, comment, transition) configured by the operator; only enabled tools are listed."
+const instructions = "Gerrit code review over MCP. A Gerrit change is one commit under review, addressed " +
+	"by change number (123), project~number (myproject~123), or the Change-Id footer of its commit message " +
+	"(I8473b95934b5732ac55d26311a706c9c2bde9940). A change evolves through numbered patch sets; the newest " +
+	"is called the current revision. Reviewers discuss code in inline comment threads and vote on labels " +
+	"such as Code-Review; a change whose submit requirements are satisfied can be submitted, which merges " +
+	"it. Typical flow: search_changes finds changes; get_change shows one change's status, votes, and " +
+	"message timeline; list_change_files and get_file_diff read the code; get_change_comments reads the " +
+	"inline discussion; post_comments, set_vote, and transition_change act on the review. Only the tools " +
+	"the operator enabled are listed, and writes may be restricted to changes owned by this account or to " +
+	"an allowlist of projects — refusals and errors name what to correct, and often carry did_you_mean " +
+	"proposals or hints worth following. All tool output is XML-like text addressed to you."
 
 // version is stamped by the release pipeline via ldflags.
 var version = "dev"

internal/tools/get-change-comments.go

@@ -24,7 +24,7 @@ const (
 var errInvalidStatus = e.New("invalid status filter, expected all, resolved, or unresolved")
 
 type getChangeCommentsInput struct {
-	Change string `json:"change" jsonschema:"Change identifier: numeric ID, project~number, or Change-Id"`
+	Change string `json:"change" jsonschema:"Change identifier: change number (123), project~number (myproject~123), or Change-Id (I8473b95...)"`
 	Status string `json:"status,omitempty" jsonschema:"Thread filter: all, resolved, or unresolved; default all"`
 }
 
@@ -34,9 +34,11 @@ func getChangeComments(c *gerritclient.Client) Tool {
 		Register: func(s *mcp.Server) {
 			mcp.AddTool(s, &mcp.Tool{
 				Name: NameGetChangeComments,
-				Description: "List the published review comments of a Gerrit change, grouped by file " +
-					"and reconstructed into threads with their resolved state. Comment ids are the " +
-					"reply anchors for posting follow-ups.",
+				Description: "List a Gerrit change's inline review comments — the code discussion " +
+					"anchored to files and lines, distinct from the change messages get_change " +
+					"shows — grouped by file and reconstructed into threads with their resolved " +
+					"state. Comment ids are the reply anchors for post_comments; filter " +
+					"status=unresolved to see what still needs action.",
 			}, func(ctx context.Context, _ *mcp.CallToolRequest, in getChangeCommentsInput,
 			) (*mcp.CallToolResult, any, error) {
 				if in.Status == "" {

internal/tools/get-change.go

@@ -14,7 +14,7 @@ import (
 )
 
 type getChangeInput struct {
-	Change string `json:"change" jsonschema:"Change identifier: numeric ID, project~number, or Change-Id"`
+	Change string `json:"change" jsonschema:"Change identifier: change number (123), project~number (myproject~123), or Change-Id (I8473b95...)"`
 }
 
 func getChange(c *gerritclient.Client) Tool {
@@ -23,8 +23,11 @@ func getChange(c *gerritclient.Client) Tool {
 		Register: func(s *mcp.Server) {
 			mcp.AddTool(s, &mcp.Tool{
 				Name: NameGetChange,
-				Description: "Fetch a Gerrit change: status, owner, labels with votes, reviewers, " +
-					"change messages, and the current revision.",
+				Description: "Fetch one Gerrit change's review state: status, owner, submittability, " +
+					"labels with votes, reviewers, and the change-message timeline. Change messages " +
+					"are patch-set and reviewer announcements, not the inline code discussion — " +
+					"read that with get_change_comments. Also reports the current revision SHA, " +
+					"usable as the revision argument of other tools.",
 			}, func(ctx context.Context, _ *mcp.CallToolRequest, in getChangeInput) (*mcp.CallToolResult, any, error) {
 				info, err := c.GetChange(ctx, in.Change)
 				if err != nil {

internal/tools/get-file-diff.go

@@ -17,9 +17,9 @@ import (
 var errFileNotInRevision = e.New("file is not part of the revision")
 
 type getFileDiffInput struct {
-	Change   string `json:"change" jsonschema:"Change identifier: numeric ID, project~number, or Change-Id"`
-	File     string `json:"file" jsonschema:"File path within the change; /COMMIT_MSG addresses the commit message"`
-	Revision string `json:"revision,omitempty" jsonschema:"Patch set number or SHA, defaults to current"`
+	Change   string `json:"change" jsonschema:"Change identifier: change number (123), project~number (myproject~123), or Change-Id (I8473b95...)"`
+	File     string `json:"file" jsonschema:"File path exactly as list_change_files reports it; /COMMIT_MSG for the commit message"`
+	Revision string `json:"revision,omitempty" jsonschema:"Patch set number (1, 2, ...) or revision SHA; omit for the newest patch set"`
 }
 
 func getFileDiff(c *gerritclient.Client) Tool {
@@ -29,7 +29,9 @@ func getFileDiff(c *gerritclient.Client) Tool {
 			mcp.AddTool(s, &mcp.Tool{
 				Name: NameGetFileDiff,
 				Description: "Fetch the diff of one file in a Gerrit change revision. Lines are " +
-					"prefixed unified-diff style: space for context, - for deleted, + for added.",
+					"prefixed unified-diff style: space for context, - for deleted, + for added; " +
+					"a skip marker stands in for long unchanged stretches. Take file paths from " +
+					"list_change_files; /COMMIT_MSG diffs the commit message.",
 			}, func(ctx context.Context, _ *mcp.CallToolRequest, in getFileDiffInput) (*mcp.CallToolResult, any, error) {
 				diff, err := c.GetDiff(ctx, in.Change, in.Revision, in.File)
 				if err != nil {

internal/tools/list-change-files.go

@@ -13,8 +13,8 @@ import (
 )
 
 type listChangeFilesInput struct {
-	Change   string `json:"change" jsonschema:"Change identifier: numeric ID, project~number, or Change-Id"`
-	Revision string `json:"revision,omitempty" jsonschema:"Patch set number or SHA, defaults to current"`
+	Change   string `json:"change" jsonschema:"Change identifier: change number (123), project~number (myproject~123), or Change-Id (I8473b95...)"`
+	Revision string `json:"revision,omitempty" jsonschema:"Patch set number (1, 2, ...) or revision SHA; omit for the newest patch set"`
 }
 
 func listChangeFiles(c *gerritclient.Client) Tool {
@@ -23,8 +23,11 @@ func listChangeFiles(c *gerritclient.Client) Tool {
 		Register: func(s *mcp.Server) {
 			mcp.AddTool(s, &mcp.Tool{
 				Name: NameListChangeFiles,
-				Description: "List the files of a Gerrit change revision with per-file change status " +
-					"and inserted/deleted line counts.",
+				Description: "List the files a Gerrit change revision touches, with per-file status " +
+					"(A added, M modified, D deleted, R renamed with old_path), inserted/deleted " +
+					"line counts, and a binary flag. The paths returned here are the valid file " +
+					"arguments for get_file_diff and post_comments; /COMMIT_MSG is the commit " +
+					"message rendered as a file.",
 			}, func(ctx context.Context, _ *mcp.CallToolRequest, in listChangeFilesInput) (*mcp.CallToolResult, any, error) {
 				files, err := c.ListFiles(ctx, in.Change, in.Revision)
 				if err != nil {

internal/tools/post-comments.go

@@ -28,20 +28,20 @@ var (
 )
 
 type inlineComment struct {
-	File      string `json:"file" jsonschema:"File path; /COMMIT_MSG or /PATCHSET_LEVEL for non-file comments"`
+	File      string `json:"file" jsonschema:"File path as list_change_files reports it; /COMMIT_MSG or /PATCHSET_LEVEL for non-file comments"`
 	Message   string `json:"message" jsonschema:"Comment text"`
-	Line      int    `json:"line,omitempty" jsonschema:"1-based line, omit for a file-level comment"`
-	StartLine int    `json:"start_line,omitempty" jsonschema:"Multi-line comment start, used with end_line"`
-	EndLine   int    `json:"end_line,omitempty" jsonschema:"Multi-line comment end, inclusive"`
+	Line      int    `json:"line,omitempty" jsonschema:"1-based line in the new version of the file; omit for a file-level comment"`
+	StartLine int    `json:"start_line,omitempty" jsonschema:"First line of a multi-line comment (new version of the file), used with end_line"`
+	EndLine   int    `json:"end_line,omitempty" jsonschema:"Last line of a multi-line comment, inclusive"`
 	ReplyTo   string `json:"reply_to,omitempty" jsonschema:"Comment id to reply to, from get_change_comments"`
-	Resolved  *bool  `json:"resolved,omitempty" jsonschema:"Thread resolution intent; replies inherit when omitted"`
+	Resolved  *bool  `json:"resolved,omitempty" jsonschema:"true resolves the thread, false reopens it; replies inherit the thread state when omitted"`
 }
 
 type postCommentsInput struct {
-	Change   string          `json:"change" jsonschema:"Change identifier: numeric ID, project~number, or Change-Id"`
-	Message  string          `json:"message,omitempty" jsonschema:"Top-level review message"`
-	Comments []inlineComment `json:"comments,omitempty" jsonschema:"Inline and file comments to publish"`
-	Notify   string          `json:"notify,omitempty" jsonschema:"NONE, OWNER, OWNER_REVIEWERS, or ALL; default ALL"`
+	Change   string          `json:"change" jsonschema:"Change identifier: change number (123), project~number (myproject~123), or Change-Id (I8473b95...)"`
+	Message  string          `json:"message,omitempty" jsonschema:"Top-level review message, shown on the change rather than on a file"`
+	Comments []inlineComment `json:"comments,omitempty" jsonschema:"Inline, range, file-level, and reply comments to publish"`
+	Notify   string          `json:"notify,omitempty" jsonschema:"Who is notified by email: NONE, OWNER, OWNER_REVIEWERS, or ALL; default ALL"`
 }
 
 func postComments(c *gerritclient.Client) Tool {
@@ -50,12 +50,14 @@ func postComments(c *gerritclient.Client) Tool {
 		Register: func(s *mcp.Server) {
 			mcp.AddTool(s, &mcp.Tool{
 				Name: NamePostComments,
-				Description: "Post a review to a Gerrit change in one call: optional top-level message " +
-					"plus inline, range, file-level, and reply comments. New comments must name a file " +
-					"of the current revision (or /COMMIT_MSG, /PATCHSET_LEVEL); replies anchor to " +
-					"comment ids from get_change_comments, and setting resolved on a reply toggles the " +
-					"thread state. Refused on changes not owned by the authenticated account unless " +
-					"the operator disabled the own-changes restriction.",
+				Description: "Post a review to a Gerrit change in one call, published immediately and " +
+					"visible to everyone on the change: optional top-level message plus inline " +
+					"(file and line), range, file-level, and reply comments. New comments must " +
+					"name a file exactly as list_change_files reports it (or /COMMIT_MSG, " +
+					"/PATCHSET_LEVEL); replies anchor to comment ids from get_change_comments, and " +
+					"setting resolved on a reply toggles the thread state. Refused on changes not " +
+					"owned by the authenticated account unless the operator disabled the " +
+					"own-changes restriction.",
 			}, func(ctx context.Context, _ *mcp.CallToolRequest, in postCommentsInput,
 			) (*mcp.CallToolResult, any, error) {
 				input, err := buildReviewInput(ctx, c, in)

internal/tools/search-changes.go

@@ -19,9 +19,9 @@ var (
 )
 
 type searchChangesInput struct {
-	Query string `json:"query" jsonschema:"Gerrit change query string"`
+	Query string `json:"query" jsonschema:"Gerrit change query, e.g. status:open owner:self; operators are listed in the tool description"`
 	Limit int    `json:"limit,omitempty" jsonschema:"Maximum results per page, default 25"`
-	Start int    `json:"start,omitempty" jsonschema:"Number of results to skip, for pagination"`
+	Start int    `json:"start,omitempty" jsonschema:"Results to skip; advance by limit while a page reports more=true"`
 }
 
 func searchChanges(c *gerritclient.Client) Tool {
@@ -34,8 +34,9 @@ func searchChanges(c *gerritclient.Client) Tool {
 					"Common operators: status:open|merged|abandoned, owner:USERNAME or owner:self, " +
 					"project:NAME, branch:NAME, topic:NAME, label:Code-Review=+2, message:TEXT, " +
 					"file:PATH, age:2d, is:wip. Terms combine with AND; use OR for alternatives and " +
-					"- for negation; quote multi-word values. Paginate via limit/start and the " +
-					"more attribute of the result.",
+					"- for negation; quote multi-word values. Each result is a one-line change " +
+					"summary; pass its number to get_change for the full review state. Paginate " +
+					"via limit/start; more=\"true\" on the result signals further pages.",
 			}, func(ctx context.Context, _ *mcp.CallToolRequest, in searchChangesInput) (*mcp.CallToolResult, any, error) {
 				if in.Limit <= 0 {
 					in.Limit = defaultSearchLimit

internal/tools/set-vote.go

@@ -17,7 +17,7 @@ import (
 var errVoteNoLabel = e.New("vote label must not be empty")
 
 type setVoteInput struct {
-	Change  string `json:"change" jsonschema:"Change identifier: numeric ID, project~number, or Change-Id"`
+	Change  string `json:"change" jsonschema:"Change identifier: change number (123), project~number (myproject~123), or Change-Id (I8473b95...)"`
 	Label   string `json:"label" jsonschema:"Label name, e.g. Code-Review or Verified"`
 	Value   int    `json:"value" jsonschema:"Numeric vote within the label's range; 0 clears an own vote"`
 	Message string `json:"message,omitempty" jsonschema:"Optional message accompanying the vote"`
@@ -29,10 +29,13 @@ func setVote(c *gerritclient.Client) Tool {
 		Register: func(s *mcp.Server) {
 			mcp.AddTool(s, &mcp.Tool{
 				Name: NameSetVote,
-				Description: "Set a vote on a Gerrit change: label name plus numeric value, with an " +
-					"optional message. Value 0 clears an own vote. Gerrit validates the label and " +
-					"range; its refusal is reported verbatim. Refused on changes not owned by the " +
-					"authenticated account unless the operator disabled the own-changes restriction.",
+				Description: "Set this account's vote on one label of a Gerrit change, e.g. " +
+					"Code-Review 2 or Verified 1; each label's range is configured per project, " +
+					"commonly -2..+2 for Code-Review. Value 0 clears the account's own vote. An " +
+					"unknown label or out-of-range value is refused by Gerrit verbatim and the " +
+					"error lists the change's configured labels. Refused on changes not owned by " +
+					"the authenticated account unless the operator disabled the own-changes " +
+					"restriction.",
 			}, func(ctx context.Context, _ *mcp.CallToolRequest, in setVoteInput,
 			) (*mcp.CallToolResult, any, error) {
 				label := strings.TrimSpace(in.Label)

internal/tools/transition-change.go

@@ -17,7 +17,7 @@ var (
 )
 
 type transitionChangeInput struct {
-	Change  string `json:"change" jsonschema:"Change identifier: numeric ID, project~number, or Change-Id"`
+	Change  string `json:"change" jsonschema:"Change identifier: change number (123), project~number (myproject~123), or Change-Id (I8473b95...)"`
 	Action  string `json:"action" jsonschema:"One of: submit, abandon, restore, wip, ready"`
 	Message string `json:"message,omitempty" jsonschema:"Optional message; not accepted for submit"`
 }