@crypto512/jicon-mcp 2.1.0 → 2.2.0

package/TOOL_LIST.md

@@ -5,10 +5,10 @@ This document provides a comprehensive reference of all available tools in the J
 
 ## Summary
 
-**Total Tools**: 75
-- **Jira Tools**: 22 (17 read + 5 write)
+**Total Tools**: 79
+- **Jira Tools**: 26 (21 read + 5 write)
 - **Confluence Tools**: 21 (13 read + 8 write)
-- **Tempo Tools**: 12 (9 read + 3 write)
+- **Tempo Tools**: 13 (10 read + 3 write)
 - **Buffer Tools**: 11
 - **Workload Tools**: 2
 - **URL Tools**: 2
@@ -21,8 +21,6 @@ This document provides a comprehensive reference of all available tools in the J
 - **XHTML**: Use `buffer_get_element` for element-based access
 - **Search**: Use `buffer_grep` to search within any buffer
 
-**Important**: `buffer_get_chunk` is blocked for JSON arrays and XHTML. Use the appropriate tool above.
-
 ---
 
 ## Agentic Workflow Patterns
@@ -139,7 +137,34 @@ When XHTML validation fails, the response includes element ID and suggested acti
 
 ---
 
-## Jira Tools (21)
+## Jira Tools (25)
+
+### Localization / Non-English Jira
+
+**IMPORTANT**: Jira field names, issue types, statuses, and priorities are localized.
+
+| English | French | German |
+|---------|--------|--------|
+| Epic | Épopée | Epic |
+| Story | Story | Story |
+| Bug | Bogue | Fehler |
+| Task | Tâche | Aufgabe |
+| Sub-task | Sous-tâche | Unteraufgabe |
+| Done | Terminé | Erledigt |
+| In Progress | En cours | In Bearbeitung |
+| To Do | À faire | Zu erledigen |
+| Open | Ouvert | Offen |
+| High | Haute | Hoch |
+| Epic Link | Lien d'épopée | Epic-Link |
+
+**Before writing JQL:**
+1. `jira_get_issue_types()` - Discover actual type names
+2. `jira_get_fields(search="epic")` - Discover field names and IDs
+3. Use `cf[ID]` syntax for language-independent queries: `cf[10014] = PROJ-123`
+
+The server automatically handles localized changelog field names for activity tracking.
+
+---
 
 ### 1. jira_search_issues
 **Description**: Search for Jira issues using JQL. Auto-fetches all results (up to 5000).
@@ -183,7 +208,7 @@ When XHTML validation fails, the response includes element ID and suggested acti
 | fields | string[] | ✗ | Specific fields to return |
 | expand | string[] | ✗ | Additional data (e.g., "changelog", "renderedFields") |
 
-**Returns**: `bufferId` with metadata `{resourceType: "jira_issue", title: "PROJ-123: Summary", issueId, projectKey}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
+**Returns**: `bufferId` with metadata `{resourceType: "jira_issue", title: "PROJ-123: Summary", issueId, projectKey}`. Use `buffer_get_items` to read, `buffer_grep` to search.
 
 ---
 
@@ -254,7 +279,7 @@ When XHTML validation fails, the response includes element ID and suggested acti
 | issueKey | string | ✓ | Issue key |
 | orderBy | string | ✗ | Sort order ("created" or "-created") |
 
-**Returns**: `bufferId` with metadata `{resourceType: "jira_comments", title: "PROJ-123 comments", issueKey}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
+**Returns**: `bufferId` with metadata `{resourceType: "jira_comments", title: "PROJ-123 comments", issueKey}`. Use `buffer_get_items` to read, `buffer_grep` to search.
 
 ---
 
@@ -267,7 +292,7 @@ When XHTML validation fails, the response includes element ID and suggested acti
 | recent | boolean | ✗ | Only recent projects |
 | expand | string[] | ✗ | Additional data to expand |
 
-**Returns**: `bufferId` with metadata `{resourceType: "jira_projects", title: "All Projects"}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
+**Returns**: `bufferId` with metadata `{resourceType: "jira_projects", title: "All Projects"}`. Use `buffer_get_items` to read, `buffer_grep` to search.
 
 ---
 
@@ -280,7 +305,7 @@ When XHTML validation fails, the response includes element ID and suggested acti
 | projectKey | string | ✓ | Project key |
 | expand | string[] | ✗ | Additional data to expand |
 
-**Returns**: `bufferId` with metadata `{resourceType: "jira_project", title: "Project Name", projectKey}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
+**Returns**: `bufferId` with metadata `{resourceType: "jira_project", title: "Project Name", projectKey}`. Use `buffer_get_items` to read, `buffer_grep` to search.
 
 ---
 
@@ -296,7 +321,29 @@ When XHTML validation fails, the response includes element ID and suggested acti
 
 ---
 
