reduce description size/redundancy

Author: tmelliottjr

README.md

@@ -845,22 +845,15 @@ Options are:
   - `owner_type`: Owner type (string, required)
   - `per_page`: Results per page (max 50) (number, optional)
   - `project_number`: The project's number. (number, required)
-  - `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)
+  - `query`: Query string for advanced filtering of project items using GitHub's project filtering syntax. (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`: 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)
+  - `query`: Filter projects by title text and open/closed state; permitted qualifiers: is:open, is:closed; 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_items.snap

@@ -42,7 +42,7 @@
         "type": "number"
       },
       "query": {
-        "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.",
+        "description": "Query string for advanced filtering of project items using GitHub's project filtering syntax.",
         "type": "string"
       }
     },

pkg/github/__toolsnaps__/list_projects.snap

@@ -31,7 +31,7 @@
         "type": "number"
       },
       "query": {
-        "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",
+        "description": "Filter projects by title text and open/closed state; permitted qualifiers: is:open, is:closed; examples: \"roadmap is:open\", \"is:open feature planning\".",
         "type": "string"
       }
     },

pkg/github/instructions.go

@@ -65,37 +65,19 @@ Use 'list_discussion_categories' to understand available categories before creat
 	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
+Workflow: 1) list_project_fields (get field IDs), 2) list_project_items (with pagination), 3) optional updates.
 
 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).
+	- Iteration synonyms (sprint/cycle) 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.
+	- Do not analyze until ALL pages fetched.
 
 Counting rules:
 	- Count items array length after full pagination.
@@ -107,10 +89,6 @@ 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
@@ -121,7 +99,7 @@ Self-check before returning:
 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:
+Query string - For advanced filtering of project items using GitHub's project filtering syntax:
 
 MUST reflect user intent; strongly prefer explicit content type if narrowed:
 	- "open issues" → state:open is:issue
@@ -154,9 +132,6 @@ Common Qualifier Glossary (items):
    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.`

pkg/github/projects.go

@@ -41,14 +41,7 @@ func ListProjects(getClient GetClientFn, t translations.TranslationHelperFunc) (
 				mcp.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."),
 			),
 			mcp.WithString("query",
-				mcp.Description(`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`),
+				mcp.Description(`Filter projects by title text and open/closed state; permitted qualifiers: is:open, is:closed; examples: "roadmap is:open", "is:open feature planning".`),
 			),
 			mcp.WithNumber("per_page",
 				mcp.Description(fmt.Sprintf("Results per page (max %d)", MaxProjectsPerPage)),
@@ -396,7 +389,7 @@ func ListProjectItems(getClient GetClientFn, t translations.TranslationHelperFun
 				mcp.Description("The project's number."),
 			),
 			mcp.WithString("query",
-				mcp.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.`),
+				mcp.Description(`Query string for advanced filtering of project items using GitHub's project filtering syntax.`),
 			),
 			mcp.WithNumber("per_page",
 				mcp.Description(fmt.Sprintf("Results per page (max %d)", MaxProjectsPerPage)),