update snapshot and docs

Author: tmelliottjr

README.md

@@ -796,17 +796,54 @@ Options are:
 <summary>Projects</summary>
 
 - **project_read** - Read project information
-  - `after`: Next page cursor (from pageInfo.endCursor) (string, optional)
-  - `before`: Previous page cursor (from pageInfo.startCursor) (string, optional)
+  - `after`: Forward pagination cursor. Use ONLY if the previous response 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. (string, optional)
+  - `before`: Backward pagination cursor (rare): supply to move to the preceding page using pageInfo.prevCursor. Not needed for normal forward iteration. (string, optional)
   - `field_id`: Field ID (required for get_project_field) (number, 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)
   - `item_id`: Item ID (required for get_project_item) (number, optional)
   - `method`: Read operation: get_project, list_projects, get_project_field, list_project_fields (call FIRST for IDs), get_project_item, list_project_items (use query + fields) (string, required)
   - `owner`: GitHub username or org name (case-insensitive) (string, required)
   - `owner_type`: Owner type: 'user' or 'org' (string, required)
-  - `per_page`: Results per page (max 20) (number, optional)
+  - `per_page`: Results per page (max 20). Keep constant across paginated requests; changing mid-sequence can complicate page traversal. (number, optional)
   - `project_number`: Project number (required for most methods) (number, optional)
-  - `query`: Filter string (CRITICAL for list_project_items). Combine filters by SPACE for logical AND (order doesn't matter): e.g. 'state:open is:issue priority:p1 label:bug'. **Content Type:** Use 'is:issue' for issues, 'is:pr' (or 'is:pull-request') for pull requests. **Format Rules:** Qualifiers (left of ':') with spaces use hyphens. Values (right of ':') with spaces use quotes. Examples: 'state:open is:issue sprint-name:"Q1 Planning"', 'is:pr team-name:"Backend Team" status:"In Review"', 'parent-issue:"github/repo#123"'. Filters: is:issue/pr/open/closed/merged, assignee:@me/username, label:name, status:value, priority:p1, updated:>@today-7d, title:*text*, -label:wontfix (negate), label:bug,critical (OR with comma), priority:1..3 (range), no:assignee, has:label, iteration:@current (string, optional)
+  - `query`: Query string to filter project items (highly recommended for list_project_items).
+		CRITICAL: Always include this when calling list_project_items.
+		
+		list_project_items instructions:
+
+		Derive the query from the user's natural language intent BEFORE invoking the tool. Map phrases directly:
+		- "open issues" => state:open is:issue
+		- "merged PRs" => state:merged is:pr
+		- "assigned to me" => assignee:@me is:issue
+		- "high priority bugs" => state:open is:issue label:bug priority:high
+		- "review-ready PRs" => is:pr status:"Ready for Review"
+
+		Content Type:
+		- Issues: is:issue
+		- Pull requests: is:pr (or is:pull-request)
+		Without one you'll get mixed types.
+
+		Logical Combination:
+		- Space-separated qualifiers = AND
+		- Commas inside a single qualifier = OR (label:bug,critical)
+		- Negation with leading dash: -label:wontfix
+
+		Format Rules:
+		- Qualifiers with spaces use hyphens: sprint-name, team-name, parent-issue
+		- Values with spaces use quotes: sprint-name:"Q1 Planning" status:"In Review"
+		- Single word values: no quotes (state:open priority:high)
+
+		Examples:
+		- state:open is:issue sprint-name:"Q1 Planning"
+		- is:pr team-name:"Backend Team" status:"In Review"
+		- parent-issue:"github/repo#123"
+
+		Common Filters:
+		is:issue/pr state:open/closed/merged assignee:@me/username label:name status:value priority:p1 updated:>@today-7d title:*text* -label:wontfix label:bug,critical priority:1..3 no:assignee has:label iteration:@current
+
+		Pagination:
+		When pageInfo.hasNextPage=true, use after=nextCursor to request the next page. Keep query, fields, and per_page identical for every page. Repeat until pageInfo.hasNextPage=false.
+		 (string, optional)
 
 - **project_write** - Modify project items
   - `item_id`: For add: issue/PR ID. For update/delete: project item ID (not issue/PR ID) (number, required)

pkg/github/__toolsnaps__/project_read.snap

@@ -3,15 +3,15 @@
     "title": "Read project information",
     "readOnlyHint": true
   },