-### 11. jira_get_transitions
+### 11. jira_get_fields
+**Description**: Get all available Jira fields (system and custom)
+**Use Cases**: Discover field names in user's language, find custom field IDs for JQL, identify Epic Link field
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| filter | enum | ✗ | Filter: "all" (default), "custom", "system", or "navigable" |
+| search | string | ✗ | Search in field name or ID (case-insensitive) |
+
+**Returns**: List of fields with id, name, custom, clauseNames, schemaType
+
+**Example workflow for Epic Link in any language**:
+1. Call `jira_get_fields(search="epic")` to find the Epic Link field
+2. Look for field with `schemaType = "com.pyxis.greenhopper.jira:gh-epic-link"`
+3. Use either:
+   - Localized name: `"Lien d'épopée" = PROJ-123` (French)
+   - Language-independent: `cf[10014] = PROJ-123`
+
+**Tip**: The `clauseNames` array shows all valid JQL names for a field. The `cf[ID]` syntax always works regardless of language.
+
+---
+
+### 12. jira_get_transitions
 **Description**: Get available workflow transitions for an issue
 **Use Cases**: Check what status changes are possible
 
@@ -306,7 +353,7 @@ When XHTML validation fails, the response includes element ID and suggested acti
 
 ---
 
-### 12. jira_link_issues
+### 13. jira_link_issues
 **Description**: Create a link between two issues
 **Use Cases**: Mark blockers, relate issues, create dependencies
 
@@ -319,7 +366,7 @@ When XHTML validation fails, the response includes element ID and suggested acti
 
 ---
 
-### 13. jira_get_board
+### 14. jira_get_board
 **Description**: Get Agile board information
 **Use Cases**: View board details, get board configuration
 
@@ -327,11 +374,11 @@ When XHTML validation fails, the response includes element ID and suggested acti
 |-----------|------|----------|-------------|
 | boardId | number | ✓ | Board ID |
 
-**Returns**: `bufferId` with metadata `{resourceType: "jira_board", title: "Board Name", boardId}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
+**Returns**: `bufferId` with metadata `{resourceType: "jira_board", title: "Board Name", boardId}`. Use `buffer_get_items` to read, `buffer_grep` to search.
 
 ---
 
-### 14. jira_get_sprints
+### 15. jira_get_sprints
 **Description**: List all sprints for a board
 **Use Cases**: View active sprints, check sprint schedules
 
@@ -340,11 +387,11 @@ When XHTML validation fails, the response includes element ID and suggested acti
 | boardId | number | ✓ | Board ID |
 | state | string | ✗ | Sprint state ("active", "future", "closed") |
 
-**Returns**: `bufferId` with metadata `{resourceType: "jira_sprints", title: "Board #123 sprints", boardId}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
+**Returns**: `bufferId` with metadata `{resourceType: "jira_sprints", title: "Board #123 sprints", boardId}`. Use `buffer_get_items` to read, `buffer_grep` to search.
 
 ---
 
-### 15. jira_get_sprint_issues
+### 16. jira_get_sprint_issues
 **Description**: Get all issues in a specific sprint
 **Use Cases**: View sprint backlog, check sprint progress
 
@@ -352,11 +399,11 @@ When XHTML validation fails, the response includes element ID and suggested acti
 |-----------|------|----------|-------------|
 | sprintId | number | ✓ | Sprint ID |
 
