update pagination rules

Author: tmelliottjr

pkg/github/__toolsnaps__/list_project_fields.snap

@@ -7,11 +7,11 @@
   "inputSchema": {
     "properties": {
       "after": {
-        "description": "Forward pagination cursor. Use when the previous response's pageInfo.hasNextPage=true. Supply pageInfo.nextCursor as 'after' and immediately request the next page. LOOP UNTIL pageInfo.hasNextPage=false (don't stop early). Keep per_page identical for every page.",
+        "description": "Forward pagination cursor from previous pageInfo.nextCursor.",
         "type": "string"
       },
       "before": {
-        "description": "Backward pagination cursor (rare): supply to move to the preceding page using pageInfo.prevCursor. Not needed for normal forward iteration.",
+        "description": "Backward pagination cursor from previous pageInfo.prevCursor (rare).",
         "type": "string"
       },
       "owner": {
@@ -27,7 +27,7 @@
         "type": "string"
       },
       "per_page": {
-        "description": "Results per page (max 50). Keep constant across paginated requests; changing mid-sequence can complicate page traversal.",
+        "description": "Results per page (max 50)",
         "type": "number"
       },
       "project_number": {

pkg/github/__toolsnaps__/list_project_items.snap

@@ -7,11 +7,11 @@
   "inputSchema": {
     "properties": {
       "after": {
-        "description": "Forward pagination cursor. Use when the previous response's pageInfo.hasNextPage=true. Supply pageInfo.nextCursor as 'after' and immediately request the next page. LOOP UNTIL pageInfo.hasNextPage=false (don't stop early). Keep query, fields, and per_page identical for every page.",
+        "description": "Forward pagination cursor from previous pageInfo.nextCursor.",
         "type": "string"
       },
       "before": {
-        "description": "Backward pagination cursor (rare): supply to move to the preceding page using pageInfo.prevCursor. Not needed for normal forward iteration.",
+        "description": "Backward pagination cursor from previous pageInfo.prevCursor (rare).",
         "type": "string"
       },
       "fields": {
@@ -34,7 +34,7 @@
         "type": "string"
       },
       "per_page": {
-        "description": "Results per page (max 50). Keep constant across paginated requests; changing mid-sequence can complicate page traversal.",
+        "description": "Results per page (max 50)",
         "type": "number"
       },
       "project_number": {

pkg/github/__toolsnaps__/list_projects.snap

@@ -7,11 +7,11 @@
   "inputSchema": {
     "properties": {
       "after": {
-        "description": "Forward pagination cursor. Use when the previous response's pageInfo.hasNextPage=true. Supply pageInfo.nextCursor as 'after' and immediately request the next page. LOOP UNTIL pageInfo.hasNextPage=false (don't stop early). Keep query and per_page identical for every page.",
+        "description": "Forward pagination cursor from previous pageInfo.nextCursor.",
         "type": "string"
       },
       "before": {
-        "description": "Backward pagination cursor (rare): supply to move to the preceding page using pageInfo.prevCursor. Not needed for normal forward iteration.",
+        "description": "Backward pagination cursor from previous pageInfo.prevCursor (rare).",
         "type": "string"
       },
       "owner": {
@@ -27,7 +27,7 @@
         "type": "string"
       },
       "per_page": {
-        "description": "Results per page (max 50). Keep constant across paginated requests; changing mid-sequence can complicate page traversal.",
+        "description": "Results per page (max 50)",
         "type": "number"
       },
       "query": {

pkg/github/instructions.go

@@ -65,42 +65,60 @@ Use 'list_discussion_categories' to understand available categories before creat
 	case "projects":
 		return `## Projects
 
-When using 'list_project_items', follow these guidelines:
-
-	Field usage:
+Read Tools:
+	- list_projects
+	- get_project
+	- list_project_fields
+	- get_project_field
+	- list_project_items
+	- get_project_item
+Write Tools:
+	- add_project_item
+	- update_project_item
+	- delete_project_item
+
+Field usage:
 	- Call list_project_fields first to understand available fields and get IDs/types before filtering.
 	- Use EXACT returned field names (case-insensitive match). Don't invent names or IDs.
 	- Iteration synonyms (sprint/cycle/iteration) only if that field exists; map to the actual name (e.g. sprint:@current).
 	- Only include filters for fields that exist and are relevant.
 
-	Pagination (mandatory):
-	- Loop while pageInfo.hasNextPage=true using after=nextCursor. Keep query, fields, per_page IDENTICAL each page.
-
-	Fields parameter:
+Pagination (mandatory):
+	Forward (normal) flow:
+	- Loop while pageInfo.hasNextPage=true using after=pageInfo.nextCursor.
+	- Keep query, fields, per_page IDENTICAL on every page.
+	Backward (rare) flow:
+	- Use before=pageInfo.prevCursor only when explicitly navigating to a previous page.
+	Parameters:
+	- per_page: results per page (max 50). Choose a stable value; do not change mid-sequence.
+	- after: forward cursor from prior response (pageInfo.nextCursor).
+	- before: backward cursor from prior response (pageInfo.prevCursor); seldom needed.
+
+Fields parameter:
 	- Include field IDs on EVERY paginated list_project_items call if you need values. Omit → title only.
 
-	Counting rules:
+Counting rules:
 	- Count items array length after full pagination.
 	- If multi-page: collect all pages, dedupe by item.id (fallback node_id) before totals.
 	- Never count field objects, content, or nested arrays as separate items.
 	- item.id = project item ID (for updates/deletes). item.content.id = underlying issue/PR ID.
 
-	Summary vs list:
+Summary vs list:
 	- Summaries ONLY if user uses verbs: analyze | summarize | summary | report | overview | insights.
-	- Listing verbs (list/show/get/fetch/display/enumerate) → just enumerate + total.
+	- Listing verbs (list/show/get/fetch/display/enumerate) → enumerate + total.
 
-	Examples:
+Examples:
 	- list_projects: "roadmap is:open"
 	- list_project_items: state:open is:issue sprint:@current priority:high updated:>@today-7d
 
-	Self-check before returning:
+Self-check before returning:
 	- Paginated fully
 	- Dedupe by id/node_id
 	- Correct IDs used
 	- Field names valid
 	- Summary only if requested.
 
-	Return COMPLETE data or state what's missing (e.g. pages skipped).`
+Return COMPLETE data or state what's missing (e.g. pages skipped).`
 	default:
 		return ""
 	}

pkg/github/projects.go

@@ -51,13 +51,13 @@ Examples:
 	- is:open feature planning`),
 			),
 			mcp.WithNumber("per_page",
-				mcp.Description(fmt.Sprintf("Results per page (max %d). Keep constant across paginated requests; changing mid-sequence can complicate page traversal.", MaxProjectsPerPage)),
+				mcp.Description(fmt.Sprintf("Results per page (max %d)", MaxProjectsPerPage)),
 			),
 			mcp.WithString("after",
-				mcp.Description("Forward pagination cursor. Use when the previous response's pageInfo.hasNextPage=true. Supply pageInfo.nextCursor as 'after' and immediately request the next page. LOOP UNTIL pageInfo.hasNextPage=false (don't stop early). Keep query and per_page identical for every page."),
+				mcp.Description("Forward pagination cursor from previous pageInfo.nextCursor."),
 			),
 			mcp.WithString("before",
-				mcp.Description("Backward pagination cursor (rare): supply to move to the preceding page using pageInfo.prevCursor. Not needed for normal forward iteration."),
+				mcp.Description("Backward pagination cursor from previous pageInfo.prevCursor (rare)."),
 			),
 		), func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
 			owner, err := RequiredParam[string](req, "owner")
@@ -228,13 +228,13 @@ func ListProjectFields(getClient GetClientFn, t translations.TranslationHelperFu
 				mcp.Description("The project's number."),
 			),
 			mcp.WithNumber("per_page",
-				mcp.Description(fmt.Sprintf("Results per page (max %d). Keep constant across paginated requests; changing mid-sequence can complicate page traversal.", MaxProjectsPerPage)),
+				mcp.Description(fmt.Sprintf("Results per page (max %d)", MaxProjectsPerPage)),
 			),
 			mcp.WithString("after",
-				mcp.Description("Forward pagination cursor. Use when the previous response's pageInfo.hasNextPage=true. Supply pageInfo.nextCursor as 'after' and immediately request the next page. LOOP UNTIL pageInfo.hasNextPage=false (don't stop early). Keep per_page identical for every page."),
+				mcp.Description("Forward pagination cursor from previous pageInfo.nextCursor."),
 			),
 			mcp.WithString("before",
-				mcp.Description("Backward pagination cursor (rare): supply to move to the preceding page using pageInfo.prevCursor. Not needed for normal forward iteration."),
+				mcp.Description("Backward pagination cursor from previous pageInfo.prevCursor (rare)."),
 			),
 		), func(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
 			owner, err := RequiredParam[string](req, "owner")
@@ -452,13 +452,13 @@ Never:
    - Drop 'fields' param on subsequent pages if field values are needed.`),
 			),
 			mcp.WithNumber("per_page",
-				mcp.Description(fmt.Sprintf("Results per page (max %d). Keep constant across paginated requests; changing mid-sequence can complicate page traversal.", MaxProjectsPerPage)),
+				mcp.Description(fmt.Sprintf("Results per page (max %d)", MaxProjectsPerPage)),
 			),
 			mcp.WithString("after",
-				mcp.Description("Forward pagination cursor. Use when the previous response's pageInfo.hasNextPage=true. Supply pageInfo.nextCursor as 'after' and immediately request the next page. LOOP UNTIL pageInfo.hasNextPage=false (don't stop early). Keep query, fields, and per_page identical for every page."),
+				mcp.Description("Forward pagination cursor from previous pageInfo.nextCursor."),
 			),
 			mcp.WithString("before",
-				mcp.Description("Backward pagination cursor (rare): supply to move to the preceding page using pageInfo.prevCursor. Not needed for normal forward iteration."),
+				mcp.Description("Backward pagination cursor from previous pageInfo.prevCursor (rare)."),
 			),
 			mcp.WithArray("fields",
 				mcp.Description("Field IDs to include (e.g. [\"102589\", \"985201\"]). CRITICAL: Always provide to get field values. Without this, only titles returned. Get IDs from list_project_fields first."),