update argument prompts

Author: tmelliottjr

pkg/github/projects.go

@@ -34,12 +34,21 @@ func ProjectRead(getClient GetClientFn, t translations.TranslationHelperFunc) (t
 
 Methods: get_project, list_projects, get_project_field, list_project_fields, get_project_item, list_project_items
 
-**For list_project_items:**
-1. Call list_project_fields FIRST for field IDs
-2. Use 'query' to filter (e.g., 'state:open priority:p1')
-3. Use 'fields' with IDs from step 1
-
-Examples: query='state:open priority:p1', query='state:closed priority:p1 milestone:"X" assignee:@me', query='unblocks:*copilot*'`)),
+USAGE GUIDANCE (CRITICAL):
+1. list_project_fields MUST be called first to discover field IDs before requesting item field values.
+2. ALWAYS provide a well‑scoped 'query' when calling list_project_items. Omitting 'query' returns broad mixed results (issues + PRs) and is inefficient.
+3. Filter by content type explicitly: add 'is:issue' or 'is:pr' as a qualifier in your query.
+4. To retrieve field values for items, pass the discovered IDs via the 'fields' argument on EVERY paginated call; otherwise only titles are returned.
+5. 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).
+6. Accumulate all pages before performing analysis or summarization; partial data leads to incorrect results.
+
+Examples of query usage:
+- query='state:open is:issue priority:p1'
+- query='is:pr status:"In Review" team-name:"Backend Team"'
+- query='is:issue sprint-name:"Q1 Planning" assignee:@me'
+- query='unblocks:*copilot* is:issue state:open'
+
+Combine space-separated qualifiers for logical AND; use commas inside a qualifier for OR (e.g., label:bug,critical).`)),
 			mcp.WithToolAnnotation(mcp.ToolAnnotation{
 				Title:        t("TOOL_PROJECT_READ_USER_TITLE", "Read project information"),
 				ReadOnlyHint: ToBoolPtr(true),
@@ -68,21 +77,53 @@ Examples: query='state:open priority:p1', query='state:closed priority:p1 milest
 				mcp.Description("Item ID (required for get_project_item)"),
 			),
 			mcp.WithString("query",
-				mcp.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:>@today-7d, title:*text*, -label:wontfix (negate), label:bug,critical (OR with comma), priority:1..3 (range), no:assignee, has:label, iteration:@current"),
+				mcp.Description(`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.
+		`),
 			),
 			mcp.WithNumber("per_page",
-				mcp.Description(fmt.Sprintf("Results per page (max %d)", MaxProjectsPerPage)),
+				mcp.Description(fmt.Sprintf("Results per page (max %d). Keep constant across paginated requests; changing mid-sequence can complicate page traversal.", MaxProjectsPerPage)),
 			),
 			mcp.WithString("after",
-				mcp.Description("Next page cursor (from pageInfo.endCursor)"),
+				mcp.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."),
 			),
 			mcp.WithString("before",
-				mcp.Description("Previous page cursor (from pageInfo.startCursor)"),
+				mcp.Description("Backward pagination cursor (rare): supply to move to the preceding page using pageInfo.prevCursor. Not needed for normal forward iteration."),
 			),
 			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."),