-  "description": "Read operations for GitHub Projects V2.\n\nMethods: get_project, list_projects, get_project_field, list_project_fields, get_project_item, list_project_items\n\n**For list_project_items:**\n1. Call list_project_fields FIRST for field IDs\n2. Use 'query' to filter (e.g., 'state:open priority:p1')\n3. Use 'fields' with IDs from step 1\n\nExamples: query='state:open priority:p1', query='state:closed priority:p1 milestone:\"X\" assignee:@me', query='unblocks:*copilot*'",
+  "description": "Read operations for GitHub Projects V2.\n\nMethods: get_project, list_projects, get_project_field, list_project_fields, get_project_item, list_project_items\n\nUSAGE GUIDANCE (CRITICAL):\n1. list_project_fields MUST be called first to discover field IDs before requesting item field values.\n2. ALWAYS provide a well‑scoped 'query' when calling list_project_items. Omitting 'query' returns broad mixed results (issues + PRs) and is inefficient.\n3. Filter by content type explicitly: add 'is:issue' or 'is:pr' as a qualifier in your query.\n4. To retrieve field values for items, pass the discovered IDs via the 'fields' argument on EVERY paginated call; otherwise only titles are returned.\n5. PAGINATION: After every list_* call, inspect pageInfo.hasNextPage. If true, immediately call again with the same method, same query, same fields, and after=pageInfo.nextCursor. Repeat until hasNextPage=false. Do not change per_page mid sequence. Use 'before' only when navigating backwards (rare).\n6. Accumulate all pages before performing analysis or summarization; partial data leads to incorrect results.\n\nExamples of query usage:\n- query='state:open is:issue priority:p1'\n- query='is:pr status:\"In Review\" team-name:\"Backend Team\"'\n- query='is:issue sprint-name:\"Q1 Planning\" assignee:@me'\n- query='unblocks:*copilot* is:issue state:open'\n\nCombine space-separated qualifiers for logical AND; use commas inside a qualifier for OR (e.g., label:bug,critical).",
   "inputSchema": {
     "properties": {
       "after": {
-        "description": "Next page cursor (from pageInfo.endCursor)",
+        "description": "Forward pagination cursor. Use ONLY if the previous response 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.",
         "type": "string"
       },
       "before": {
-        "description": "Previous page cursor (from pageInfo.startCursor)",
+        "description": "Backward pagination cursor (rare): supply to move to the preceding page using pageInfo.prevCursor. Not needed for normal forward iteration.",
         "type": "string"
       },
       "field_id": {
@@ -54,15 +54,15 @@
         "type": "string"
       },
       "per_page": {
-        "description": "Results per page (max 20)",
+        "description": "Results per page (max 20). Keep constant across paginated requests; changing mid-sequence can complicate page traversal.",
         "type": "number"
       },
       "project_number": {
         "description": "Project number (required for most methods)",
         "type": "number"
       },
       "query": {
-        "description": "Filter string (CRITICAL for list_project_items). Combine filters by SPACE for logical AND (order doesn't matter): e.g. 'state:open is:issue priority:p1 label:bug'. **Content Type:** Use 'is:issue' for issues, 'is:pr' (or 'is:pull-request') for pull requests. **Format Rules:** Qualifiers (left of ':') with spaces use hyphens. Values (right of ':') with spaces use quotes. Examples: 'state:open is:issue sprint-name:\"Q1 Planning\"', 'is:pr team-name:\"Backend Team\" status:\"In Review\"', 'parent-issue:\"github/repo#123\"'. Filters: is:issue/pr/open/closed/merged, assignee:@me/username, label:name, status:value, priority:p1, updated:\u003e@today-7d, title:*text*, -label:wontfix (negate), label:bug,critical (OR with comma), priority:1..3 (range), no:assignee, has:label, iteration:@current",
+        "description": "Query string to filter project items (highly recommended for list_project_items).\n\t\tCRITICAL: Always include this when calling list_project_items.\n\t\t\n\t\tlist_project_items instructions:\n\n\t\tDerive the query from the user's natural language intent BEFORE invoking the tool. Map phrases directly:\n\t\t- \"open issues\" =\u003e state:open is:issue\n\t\t- \"merged PRs\" =\u003e state:merged is:pr\n\t\t- \"assigned to me\" =\u003e assignee:@me is:issue\n\t\t- \"high priority bugs\" =\u003e state:open is:issue label:bug priority:high\n\t\t- \"review-ready PRs\" =\u003e is:pr status:\"Ready for Review\"\n\n\t\tContent Type:\n\t\t- Issues: is:issue\n\t\t- Pull requests: is:pr (or is:pull-request)\n\t\tWithout one you'll get mixed types.\n\n\t\tLogical Combination:\n\t\t- Space-separated qualifiers = AND\n\t\t- Commas inside a single qualifier = OR (label:bug,critical)\n\t\t- Negation with leading dash: -label:wontfix\n\n\t\tFormat Rules:\n\t\t- Qualifiers with spaces use hyphens: sprint-name, team-name, parent-issue\n\t\t- Values with spaces use quotes: sprint-name:\"Q1 Planning\" status:\"In Review\"\n\t\t- Single word values: no quotes (state:open priority:high)\n\n\t\tExamples:\n\t\t- state:open is:issue sprint-name:\"Q1 Planning\"\n\t\t- is:pr team-name:\"Backend Team\" status:\"In Review\"\n\t\t- parent-issue:\"github/repo#123\"\n\n\t\tCommon Filters:\n\t\tis:issue/pr state:open/closed/merged assignee:@me/username label:name status:value priority:p1 updated:\u003e@today-7d title:*text* -label:wontfix label:bug,critical priority:1..3 no:assignee has:label iteration:@current\n\n\t\tPagination:\n\t\tWhen pageInfo.hasNextPage=true, use after=nextCursor to request the next page. Keep query, fields, and per_page identical for every page. Repeat until pageInfo.hasNextPage=false.\n\t\t",
         "type": "string"
       }
     },