projects: tool consolidation and prompt updates

README.md

@@ -795,63 +795,27 @@ Options are:
 
 <summary>Projects</summary>
 
-- **add_project_item** - Add project item
-  - `item_id`: The numeric ID of the issue or pull request to add to the project. (number, required)
-  - `item_type`: The item's type, either issue or pull_request. (string, required)
-  - `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)
-  - `project_number`: The project's number. (number, required)
-
-- **delete_project_item** - Delete project item
-  - `item_id`: The internal project item ID to delete from the project (not the issue or pull request ID). (number, required)
-  - `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)
-  - `project_number`: The project's number. (number, required)
-
-- **get_project** - Get project
-  - `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)
-  - `project_number`: The project's number (number, required)
-
-- **get_project_field** - Get project field
-  - `field_id`: The field's id. (number, required)
-  - `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)
-  - `project_number`: The project's number. (number, required)
-
-- **get_project_item** - Get project item
-  - `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)
-  - `item_id`: The item's ID. (number, required)
-  - `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)
-  - `project_number`: The project's number. (number, required)
-
-- **list_project_fields** - List project fields
-  - `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)
-  - `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)
-  - `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)
-  - `project_number`: The project's number. (number, required)
-  - `query`: Search query to filter items (string, optional)
-
-- **list_projects** - List projects
-  - `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)
-
-- **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)
-  - `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)
-  - `project_number`: The project's number. (number, required)
-  - `updated_field`: Object consisting of the ID of the project field to update and the new value for the field. To clear the field, set value to null. Example: {"id": 123456, "value": "New Value"} (object, required)
+- **project_read** - Read project information
+  - `after`: Next page cursor (from pageInfo.endCursor) (string, optional)
+  - `before`: Previous page cursor (from pageInfo.startCursor) (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)
+  - `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)
+
+- **project_write** - Modify project items
+  - `item_id`: For add: issue/PR ID. For update/delete: project item ID (not issue/PR ID) (number, required)
+  - `item_type`: Type to add: 'issue' or 'pull_request' (required for add_project_item) (string, optional)
+  - `method`: Write operation: add_project_item (needs item_type, item_id), update_project_item (needs item_id, updated_field), delete_project_item (needs item_id) (string, required)
+  - `owner`: GitHub username or org name (case-insensitive) (string, required)
+  - `owner_type`: Owner type: 'user' or 'org' (string, required)
+  - `project_number`: Project number (number, required)
+  - `updated_field`: Field update object (required for update_project_item). Format: {"id": 123456, "value": <value>}. Value types: text=string, single-select=option ID (number), date=ISO string, number=number. Set value to null to clear. (object, optional)
 
 </details>
 

pkg/github/__toolsnaps__/project_read.snap

@@ -0,0 +1,77 @@
+{
+  "annotations": {
+    "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*'",
+  "inputSchema": {
+    "properties": {
+      "after": {
+        "description": "Next page cursor (from pageInfo.endCursor)",
+        "type": "string"
+      },
+      "before": {
+        "description": "Previous page cursor (from pageInfo.startCursor)",
+        "type": "string"
+      },
+      "field_id": {
+        "description": "Field ID (required for get_project_field)",
+        "type": "number"
+      },
+      "fields": {
+        "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"
+        },
+        "type": "array"
+      },
+      "item_id": {
+        "description": "Item ID (required for get_project_item)",
+        "type": "number"
+      },
+      "method": {
+        "description": "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)",
+        "enum": [
+          "get_project",
+          "list_projects",
+          "get_project_field",
+          "list_project_fields",
+          "get_project_item",
+          "list_project_items"
+        ],
+        "type": "string"
+      },
+      "owner": {
+        "description": "GitHub username or org name (case-insensitive)",
+        "type": "string"
+      },
+      "owner_type": {
+        "description": "Owner type: 'user' or 'org'",
+        "enum": [
+          "user",
+          "org"
+        ],
+        "type": "string"
+      },
+      "per_page": {
+        "description": "Results per page (max 20)",
+        "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",
+        "type": "string"
+      }
+    },
+    "required": [
+      "method",
+      "owner_type",
+      "owner"
+    ],
+    "type": "object"
+  },
+  "name": "project_read"
+}

pkg/github/__toolsnaps__/project_write.snap

@@ -0,0 +1,62 @@
+{
+  "annotations": {
+    "title": "Modify project items",
+    "readOnlyHint": false
+  },
+  "description": "Write operations for GitHub Projects V2.\n\nMethods: add_project_item (add issue/PR), update_project_item (update fields), delete_project_item (remove item).\nNote: item_id for add is the issue/PR ID; for update/delete it's the project item ID.",
+  "inputSchema": {
+    "properties": {
+      "item_id": {
+        "description": "For add: issue/PR ID. For update/delete: project item ID (not issue/PR ID)",
+        "type": "number"
+      },
+      "item_type": {
+        "description": "Type to add: 'issue' or 'pull_request' (required for add_project_item)",
+        "enum": [
+          "issue",
+          "pull_request"
+        ],
+        "type": "string"
+      },
+      "method": {
+        "description": "Write operation: add_project_item (needs item_type, item_id), update_project_item (needs item_id, updated_field), delete_project_item (needs item_id)",
+        "enum": [
+          "add_project_item",
+          "update_project_item",
+          "delete_project_item"
+        ],
+        "type": "string"
+      },
+      "owner": {
+        "description": "GitHub username or org name (case-insensitive)",
+        "type": "string"
+      },
+      "owner_type": {
+        "description": "Owner type: 'user' or 'org'",
+        "enum": [
+          "user",
+          "org"
+        ],
+        "type": "string"
+      },
+      "project_number": {
+        "description": "Project number",
+        "type": "number"
+      },
+      "updated_field": {
+        "description": "Field update object (required for update_project_item). Format: {\"id\": 123456, \"value\": \u003cvalue\u003e}. Value types: text=string, single-select=option ID (number), date=ISO string, number=number. Set value to null to clear.",
+        "properties": {},
+        "type": "object"
+      }
+    },
+    "required": [
+      "method",
+      "owner_type",
+      "owner",
+      "project_number",
+      "item_id"
+    ],
+    "type": "object"
+  },
+  "name": "project_write"
+}