projects: update tools to support pagination, improve prompts

README.md

@@ -830,24 +830,37 @@ Options are:
   - `project_number`: The project's number. (number, required)
 
 - **list_project_fields** - List project fields
+  - `after`: Forward pagination cursor from previous pageInfo.nextCursor. (string, optional)
+  - `before`: Backward pagination cursor from previous pageInfo.prevCursor (rare). (string, optional)
   - `owner`: If owner_type == user it is the handle for the GitHub user account. If owner_type == org it is the name of the organization. The name is not case sensitive. (string, required)
   - `owner_type`: Owner type (string, required)
-  - `per_page`: Number of results per page (max 100, default: 30) (number, optional)
+  - `per_page`: Results per page (max 50) (number, optional)
   - `project_number`: The project's number. (number, required)
 
 - **list_project_items** - List project items
-  - `fields`: Specific list of field IDs to include in the response (e.g. ["102589", "985201", "169875"]). If not provided, only the title field is included. (string[], optional)
+  - `after`: Forward pagination cursor from previous pageInfo.nextCursor. (string, optional)
+  - `before`: Backward pagination cursor from previous pageInfo.prevCursor (rare). (string, optional)
+  - `fields`: 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. (string[], optional)
   - `owner`: If owner_type == user it is the handle for the GitHub user account. If owner_type == org it is the name of the organization. The name is not case sensitive. (string, required)
   - `owner_type`: Owner type (string, required)
-  - `per_page`: Number of results per page (max 100, default: 30) (number, optional)
+  - `per_page`: Results per page (max 50) (number, optional)
   - `project_number`: The project's number. (number, required)
-  - `query`: Search query to filter items (string, optional)
+  - `query`: Query string for advanced filtering of project items. See Projects server instructions (list_project_items query rules) for full construction heuristics, syntax essentials, qualifier glossary, pagination mandate, recovery guidance, and prohibited behaviors. (string, optional)
 
 - **list_projects** - List projects
+  - `after`: Forward pagination cursor from previous pageInfo.nextCursor. (string, optional)
+  - `before`: Backward pagination cursor from previous pageInfo.prevCursor (rare). (string, optional)
   - `owner`: If owner_type == user it is the handle for the GitHub user account. If owner_type == org it is the name of the organization. The name is not case sensitive. (string, required)
   - `owner_type`: Owner type (string, required)
-  - `per_page`: Number of results per page (max 100, default: 30) (number, optional)
-  - `query`: Filter projects by a search query (matches title and description) (string, optional)
+  - `per_page`: Results per page (max 50) (number, optional)
+  - `query`: Filter projects by a search query
+
+Scope: title text + open/closed state.
+PERMITTED qualifiers: is:open, is:closed (state), simple title terms.
+FORBIDDEN: is:issue, is:pr, assignee:, label:, status:, sprint-name:, parent-issue:, team-name:, priority:, etc.
+Examples:
+	- roadmap is:open
+	- is:open feature planning (string, optional)
 
 - **update_project_item** - Update project item
   - `item_id`: The unique identifier of the project item. This is not the issue or pull request ID. (number, required)

pkg/github/__toolsnaps__/list_project_fields.snap