-**Returns**: `bufferId` with metadata `{resourceType: "jira_sprint_issues", title: "Sprint #456 issues", sprintId}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
+**Returns**: `bufferId` with metadata `{resourceType: "jira_sprint_issues", title: "Sprint #456 issues", sprintId}`. Use `buffer_get_items` to read, `buffer_grep` to search.
 
 ---
 
-### 16. jira_get_issue_watchers
+### 17. jira_get_issue_watchers
 **Description**: Get list of watchers on an issue
 **Use Cases**: See who's following an issue
 
@@ -366,7 +413,7 @@ When XHTML validation fails, the response includes element ID and suggested acti
 
 ---
 
-### 17. jira_get_issue_worklogs
+### 18. jira_get_issue_worklogs
 **Description**: Retrieve all worklogs from a Jira issue
 **Use Cases**: Analyze time logged against an issue, see worklog history
 
@@ -374,11 +421,11 @@ When XHTML validation fails, the response includes element ID and suggested acti
 |-----------|------|----------|-------------|
 | issueKey | string | ✓ | Issue key (e.g., PROJ-123) |
 
-**Returns**: `bufferId` with metadata `{resourceType: "jira_worklogs", title: "PROJ-123 worklogs", issueKey}`. Includes `worklogCount`, `totalTimeSpentSeconds`, `totalTimeSpent`, `worklogs`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
+**Returns**: `bufferId` with metadata `{resourceType: "jira_worklogs", title: "PROJ-123 worklogs", issueKey}`. Includes `worklogCount`, `totalTimeSpentSeconds`, `totalTimeSpent`, `worklogs`. Use `buffer_get_items` to read, `buffer_grep` to search.
 
 ---
 
-### 18. jira_get_total_worklogs
+### 19. jira_get_total_worklogs
 **Description**: Get total worklogs for an issue and all its children recursively
 **Use Cases**: Get total time spent on an Epic including all stories and sub-tasks
 
@@ -390,7 +437,30 @@ When XHTML validation fails, the response includes element ID and suggested acti
 
 ---
 
-### 19. jira_get_activity_digest
+### 20. jira_list_epic_children
+**Description**: List all children of an Epic/Initiative without needing JQL
+**Use Cases**: Get Epic children, list Initiative epics, find issue hierarchy
+
+Automatically detects Epic Link and Parent Link fields for language-independent queries. Handles:
+- Initiative → Epic (via Parent Link)
+- Epic → Story/Task/Bug (via Epic Link)
+- Any parent → Subtasks
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| parentKey | string | ✓ | Parent issue key (Epic, Initiative, etc.) |
+| type | string | ✗ | Filter by issue type (Story, Task, Bug, etc.) |
+| status | "open" \| "closed" \| "all" | ✗ | Filter by status (default: "all") |
+| recursive | boolean | ✗ | Include nested children recursively (default: false) |
+| fields | string[] | ✗ | Specific fields to return |
+
+**Returns**: `bufferId` with child issues (same format as `jira_search_issues`). Includes metadata `{resourceType: "jira_epic_children", parentKey, recursive, filters}`.
+
+**Example**: `jira_list_epic_children(parentKey="PROJ-100", status="open", type="Story")`
+
+---
+
+### 21. jira_get_activity_digest
 **Description**: Get recent activity across issues for LLM analysis. Returns DIRECTLY (not buffered).
 **Use Cases**: Project activity summary, team updates, blocker detection, weekly reports
 
@@ -431,7 +501,7 @@ Fetches comments, status changes, priority changes, and assignee changes - forma
 
 ---
 
-### 20. jira_get_recent_comments
+### 22. jira_get_recent_comments
 **Description**: Get comments across multiple issues for discussion analysis. Returns DIRECTLY (not buffered).
 **Use Cases**: Discussion summaries, finding comments about specific topics, tracking team communication
 
@@ -451,7 +521,7 @@ Fetches comments, status changes, priority changes, and assignee changes - forma
 
 ---
 
-### 21. jira_get_changelog
+### 23. jira_get_changelog
 **Description**: Get field changes across issues for tracking what happened. Returns DIRECTLY (not buffered).
 **Use Cases**: Status change tracking, priority escalation analysis, assignment history
 
@@ -481,7 +551,7 @@ Fetches comments, status changes, priority changes, and assignee changes - forma
 
 ---
 
-### 22. jira_analyze_epic
+### 24. jira_analyze_epic
 **Description**: Comprehensive Epic/Feature analysis for LLM insights. Returns DIRECTLY (not buffered).
 **Use Cases**: Epic progress analysis, velocity tracking, time metrics, feature status
 
@@ -500,7 +570,7 @@ Fetches comments, status changes, priority changes, and assignee changes - forma
 - **Linked Resources**: Confluence pages, related issues
 - **Recent Discussions**: Comments from the last N days
 
-**Example output**:
+**Example output** *(status names will be in your Jira's language)*:
 ```markdown
 # Epic Analysis: PROJ-100
 **Payment Gateway Integration**
@@ -526,6 +596,140 @@ Currently **3 issues** are in progress.
 
 ---
 
+### 25. jira_epic_summary
+**Description**: Lightweight Epic/Initiative summary with hierarchy and status breakdown. Returns DIRECTLY (not buffered).
+**Use Cases**: Quick Epic overview, status breakdown, cross-project dependencies
+
+Provides quick overview without the heavy metrics of `jira_analyze_epic` - no time tracking, no comments, no Confluence links.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| issueKey | string | ✓ | Epic or parent issue key (e.g., PROJ-123) |
+| includeLinks | boolean | ✗ | Show cross-project dependencies (default: true) |
+| maxDepth | number | ✗ | Maximum recursion depth (default: 3) |
+
+**Returns**: Markdown summary including:
+- Issue list (key, type, summary, status, assignee)
+- Status breakdown by issue type
+- Cross-project dependencies (links to issues outside hierarchy)
+
+**Example output**:
+```markdown
+# Epic Summary: PROJ-100
+**Payment Gateway Integration**
+
+**Status**: In Progress | **Completion**: 65%
+
+## Hierarchy (17 issues)
+
+| Key | Type | Summary | Status | Assignee |
+|-----|------|---------|--------|----------|
+| PROJ-101 | Story | Stripe integration | Done | Alice |
+| PROJ-102 | Story | PayPal support | In Progress | Bob |
+
+## Status Breakdown
+
+| Type | Total | Done | In Progress | To Do | Completion |
+|------|-------|------|-------------|-------|------------|
+| Story | 5 | 3 | 1 | 1 | 60% |
+| Sub-task | 12 | 8 | 2 | 2 | 67% |
+
+## Cross-Project Dependencies (3)
+
+| Source | Relationship | Target | Project | Status |
+|--------|--------------|--------|---------|--------|
+| PROJ-102 | blocks | CORE-45 | CORE | Open |
+```
+
+---
+
+### 26. jira_analyze_sprint
+**Description**: Comprehensive Sprint analysis for LLM insights. Returns DIRECTLY (not buffered).
+**Use Cases**: Sprint progress, risk assessment, team workload, daily standups
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| sprintId | number | ✓ | Sprint ID (from `jira_get_sprints`) |
+| includeComments | boolean | ✗ | Include recent comments (default: true) |
+| commentDays | number | ✗ | Days of comments to include (default: 7) |
+| includeRisks | boolean | ✗ | Calculate risk indicators (default: true) |
+
+**Finding sprintId**: Call `jira_get_sprints(boardId)` first. BoardId can be found in Jira URLs like `/secure/RapidBoard.jspa?rapidView=123`.
+
+**Returns**: Comprehensive markdown analysis including:
+- **Sprint Metadata**: Name, state, dates, duration, days remaining
+- **Progress**: Completion percentage, status breakdown (Done/In Progress/To Do)
+- **Issue Breakdown**: By type with status distribution
+- **Time Metrics**: Estimated vs spent vs remaining, burn rate warning
+- **Team Distribution**: Who's working on what, sorted by workload
+- **Risk Indicators**: Stale issues (3+ days no update), blocked, high-priority unstarted
+- **Recent Discussions**: Comments from last N days
+
+**Example output**:
+```markdown
+# Sprint Analysis: Sprint 42
+
+**State**: Active
+**Period**: Jan 20 - Feb 3 (14 days)
+**Progress**: Day 10 of 14 (4 days remaining)
+
+---
+## Sprint Progress
+
+**Completion**: 65% (13 of 20 issues done)
+
+| Status | Count | % |
+|--------|-------|---|
+| Done | 13 | 65% |
+| In Progress | 4 | 20% |
+| To Do | 3 | 15% |
+
+## Issue Breakdown by Type
+
+| Type | Total | Done | In Progress | To Do |
+|------|-------|------|-------------|-------|
+| Story | 8 | 5 | 2 | 1 |
+| Bug | 6 | 4 | 1 | 1 |
+| Task | 6 | 4 | 1 | 1 |
+
+## Time Metrics
+
+- **Estimated**: 120h (3w)
+- **Spent**: 85h (2w 1d)
+- **Remaining**: 35h (4d 3h)
+- **Burn Rate**: 71% spent, 65% done
+
+## Team Distribution
+
+| Assignee | Total | Done | In Progress |
+|----------|-------|------|-------------|
+| Alice | 5 | 3 | 2 |
+| Bob | 4 | 3 | 1 |
+| Unassigned | 3 | 0 | 0 |
+
+## Risk Indicators
+
+⚠️ **3 issues at risk:**
+- **PROJ-456**: In Progress for 5 days without update
+- **PROJ-789**: High priority, still To Do
+- **PROJ-012**: Blocked by PROJ-999 (In Progress) - external to sprint
+
+## Recent Discussions (last 7 days)
+
+- **PROJ-123** @alice (Jan 28): "Found edge case in payment flow..."
+- **PROJ-456** @bob (Jan 27): "Blocked by API changes..."
+
+---
+## Summary
+
+Sprint "Sprint 42" is **65% complete** with 4 issues in progress and 3 issues remaining.
+**4 days remaining** in the sprint.
+**3 issues** need attention.
+Time tracking shows **71% of estimate used** for **65% completion**.
+```
+
+---
+
 ## Confluence Tools (21)
 
 ### 1. confluence_search_content
@@ -537,7 +741,7 @@ Currently **3 issues** are in progress.
 | cql | string | ✓ | CQL query string |
 | expand | string[] | ✗ | Additional data to expand |
 
-**Returns**: `bufferId` with metadata `{resourceType: "confluence_search", title: "CQL: ..."}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
+**Returns**: `bufferId` with metadata `{resourceType: "confluence_search", title: "CQL: ..."}`. Use `buffer_get_items` to read, `buffer_grep` to search.
 
 ---
 
@@ -640,7 +844,7 @@ buffer_edit(bufferId=pageBuffer, after=5, fromBufferId=newContentBuffer)
 |-----------|------|----------|-------------|
 | type | string | ✗ | Space type filter ("global" or "personal") |
 
-**Returns**: `bufferId` with metadata `{resourceType: "confluence_spaces", title: "All Spaces"}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
+**Returns**: `bufferId` with metadata `{resourceType: "confluence_spaces", title: "All Spaces"}`. Use `buffer_get_items` to read, `buffer_grep` to search.
 
 ---
 
@@ -653,7 +857,7 @@ buffer_edit(bufferId=pageBuffer, after=5, fromBufferId=newContentBuffer)
 | spaceKey | string | ✓ | Space key |
 | expand | string[] | ✗ | Additional data to expand |
 
-**Returns**: `bufferId` with metadata `{resourceType: "confluence_space", title: "Space Name", spaceKey}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
+**Returns**: `bufferId` with metadata `{resourceType: "confluence_space", title: "Space Name", spaceKey}`. Use `buffer_get_items` to read, `buffer_grep` to search.
 
 ---
 
@@ -666,7 +870,7 @@ buffer_edit(bufferId=pageBuffer, after=5, fromBufferId=newContentBuffer)
 | pageId | string | ✓ | Parent page ID (accepts string or number) |
 | expand | string[] | ✗ | Additional data to expand |
 
-**Returns**: `bufferId` with metadata `{resourceType: "confluence_page_children", title: "Page 123 children", pageId}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
+**Returns**: `bufferId` with metadata `{resourceType: "confluence_page_children", title: "Page 123 children", pageId}`. Use `buffer_get_items` to read, `buffer_grep` to search.
 
 ---
 