@@ -6,6 +6,14 @@
   "description": "List Project fields for a user or org",
   "inputSchema": {
     "properties": {
+      "after": {
+        "description": "Forward pagination cursor from previous pageInfo.nextCursor.",
+        "type": "string"
+      },
+      "before": {
+        "description": "Backward pagination cursor from previous pageInfo.prevCursor (rare).",
+        "type": "string"
+      },
       "owner": {
         "description": "If owner_type == user it is the handle for the GitHub user account. If owner_type == org it is the name of the organization. The name is not case sensitive.",
         "type": "string"
@@ -19,7 +27,7 @@
         "type": "string"
       },
       "per_page": {
-        "description": "Number of results per page (max 100, default: 30)",
+        "description": "Results per page (max 50)",
         "type": "number"
       },
       "project_number": {

pkg/github/__toolsnaps__/list_project_items.snap

@@ -3,11 +3,19 @@
     "title": "List project items",
     "readOnlyHint": true
   },
-  "description": "List Project items for a user or org",
+  "description": "Search project items with advanced filtering",
   "inputSchema": {
     "properties": {
+      "after": {
+        "description": "Forward pagination cursor from previous pageInfo.nextCursor.",
+        "type": "string"
+      },
+      "before": {
+        "description": "Backward pagination cursor from previous pageInfo.prevCursor (rare).",
+        "type": "string"
+      },
       "fields": {
-        "description": "Specific list of field IDs to include in the response (e.g. [\"102589\", \"985201\", \"169875\"]). If not provided, only the title field is included.",
+        "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.",
         "items": {
           "type": "string"
         },
@@ -26,15 +34,15 @@
         "type": "string"
       },
       "per_page": {
-        "description": "Number of results per page (max 100, default: 30)",
+        "description": "Results per page (max 50)",
         "type": "number"
       },
       "project_number": {
         "description": "The project's number.",
         "type": "number"
       },
       "query": {
-        "description": "Search query to filter items",
+        "description": "Query string for advanced filtering of project items. See Projects server instructions (list_project_items query rules) for full construction heuristics, syntax essentials, qualifier glossary, pagination mandate, recovery guidance, and prohibited behaviors.",
         "type": "string"
       }
     },

pkg/github/__toolsnaps__/list_projects.snap

@@ -3,9 +3,17 @@
     "title": "List projects",
     "readOnlyHint": true
   },
-  "description": "List Projects for a user or org",
+  "description": "List Projects for a user or organization",
   "inputSchema": {
     "properties": {
+      "after": {
+        "description": "Forward pagination cursor from previous pageInfo.nextCursor.",
+        "type": "string"
+      },
+      "before": {
+        "description": "Backward pagination cursor from previous pageInfo.prevCursor (rare).",
+        "type": "string"
+      },
       "owner": {
         "description": "If owner_type == user it is the handle for the GitHub user account. If owner_type == org it is the name of the organization. The name is not case sensitive.",
         "type": "string"
@@ -19,11 +27,11 @@
         "type": "string"
       },
       "per_page": {
-        "description": "Number of results per page (max 100, default: 30)",
+        "description": "Results per page (max 50)",
         "type": "number"
       },
       "query": {
-        "description": "Filter projects by a search query (matches title and description)",
+        "description": "Filter projects by a search query\n\t\t\t\t\nScope: title text + open/closed state.\nPERMITTED qualifiers: is:open, is:closed (state), simple title terms.\nFORBIDDEN: is:issue, is:pr, assignee:, label:, status:, sprint-name:, parent-issue:, team-name:, priority:, etc.\nExamples:\n\t- roadmap is:open\n\t- is:open feature planning",
         "type": "string"
       }
     },

pkg/github/instructions.go

@@ -62,6 +62,104 @@ Check 'list_issue_types' first for organizations to use proper issue types. Use
 		return `## Discussions
 
 Use 'list_discussion_categories' to understand available categories before creating discussions. Filter by category for better organization.`
+	case "projects":
+		return `## Projects
+
+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):
+	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:
+	- 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:
+	- Summaries ONLY if user uses verbs: analyze | summarize | summary | report | overview | insights.
+	- Listing verbs (list/show/get/fetch/display/enumerate) → enumerate + total.
+
+Examples:
+	- list_projects: "roadmap is:open"
+	- list_project_items: state:open is:issue sprint:@current priority:high updated:>@today-7d
+
+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).
+
+list_project_items query rules:
+Query string - For advanced filtering of project items using GitHub's search syntax:
+
+MUST reflect user intent; strongly prefer explicit content type if narrowed:
+	- "open issues" → state:open is:issue
+	- "merged PRs" → state:merged is:pr
+	- "items updated this week" → updated:>@today-7d (omit type only if mixed desired)
+	- "list all P1 priority items" → priority:p1 (omit state if user wants all, omit type if user specifies "items")
+	- "list all open P2 issues" → is:issue state:open priority:p2 (include state if user wants open or closed, include type if user specifies "issues" or "PRs")
+	- "all open issues I'm working on" → is:issue state:open assignee:@me
+
+Query Construction Heuristics:
+	a. Extract type nouns: issues → is:issue | PRs, Pulls, or Pull Requests → is:pr | tasks/tickets → is:issue (ask if ambiguity)
+	b. Map temporal phrases: "this week" → updated:>@today-7d
+	c. Map negations: "excluding wontfix" → -label:wontfix
+	d. Map priority adjectives: "high/sev1/p1" → priority:high OR priority:p1 (choose based on field presence)
+	e. When filtering by label, always use wildcard matching to account for cross-repository differences or emojis: (e.g. "bug 🐛" → label:*bug*)
+	f. When filtering by milestone, always use wildcard matching to account for cross-repository differences: (e.g. "v1.0" → milestone:*v1.0*)
+
+Syntax Essentials (items):
+   AND: space-separated. (label:bug priority:high).
+   OR: comma inside one qualifier (label:bug,critical).
+   NOT: leading '-' (-label:wontfix).
+   Hyphenate multi-word field names. (team-name:"Backend Team", story-points:>5).
+   Quote multi-word values. (status:"In Review" team-name:"Backend Team").
+   Ranges: points:1..3, updated:<@today-30d.
+   Wildcards: title:*crash*, label:bug*.
+	 Assigned to User: assignee:@me | assignee:username | no:assignee
+
+Common Qualifier Glossary (items):
+   is:issue | is:pr | state:open|closed|merged | assignee:@me|username | label:NAME | status:VALUE |
+   priority:p1|high | sprint-name:@current | team-name:"Backend Team" | parent-issue:"org/repo#123" |
+   updated:>@today-7d | title:*text* | -label:wontfix | label:bug,critical | no:assignee | has:label
+
+Pagination Mandate:
+   Do not analyze until ALL pages fetched (loop while pageInfo.hasNextPage=true). Always reuse identical query, fields, per_page.
+
+Never:
+   - Infer field IDs; fetch via list_project_fields.
+   - Drop 'fields' param on subsequent pages if field values are needed.`
 	default:
 		return ""
 	}