@@ -689,7 +893,7 @@ buffer_edit(bufferId=pageBuffer, after=5, fromBufferId=newContentBuffer)
 |-----------|------|----------|-------------|
 | pageId | string | ✓ | Page ID (accepts string or number) |
 
-**Returns**: `bufferId` with metadata `{resourceType: "confluence_comments", title: "Page 123 comments", pageId}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
+**Returns**: `bufferId` with metadata `{resourceType: "confluence_comments", title: "Page 123 comments", pageId}`. Use `buffer_get_items` to read, `buffer_grep` to search.
 
 ---
 
@@ -713,7 +917,7 @@ buffer_edit(bufferId=pageBuffer, after=5, fromBufferId=newContentBuffer)
 |-----------|------|----------|-------------|
 | pageId | string | ✓ | Page ID (accepts string or number) |
 
-**Returns**: `bufferId` with metadata `{resourceType: "confluence_attachments", title: "Page 123 attachments", pageId}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
+**Returns**: `bufferId` with metadata `{resourceType: "confluence_attachments", title: "Page 123 attachments", pageId}`. Use `buffer_get_items` to read, `buffer_grep` to search.
 
 ---
 
@@ -739,7 +943,7 @@ buffer_edit(bufferId=pageBuffer, after=5, fromBufferId=newContentBuffer)
 |-----------|------|----------|-------------|
 | spaceKey | string | ✗ | Filter by space key |
 
-**Returns**: `bufferId` with metadata `{resourceType: "confluence_drafts", title: "All Drafts"}`. Includes `drafts` array with `draftId`, `title`, `spaceKey`, `spaceName`, `created`, `url`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
+**Returns**: `bufferId` with metadata `{resourceType: "confluence_drafts", title: "All Drafts"}`. Includes `drafts` array with `draftId`, `title`, `spaceKey`, `spaceName`, `created`, `url`. Use `buffer_get_items` to read, `buffer_grep` to search.
 
 ---
 
@@ -904,6 +1108,8 @@ buffer_edit(bufferId=pageBuffer, after=5, fromBufferId=newContentBuffer)
 
 ### JQL (Jira Query Language) Examples
 
+> **Note**: Type, status, and priority names below are in English. Use `jira_get_issue_types()` and `jira_get_fields()` to discover actual names for your Jira instance. Functions like `currentUser()`, `openSprints()`, `startOfDay()` work in all languages.
+
 ```jql
 # Find open bugs assigned to you
 project = PROJ AND type = Bug AND status = Open AND assignee = currentUser()
@@ -924,6 +1130,8 @@ AND priority in (High, Critical) ORDER BY created DESC
 
 ### CQL (Confluence Query Language) Examples
 
+> **Note**: CQL keywords (`type`, `space`, `label`, `text`) and type values (`page`, `blogpost`) are language-independent. Space keys, labels, and usernames are instance-specific.
+
 ```cql
 # Find pages by title keyword
 type=page AND title~"API Documentation"
@@ -1002,7 +1210,7 @@ AND lastModified >= now("-30d")
 
 ---
 
-## Tempo Tools (12)
+## Tempo Tools (13)
 
 ### 1. tempo_get_worklogs
 **Description**: Get Tempo worklogs with filters
@@ -1018,7 +1226,7 @@ AND lastModified >= now("-30d")
 
 **WARNING**: No workerKey = returns ALL worklogs.
 
-**Returns**: `bufferId` with metadata `{resourceType: "tempo_worklogs", title: "Worklogs 2024-01-01 to 2024-01-31"}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
+**Returns**: `bufferId` with metadata `{resourceType: "tempo_worklogs", title: "Worklogs 2024-01-01 to 2024-01-31"}`. Use `buffer_get_items` to read, `buffer_grep` to search.
 
 ---
 
@@ -1030,7 +1238,7 @@ AND lastModified >= now("-30d")
 |-----------|------|----------|-------------|
 | worklogId | number | ✓ | Tempo worklog ID |
 
-**Returns**: `bufferId` with metadata `{resourceType: "tempo_worklog", title: "PROJ-123 worklog #456", resourceId, issueKey}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
+**Returns**: `bufferId` with metadata `{resourceType: "tempo_worklog", title: "PROJ-123 worklog #456", resourceId, issueKey}`. Use `buffer_get_items` to read, `buffer_grep` to search.
 
 ---
 
@@ -1083,7 +1291,7 @@ AND lastModified >= now("-30d")
 |-----------|------|----------|-------------|
 | (none) | | | |
 
-**Returns**: `bufferId` with metadata `{resourceType: "tempo_accounts", title: "All Tempo Accounts"}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
+**Returns**: `bufferId` with metadata `{resourceType: "tempo_accounts", title: "All Tempo Accounts"}`. Use `buffer_get_items` to read, `buffer_grep` to search.
 
 ---
 
@@ -1095,7 +1303,7 @@ AND lastModified >= now("-30d")
 |-----------|------|----------|-------------|
 | accountKey | string | ✓ | Account key |
 
-**Returns**: `bufferId` with metadata `{resourceType: "tempo_account", title: "Account Name", accountKey}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
+**Returns**: `bufferId` with metadata `{resourceType: "tempo_account", title: "Account Name", accountKey}`. Use `buffer_get_items` to read, `buffer_grep` to search.
 
 ---
 
@@ -1107,7 +1315,7 @@ AND lastModified >= now("-30d")
 |-----------|------|----------|-------------|
 | (none) | | | |
 
-**Returns**: `bufferId` with metadata `{resourceType: "tempo_teams", title: "All Tempo Teams"}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
+**Returns**: `bufferId` with metadata `{resourceType: "tempo_teams", title: "All Tempo Teams"}`. Use `buffer_get_items` to read, `buffer_grep` to search.
 
 ---
 
@@ -1119,7 +1327,7 @@ AND lastModified >= now("-30d")
 |-----------|------|----------|-------------|
 | teamId | number | ✓ | Team ID |
 
-**Returns**: `bufferId` with metadata `{resourceType: "tempo_team", title: "Team Name", teamId}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
+**Returns**: `bufferId` with metadata `{resourceType: "tempo_team", title: "Team Name", teamId}`. Use `buffer_get_items` to read, `buffer_grep` to search.
 
 ---
 
@@ -1133,7 +1341,7 @@ AND lastModified >= now("-30d")
 | dateFrom | string | ✓ | Start date (YYYY-MM-DD) |
 | dateTo | string | ✓ | End date (YYYY-MM-DD) |
 
-**Returns**: `bufferId` with metadata `{resourceType: "tempo_team_worklogs", title: "Team #123 worklogs 2024-01-01 to 2024-01-31", teamId}`. Use `buffer_get_chunk` to read, `buffer_grep` to search.
+**Returns**: `bufferId` with metadata `{resourceType: "tempo_team_worklogs", title: "Team #123 worklogs 2024-01-01 to 2024-01-31", teamId}`. Use `buffer_get_items` to read, `buffer_grep` to search.
 
 ---
 
@@ -1159,7 +1367,38 @@ AND lastModified >= now("-30d")
 | dateFrom | string | ✗ | Start date filter (YYYY-MM-DD) |
 | dateTo | string | ✗ | End date filter (YYYY-MM-DD) |
 
-**Returns**: `bufferId` with metadata `{resourceType: "tempo_epic_worklogs", title: "PROJ-100 epic worklogs", epicKey}`. Includes `totalTimeSpent`, `totalWorklogCount`, `issueCount`, breakdown by issue, and full worklog list. Use `buffer_get_chunk` to read, `buffer_grep` to search. More efficient than `jira_get_total_worklogs` for Tempo instances.
+**Returns**: `bufferId` with metadata `{resourceType: "tempo_epic_worklogs", title: "PROJ-100 epic worklogs", epicKey}`. Includes `totalTimeSpent`, `totalWorklogCount`, `issueCount`, breakdown by issue, and full worklog list. Use `buffer_get_items` to read, `buffer_grep` to search. More efficient than `jira_get_total_worklogs` for Tempo instances.
+
+---
+
+### 13. tempo_get_top_worklogs
+**Description**: Get top issues or users by workload for a period. Returns DIRECTLY (not buffered).
+**Use Cases**: Top tickets by workload, most active contributors, time distribution analysis
+
+Aggregates Tempo worklogs and returns ranked results in markdown format.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| since | string | ✓ | Date expression: "today", "last_week", "this_month", "7d", "30d", etc. |
+| projectKey | string | ✗ | Filter by project key |
+| groupBy | "issue" \| "user" | ✗ | Group results by issue or user (default: "issue") |
+| limit | number | ✗ | Maximum results to return (default: 10) |
+
+**Returns**: Markdown table with ranked results:
+```markdown
+# Top 10 Issues by Workload (MESH)
+**Period**: 2026-01-20 to 2026-01-31
+
+| Rank | Issue | Time Spent | Entries | Contributors |
+|------|-------|------------|---------|--------------|
+| 1 | MESH-4898 | 16h | 8 | Alice, Bob |
+| 2 | MESH-4899 | 8h 30m | 4 | Charlie |
+
+---
+**Total** (top 10): 45h 30m across 42 worklogs
+```
+
+**Example**: `tempo_get_top_worklogs(since="last_week", projectKey="MESH", groupBy="issue", limit=10)`
 
 ---
 
@@ -1178,15 +1417,14 @@ Buffer tools are used for local content management. All buffer operations are in
 
 **Content types**:
 - **xhtml**: Confluence storage format. Returns element IDs for `buffer_edit`.
-- **json**: JSON data (array or object). Use `buffer_pipeline` to filter, aggregate, and transform.
-- **plain**: Raw text content.
+- **json**: JSON data (array or object). Use `buffer_get_items` to access, `buffer_pipeline` to transform.
 
 **Use Cases**: Draft new Confluence pages, prepare content before persisting, create JSON arrays for aggregation
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | content | string \| object \| array | ✓ | Content: string for all types, or object/array for json (auto-stringified) |
-| contentType | enum | ✓ | Content type: `"xhtml"` for Confluence, `"plain"` for text, `"json"` for data |
+| contentType | enum | ✓ | Content type: `"xhtml"` for Confluence, `"json"` for data |
 | metadata | object | ✗ | Optional metadata to attach to the buffer |
 
 **Auto-stringify for JSON**: When `contentType: "json"`, you can pass native objects/arrays directly instead of JSON strings:
@@ -1200,8 +1438,6 @@ buffer_create({ content: [{"key":"PROJ-1"}], contentType: "json" })    // Native
 
 **Response for JSON includes**: `bufferId`, `contentType`, `bufferSizeBytes`, `structure` (type, itemCount/keys, preview), `hint` (suggested next tool)
 
-**Response for plain includes**: `bufferId`, `contentType`, `bufferSizeBytes`, `createdAt`, `expiresAt`
-
 **CDATA Detection**: For XHTML content, the tool detects if content is incorrectly wrapped in `<![CDATA[...]]>` and returns a clear error. CDATA should only be used inside `<ac:plain-text-body>` elements (for code blocks and PlantUML), never around the entire content.
 
 **Example workflow for new Confluence page**:
@@ -1228,41 +1464,24 @@ buffer_create({ content: [{"key":"PROJ-1"}], contentType: "json" })    // Native
 
 ---
 
-### 2. buffer_get_chunk
-**Description**: Retrieve raw character chunks from a buffer. Returns raw content by character offset.
-**Use Cases**: Plain text buffers only, raw character access
-
-**BLOCKED FOR**: JSON arrays and XHTML content. Use instead:
-- JSON arrays: `buffer_get_items` - returns complete items
-- XHTML: `buffer_get_element` - returns element content
+### 2. buffer_get_items
+**Description**: Retrieve items from a JSON buffer (arrays by index, objects by key).
+**Use Cases**: Iterate through search results, access object properties, process items in batches
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| bufferId | string | ✓ | Buffer ID from previous tool response |
-| offset | number | ✗ | Character position to start from (default: 0) |
-| limit | number | ✗ | Maximum characters to return (default: 5000) |
+| bufferId | string | ✓ | Buffer ID containing JSON array or object |
+| start | number | ✗ | Array: starting index (0-based, default: 0) |
+| count | number | ✗ | Array: number of items to return (default: 10, max: 100) |
+| keys | string[] | ✗ | Object: specific keys to retrieve (omit for all keys) |
 
-**Response includes**: `bufferId`, `content`, `offset`, `limit`, `totalSize`, `hasMore`, `metadata`
+**Type Requirement**: Buffer must have `contentType: "json"`. Returns error if buffer is XHTML.
 
-**Error on JSON/XHTML**: Returns error with guidance to use correct tool
-
----
+**Response for arrays**: `bufferId`, `type: "array"`, `items`, `start`, `count`, `totalItems`, `hasMore`, `itemSchema`
 
-### 3. buffer_get_items
-**Description**: Retrieve complete JSON array items from a buffer. Unlike `buffer_get_chunk` which may truncate mid-item, this returns whole items.
-**Use Cases**: Iterate through search results, process items in batches, inspect specific items
+**Response for objects**: `bufferId`, `type: "object"`, `data`, `keys` (all available), `foundKeys`, `missingKeys` (if any)
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| bufferId | string | ✓ | Buffer ID containing JSON array |
-| start | number | ✗ | Starting index (0-based, default: 0) |
-| count | number | ✗ | Number of items to return (default: 10, max: 100) |
-
-**Type Requirement**: Buffer must have `contentType: "json"`. Returns error if buffer is XHTML or plain text.
-
-**Response includes**: `bufferId`, `items` (array of parsed objects), `start`, `count`, `totalItems`, `hasMore`, `itemSchema` (field names in items)
-
-**Example - Get first 10 items:**
+**Example - Array: Get first 10 items:**
 ```typescript
 buffer_get_items({
   bufferId: "buf_xxx",
@@ -1270,6 +1489,7 @@ buffer_get_items({
   count: 10
 })
 // Returns: {
+//   type: "array",
 //   items: [{key: "PROJ-1", ...}, {key: "PROJ-2", ...}, ...],
 //   start: 0,
 //   count: 10,
@@ -1279,23 +1499,42 @@ buffer_get_items({
 // }
 ```
 
-**Example - Page through results:**
+**Example - Array: Page through results:**
 ```typescript
 // Page 1
 buffer_get_items({ bufferId: "buf_xxx", start: 0, count: 50 })
 // Page 2
 buffer_get_items({ bufferId: "buf_xxx", start: 50, count: 50 })
-// Page 3
-buffer_get_items({ bufferId: "buf_xxx", start: 100, count: 50 })
 ```
 
-**When to use `buffer_get_items` vs `buffer_get_chunk`:**
-- Use `buffer_get_items` for JSON array buffers when you need complete items
-- Use `buffer_get_chunk` for XHTML/plain text or when you need raw character access
+**Example - Object: Get specific keys:**
+```typescript
+buffer_get_items({
+  bufferId: "buf_xxx",
+  keys: ["name", "email"]
+})
+// Returns: {
+//   type: "object",
+//   data: { name: "John", email: "john@example.com" },
+//   requestedKeys: ["name", "email"],
+//   foundKeys: ["name", "email"],
+//   availableKeys: ["name", "email", "age", "phone"]
+// }
+```
+
+**Example - Object: Get all keys:**
+```typescript
+buffer_get_items({ bufferId: "buf_xxx" })
+// Returns: {
+//   type: "object",
+//   data: { name: "John", email: "john@example.com", age: 30, phone: "..." },
+//   keys: ["name", "email", "age", "phone"]
+// }
+```
 
 ---
 
-### 4. buffer_get_element
+### 3. buffer_get_element
 **Description**: Get the raw XHTML content of a specific element by ID. Use to inspect problematic elements when fixing XHTML parsing errors.
 **Use Cases**: Debug XHTML validation errors, inspect element content before editing, targeted error recovery
 
@@ -1328,6 +1567,70 @@ buffer_get_element({
 
 ---
 
+### 4. buffer_set_items
+**Description**: Update or append items in a JSON buffer (arrays by ID/append, objects by key).
+**Use Cases**: Modify JSON data after processing, update specific fields, append new items to arrays, merge new data into objects
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| bufferId | string | ✓ | Buffer ID containing JSON array or object |
+| itemId | number | ✗ | Array: ID of the item to update (from buffer structure) |
+| append | boolean | ✗ | Array: append new item instead of updating existing |
+| data | object | ✓ | Data to set/merge/append |
+
+**Type Requirement**: Buffer must have `contentType: "json"`. Returns error if buffer is XHTML.
+
+**For Arrays - Update**: Update an item by its `__jicon_id` (visible in buffer structure). The `data` object replaces the existing item.
+
+**For Arrays - Append**: Set `append=true` to add a new item to the array. Returns the new item's ID.
+
+**For Objects**: Merge the `data` object into the root object. Existing keys are updated, new keys are added.
+
+**Response for array update**: `bufferId`, `type: "array"`, `action: "replace"`, `itemId`, `totalItems`
+
+**Response for array append**: `bufferId`, `type: "array"`, `action: "append"`, `appendedId`, `totalItems`
+
+**Response for objects**: `bufferId`, `type: "object"`, `action: "merge"`, `updatedKeys`, `addedKeys`, `keys`
+
+**Example - Array: Update item by ID:**
+```typescript
+// Buffer structure shows items with IDs: [{id: 1, ...}, {id: 2, ...}]
+buffer_set_items({
+  bufferId: "buf_xxx",
+  itemId: 1,
+  data: { status: "completed", updatedAt: "2024-01-15" }
+})
+// Returns: { type: "array", action: "replace", itemId: 1, totalItems: 2 }
+```
+
+**Example - Array: Append new item:**
+```typescript
+buffer_set_items({
+  bufferId: "buf_xxx",
+  append: true,
+  data: { key: "PROJ-123", summary: "New issue" }
+})
+// Returns: { type: "array", action: "append", appendedId: 3, totalItems: 3 }
+```
+
+**Example - Object: Update/add keys:**
+```typescript
+// Buffer contains: { name: "Alice", age: 30 }
+buffer_set_items({
+  bufferId: "buf_xxx",
+  data: { age: 31, email: "alice@example.com" }
+})
+// Returns: {
+//   type: "object",
+//   action: "merge",
+//   updatedKeys: ["age"],
+//   addedKeys: ["email"],
+//   keys: ["name", "age", "email"]
+// }
+```
+
+---
+
 ### 5. buffer_list
 **Description**: List all active buffers with their metadata
 **Use Cases**: View active buffers, check expiration times
@@ -1676,9 +1979,9 @@ buffer_pipeline({
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | bufferId | string | ✓ | Buffer ID to modify |
-| old_string | string | ✓ | Exact text to replace |
-| new_string | string | ✓ | Replacement text |
-| replace_all | boolean | ✗ | Replace all occurrences (default: false) |
+| oldString | string | ✓ | Exact text to replace |
+| newString | string | ✓ | Replacement text |
+| replaceAll | boolean | ✗ | Replace all occurrences (default: false) |
 
 **Plain/JSON Parameters (append):**
 
@@ -2205,7 +2508,7 @@ Tools enforce type-safe buffer access - each tool only accepts buffers of the ty
 |-------------|------------------------------|
 | **json** | `buffer_pipeline`, `buffer_get_items` |
 | **xhtml** | `buffer_get_structure`, `buffer_get_element`, `buffer_validate_xhtml`, `confluence_draft_create` (with bufferId), `confluence_draft_save` |
-| **any** | `buffer_grep`, `buffer_get_chunk`, `buffer_list`, `buffer_clear`, `buffer_edit` (string mode) |
+| **any** | `buffer_grep`, `buffer_list`, `buffer_clear`, `buffer_edit` (string mode) |
 
 **Error Messages**: When you use a tool with the wrong buffer type, you get a helpful error:
 ```