@crypto512/jicon-mcp 2.3.0 → 2.3.19

package/TOOL_LIST.md

@@ -5,16 +5,17 @@ This document provides a comprehensive reference of all available tools in the J
 
 ## Summary
 
-**Total Tools**: 80
-- **Jira Tools**: 27 (22 read + 5 write)
-- **Confluence Tools**: 21 (13 read + 8 write)
-- **Tempo Tools**: 13 (10 read + 3 write)
-- **Buffer Tools**: 11
-- **Workload Tools**: 2
-- **URL Tools**: 2
-- **Jicon Help Tools**: 1
-- **Date Tools**: 1
-- **PlantUML Tools**: 3
+**Tool Categories**:
+- **Jira Tools** - Issue search, CRUD, transitions, comments, boards, sprints, epic analysis
+- **Confluence Tools** - Page search, CRUD, draft workflow, review workflow, comments, attachments
+- **Tempo Tools** - Worklog management, accounts, teams, time analysis
+- **Buffer Tools** - Content buffering, XHTML editing, transformation, schema discovery
+- **Workload Tools** - Time conversion and calculation utilities
+- **URL Tools** - Full URL construction and parsing
+- **Date Tools** - Date expression resolution
+- **Help Tools** - Unified help system with topics
+- **Whoami Tools** - User identity across services
+- **PlantUML Tools** - Diagram validation and rendering
 
 **Note**: All data-heavy tools (search, list, get) **always** return buffered responses with metadata for origin tracking:
 - **JSON arrays**: Use `buffer_get_items` for complete items, `buffer_transform` for reports
@@ -137,7 +138,7 @@ When XHTML validation fails, the response includes element ID and suggested acti
 
 ---
 
-## Jira Tools (27)
+## Jira Tools (29)
 
 ### Localization / Non-English Jira
 
@@ -166,8 +167,8 @@ The server automatically handles localized changelog field names for activity tr
 
 ---
 
-### 1. jira_search_issues
-**Description**: Search for Jira issues using JQL. Auto-fetches all results (up to 5000).
+### jira_search_issues
+**Description**: Search for Jira issues using JQL. Auto-fetches all matching results.
 **Use Cases**: Find bugs, filter by status, search by assignee, complex queries
 
 | Parameter | Type | Required | Description |
@@ -180,7 +181,6 @@ The server automatically handles localized changelog field names for activity tr
 |-------|-------------|
 | `returnedItems` | Items available in buffer - **USE THIS** for actual count |
 | `jiraTotalMatching` | Total matching in Jira (may exceed returnedItems) |
-| `apiLimit` | Maximum items per search (5000 cap) |
 | `note` | Explanation when results are truncated |
 
 **Example Response** (when JQL matches 9998 issues):
@@ -189,7 +189,6 @@ The server automatically handles localized changelog field names for activity tr
   "bufferId": "buf_xxx",
   "returnedItems": 5000,
   "jiraTotalMatching": 9998,
-  "apiLimit": 5000,
   "note": "9998 issues match query, 5000 returned (API limit)"
 }
 ```
@@ -198,7 +197,7 @@ The server automatically handles localized changelog field names for activity tr
 
 ---
 
-### 2. jira_get_issue
+### jira_get_issue
 **Description**: Get detailed information about a specific issue
 **Use Cases**: View issue details, check status, read description and comments
 
@@ -212,7 +211,20 @@ The server automatically handles localized changelog field names for activity tr
 
 ---
 
-### 3. jira_create_issue
+### jira_get_issues
+**Description**: Get multiple Jira issues at once in a single buffer
+**Use Cases**: Batch fetch issues by key instead of calling jira_get_issue N times; compare issues side by side; bulk analysis
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| issueKeys | string \| string[] | ✓ | Single key or array of keys (e.g., "PROJ-123" or ["PROJ-123","PROJ-456"]) |
+| fields | string[] | ✗ | Specific fields to return |
+
+**Returns**: `bufferId` with flat issues array (same `jira_issue` schema as `jira_search_issues`). Use `buffer_transform` for tables, `buffer_get_items` for analysis.
+
+---
+
+### jira_create_issue
 **Description**: Create a new Jira issue
 **Use Cases**: Report bugs, create tasks, add stories to backlog
 
@@ -230,7 +242,7 @@ The server automatically handles localized changelog field names for activity tr
 
 ---
 
-### 4. jira_update_issue
+### jira_update_issue
 **Description**: Update fields on an existing issue
 **Use Cases**: Change priority, update description, modify assignee
 
@@ -245,7 +257,7 @@ The server automatically handles localized changelog field names for activity tr
 
 ---
 
-### 5. jira_transition_issue
+### jira_transition_issue
 **Description**: Move issue to different status
 **Use Cases**: Start work, mark as done, move to review
 
@@ -258,7 +270,7 @@ The server automatically handles localized changelog field names for activity tr
 
 ---
 
-### 6. jira_add_comment
+### jira_add_comment
 **Description**: Add a comment to an issue
 **Use Cases**: Provide updates, ask questions, document decisions
 
@@ -270,7 +282,7 @@ The server automatically handles localized changelog field names for activity tr
 
 ---
 
-### 7. jira_get_issue_comments
+### jira_get_issue_comments
 **Description**: Retrieve all comments from a Jira issue
 **Use Cases**: Read discussion history, check updates
 
@@ -283,7 +295,7 @@ The server automatically handles localized changelog field names for activity tr
 
 ---
 
-### 8. jira_list_projects
+### jira_list_projects
 **Description**: List all accessible Jira projects
 **Use Cases**: Discover available projects, get project keys
 
@@ -296,7 +308,7 @@ The server automatically handles localized changelog field names for activity tr
 
 ---
 
-### 9. jira_get_project
+### jira_get_project
 **Description**: Get detailed project information
 **Use Cases**: View project details, components, versions
 
@@ -309,7 +321,7 @@ The server automatically handles localized changelog field names for activity tr
 
 ---
 
-### 10. jira_get_issue_types
+### jira_get_issue_types
 **Description**: Get all available issue types in this Jira instance
 **Use Cases**: Discover type names before filtering by type in JQL, find localized or custom type names
 
@@ -321,29 +333,44 @@ The server automatically handles localized changelog field names for activity tr
 
 ---
 
-### 11. jira_get_fields
-**Description**: Get all available Jira fields (system and custom)
+### jira_get_fields
+**Description**: Get Jira fields (system and custom). Requires a search term or "all".
 **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) |
+| search | string | **Yes** | `"all"` to return every field, or a search term to filter by name, id, clauseNames, or schemaType (case-insensitive) |
+| filter | enum | No | Filter by category: "all" (default), "custom", "system", or "navigable" |
 
 **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
+1. Call `jira_get_fields(search="epic")` — matches name, id, clauseNames, AND schemaType
 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`
+3. Use `cf[ID]` from clauseNames in JQL: `cf[10014] IS EMPTY`
+
+**Tip**: The `clauseNames` array shows all valid JQL names for a field. The `cf[ID]` syntax always works regardless of language. The search also matches `schemaType`, so `search="epic"` finds the Epic Link field even on French instances where it's named "Lien d'épopée".
+
+---
 
-**Tip**: The `clauseNames` array shows all valid JQL names for a field. The `cf[ID]` syntax always works regardless of language.
+### jira_search_users
+**Description**: Search for Jira users by name, username, or email
+**Use Cases**: Find a person's username before building JQL queries with assignee/reporter
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| query | string | ✓ | Search text (display name, username, or email) |
+| maxResults | number | ✗ | Maximum results (default: 20) |
+
+**Returns**: Inline list of matching users with `key`, `name`, `displayName`, `emailAddress`.
+
+**Example workflow**:
+1. `jira_search_users(query="Fabien")` → finds users matching "Fabien"
+2. Use username in JQL: `assignee = "fthuillier"`
 
 ---
 
-### 12. jira_get_transitions
+### jira_get_transitions
 **Description**: Get available workflow transitions for an issue
 **Use Cases**: Check what status changes are possible
 
@@ -353,7 +380,7 @@ The server automatically handles localized changelog field names for activity tr
 
 ---
 
-### 13. jira_link_issues
+### jira_link_issues
 **Description**: Create a link between two issues
 **Use Cases**: Mark blockers, relate issues, create dependencies
 
@@ -366,7 +393,7 @@ The server automatically handles localized changelog field names for activity tr
 
 ---
 
-### 14. jira_list_boards
+### jira_list_boards
 **Description**: List all Jira Agile boards (Scrum and Kanban). Entry point for board discovery.
 **Use Cases**: Discover available boards, filter by project or type, find board IDs
 
@@ -387,7 +414,7 @@ jira_list_boards(type="scrum")             # Only Scrum boards
 
 ---
 
-### 15. jira_get_board
+### jira_get_board
 **Description**: Get Agile board information
 **Use Cases**: View board details, get board configuration
 
@@ -399,7 +426,7 @@ jira_list_boards(type="scrum")             # Only Scrum boards
 
 ---
 
-### 16. jira_get_sprints
+### jira_get_sprints
 **Description**: List all sprints for a board
 **Use Cases**: View active sprints, check sprint schedules
 
@@ -412,7 +439,7 @@ jira_list_boards(type="scrum")             # Only Scrum boards
 
 ---
 
-### 17. jira_get_sprint_issues
+### jira_get_sprint_issues
 **Description**: Get all issues in a specific sprint
 **Use Cases**: View sprint backlog, check sprint progress
 
@@ -424,7 +451,7 @@ jira_list_boards(type="scrum")             # Only Scrum boards
 
 ---
 
-### 18. jira_get_issue_watchers
+### jira_get_issue_watchers
 **Description**: Get list of watchers on an issue
 **Use Cases**: See who's following an issue
 
@@ -434,7 +461,7 @@ jira_list_boards(type="scrum")             # Only Scrum boards
 
 ---
 
-### 19. jira_get_issue_worklogs
+### jira_get_issue_worklogs
 **Description**: Retrieve all worklogs from a Jira issue
 **Use Cases**: Analyze time logged against an issue, see worklog history
 
@@ -446,7 +473,7 @@ jira_list_boards(type="scrum")             # Only Scrum boards
 
 ---
 
-### 20. jira_get_total_worklogs
+### 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
 
@@ -458,7 +485,7 @@ jira_list_boards(type="scrum")             # Only Scrum boards
 
 ---
 
-### 21. jira_list_epic_children
+### 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
 
@@ -481,7 +508,7 @@ Automatically detects Epic Link and Parent Link fields for language-independent
 
 ---
 
-### 22. jira_get_activity_digest
+### 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
 
@@ -492,7 +519,7 @@ Fetches comments, status changes, priority changes, and assignee changes - forma
 | projectKey | string | ✗ | Filter by project key |
 | jql | string | ✗ | Full JQL query for flexible scoping |
 | issueKeys | string[] | ✗ | Specific issue keys to include |
-| since | string | ✗ | Time range: "1d", "7d", "30d", or ISO date (default: "7d") |
+| since | string | ✗ | Time range: "7d", "30d", "365d", or ISO date (default: "30d"). Provide explicitly for accurate results. |
 | includeComments | boolean | ✗ | Include comments (default: true) |
 | includeStatusChanges | boolean | ✗ | Include status changes (default: true) |
 | includePriorityChanges | boolean | ✗ | Include priority changes (default: true) |
@@ -522,27 +549,27 @@ Fetches comments, status changes, priority changes, and assignee changes - forma
 
 ---
 
-### 23. 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
+### jira_get_recent_comments
+**Description**: Get comments across multiple issues for analysis. Returns buffered data.
+**Use Cases**: Comment statistics (top commenters), discussion analysis, finding comments about specific topics
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | projectKey | string | ✗ | Filter by project key |
 | jql | string | ✗ | Full JQL query for flexible scoping |
 | issueKeys | string[] | ✗ | Specific issue keys to include |
-| since | string | ✗ | Time range: "1d", "7d", "30d", or ISO date (default: "7d") |
+| since | string | ✗ | Time range: "7d", "30d", "365d", or ISO date (default: "30d"). Provide explicitly for accurate results. |
 | authorKey | string | ✗ | Filter by comment author username |
-| maxComments | number | ✗ | Maximum comments to return (default: 30) |
-| includeContext | boolean | ✗ | Include issue summary/status (default: true) |
+| maxComments | number | ✗ | Maximum comments to return (default: all) |
 
 **At least one scoping parameter required**: `projectKey`, `jql`, or `issueKeys`
 
-**Returns**: Markdown-formatted comments grouped by issue with summary statistics.
+**Returns**: bufferId with `jira_comment` schema (issueKey, issueSummary, author, authorEmail, body, created, updated).
+**Next**: `buffer_transform` for stats/tables, `buffer_grep` to search comments.
 
 ---
 
-### 24. jira_get_changelog
+### 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
 
@@ -551,7 +578,7 @@ Fetches comments, status changes, priority changes, and assignee changes - forma
 | projectKey | string | ✗ | Filter by project key |
 | jql | string | ✗ | Full JQL query for flexible scoping |
 | issueKeys | string[] | ✗ | Specific issue keys to include |
-| since | string | ✗ | Time range: "1d", "7d", "30d", or ISO date (default: "7d") |
+| since | string | ✗ | Time range: "7d", "30d", "365d", or ISO date (default: "30d"). Provide explicitly for accurate results. |
 | fields | string[] | ✗ | Fields to track (default: ["status", "priority", "assignee", "resolution"]) |
 | maxChanges | number | ✗ | Maximum changes to return (default: 50) |
 
@@ -572,7 +599,7 @@ Fetches comments, status changes, priority changes, and assignee changes - forma
 
 ---
 
-### 25. jira_analyze_epic
+### 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
 
@@ -617,7 +644,7 @@ Currently **3 issues** are in progress.
 
 ---
 
-### 26. jira_epic_summary
+### 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
 
@@ -664,7 +691,7 @@ Provides quick overview without the heavy metrics of `jira_analyze_epic` - no ti
 
 ---
 
-### 27. jira_analyze_sprint
+### jira_analyze_sprint
 **Description**: Comprehensive Sprint analysis for LLM insights. Returns DIRECTLY (not buffered).
 **Use Cases**: Sprint progress, risk assessment, team workload, daily standups
 
@@ -751,11 +778,12 @@ Time tracking shows **71% of estimate used** for **65% completion**.
 
 ---
 
-## Confluence Tools (21)
+## Confluence Tools (20)
 
-### 1. confluence_search_content
+### confluence_search_content
 **Description**: Search Confluence content using CQL. Auto-fetches all results.
 **Use Cases**: Find pages, search by keyword, filter by space
+**CQL Syntax**: See `help(topic="cql")` for valid fields and examples.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -766,7 +794,7 @@ Time tracking shows **71% of estimate used** for **65% completion**.
 
 ---
 
-### 2. confluence_get_page
+### confluence_get_page
 **Description**: Get a Confluence page by ID (PREFERRED when you have page ID)
 **Use Cases**: Read page content, prepare for editing
 
@@ -781,7 +809,7 @@ Time tracking shows **71% of estimate used** for **65% completion**.
 
 ---
 
-### 3. confluence_get_page_by_title
+### confluence_get_page_by_title
 **Description**: Get a page by title and space (use ONLY when you don't have page ID)
 **Use Cases**: Find page by name, access documentation
 
@@ -797,7 +825,7 @@ Time tracking shows **71% of estimate used** for **65% completion**.
 
 ---
 
-### 4. confluence_edit (RECOMMENDED)
+### confluence_edit (RECOMMENDED)
 **Description**: Smart page/draft loader - auto-resolves URLs, pageIds, draftIds, or SPACE/Title
 **Use Cases**: Edit any Confluence content with a single tool, handle URL input from users
 
@@ -847,7 +875,7 @@ buffer_edit(bufferId=pageBuffer, after=5, fromBufferId=newContentBuffer)
 
 ---
 
-### 5. confluence_delete_page
+### confluence_delete_page
 **Description**: Delete a Confluence page
 **Use Cases**: Remove outdated content
 
@@ -857,7 +885,7 @@ buffer_edit(bufferId=pageBuffer, after=5, fromBufferId=newContentBuffer)
 
 ---
 
-### 6. confluence_list_spaces
+### confluence_list_spaces
 **Description**: List all accessible Confluence spaces
 **Use Cases**: Discover available spaces, get space keys
 
@@ -869,7 +897,7 @@ buffer_edit(bufferId=pageBuffer, after=5, fromBufferId=newContentBuffer)
 
 ---
 
-### 7. confluence_get_space
+### confluence_get_space
 **Description**: Get detailed information about a space
 **Use Cases**: View space details, get homepage
 
@@ -882,7 +910,7 @@ buffer_edit(bufferId=pageBuffer, after=5, fromBufferId=newContentBuffer)
 
 ---
 
-### 8. confluence_get_page_children
+### confluence_get_page_children
 **Description**: Get all child pages of a page
 **Use Cases**: Navigate page hierarchy, list subpages
 
@@ -895,7 +923,7 @@ buffer_edit(bufferId=pageBuffer, after=5, fromBufferId=newContentBuffer)
 
 ---
 
-### 9. confluence_add_comment
+### confluence_add_comment
 **Description**: Add a comment to a Confluence page
 **Use Cases**: Provide feedback, ask questions
 
@@ -906,7 +934,7 @@ buffer_edit(bufferId=pageBuffer, after=5, fromBufferId=newContentBuffer)
 
 ---
 
-### 10. confluence_get_comments
+### confluence_get_comments
 **Description**: Get all comments on a Confluence page
 **Use Cases**: Read feedback, review discussions
 
@@ -918,7 +946,7 @@ buffer_edit(bufferId=pageBuffer, after=5, fromBufferId=newContentBuffer)
 
 ---
 
-### 11. confluence_upload_attachment
+### confluence_upload_attachment
 **Description**: Upload an attachment to a Confluence page
 **Use Cases**: Attach documents, upload images
 
@@ -930,7 +958,7 @@ buffer_edit(bufferId=pageBuffer, after=5, fromBufferId=newContentBuffer)
 
 ---
 
-### 12. confluence_list_attachments
+### confluence_list_attachments
 **Description**: List all attachments on a Confluence page
 **Use Cases**: View uploaded files, check attachments
 
@@ -942,23 +970,10 @@ buffer_edit(bufferId=pageBuffer, after=5, fromBufferId=newContentBuffer)
 
 ---
 
-### 13. confluence_get_current_user_space
-**Description**: Get the current user's personal Confluence space
-**Use Cases**: Verify personal space before write operations, check space key for write-home restriction
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| (none) | | | |
-
-**Response includes**: `spaceKey`, `spaceName`, `spaceType`, `homePageId`, `homePageTitle`
-
-**Tip**: Use this to find your personal space key when write-home restriction is enabled.
-
----
-
-### 14. confluence_draft_list
-**Description**: List user's draft pages
+### confluence_draft_list
+**Description**: List user's UNPUBLISHED draft pages (work-in-progress content)
 **Use Cases**: View pending drafts, find drafts to continue editing
+**NOTE**: To find published pages you edited, use `confluence_search_content(cql="contributor=currentUser()")`
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -968,7 +983,7 @@ buffer_edit(bufferId=pageBuffer, after=5, fromBufferId=newContentBuffer)
 
 ---
 
-### 15. confluence_draft_open
+### confluence_draft_open
 **Description**: Load existing draft into buffer for editing
 **Use Cases**: Continue editing a draft, prepare draft for publishing
 
@@ -982,7 +997,7 @@ buffer_edit(bufferId=pageBuffer, after=5, fromBufferId=newContentBuffer)
 
 ---
 
-### 16. confluence_draft_create
+### confluence_draft_create
 **Description**: Create a draft for user review - either a new page or as an edit to an existing page
 **Use Cases**: Start new page as draft, edit existing page through draft workflow
 
@@ -1044,7 +1059,7 @@ buffer_edit(bufferId=pageBuffer, after=5, fromBufferId=newContentBuffer)
 
 ---
 
-### 17. confluence_draft_save
+### confluence_draft_save
 **Description**: Save buffer content to draft (delete + recreate pattern)
 **Use Cases**: Checkpoint work, persist edits before publishing
 
@@ -1062,7 +1077,7 @@ buffer_edit(bufferId=pageBuffer, after=5, fromBufferId=newContentBuffer)
 
 ---
 
-### 18. confluence_draft_delete
+### confluence_draft_delete
 **Description**: Permanently delete a draft
 **Use Cases**: Clean up abandoned drafts, remove unwanted content
 
@@ -1074,7 +1089,7 @@ buffer_edit(bufferId=pageBuffer, after=5, fromBufferId=newContentBuffer)
 
 ---
 
-### 19. confluence_review_list
+### confluence_review_list
 **Description**: List all "[jicon-mcp REVIEW]" drafts for cleanup or management
 **Use Cases**: Find abandoned review drafts, manage multiple review workflows, clean up after publishing
 
@@ -1088,7 +1103,7 @@ buffer_edit(bufferId=pageBuffer, after=5, fromBufferId=newContentBuffer)
 
 ---
 
-### 20. confluence_review_publish
+### confluence_review_publish
 **Description**: Publish a review draft to apply changes to the original page
 **Use Cases**: Apply reviewed changes to the original page, complete the review workflow
 
@@ -1108,7 +1123,7 @@ buffer_edit(bufferId=pageBuffer, after=5, fromBufferId=newContentBuffer)
 
 ---
 
-### 21. confluence_review_discard
+### confluence_review_discard
 **Description**: Discard a review draft without applying changes to the original page
 **Use Cases**: Cancel a review, abandon changes, clean up unwanted review drafts
 
@@ -1129,7 +1144,7 @@ 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.
+> **Note**: Type, status, and priority names below are in English. Use `jira_get_issue_types()` and `jira_get_fields(search="epic")` to discover actual names for your Jira instance. Functions like `currentUser()`, `openSprints()`, `startOfDay()` work in all languages.
 
 ```jql
 # Find open bugs assigned to you
@@ -1233,7 +1248,7 @@ AND lastModified >= now("-30d")
 
 ## Tempo Tools (13)
 
-### 1. tempo_get_worklogs
+### tempo_get_worklogs
 **Description**: Get Tempo worklogs with filters
 **Use Cases**: View time entries, generate reports, review team work
 
@@ -1251,7 +1266,7 @@ AND lastModified >= now("-30d")
 
 ---
 
-### 2. tempo_get_worklog
+### tempo_get_worklog
 **Description**: Get detailed information about a specific worklog entry
 **Use Cases**: View worklog details, check time logged
 
@@ -1263,7 +1278,7 @@ AND lastModified >= now("-30d")
 
 ---
 
-### 3. tempo_log_work
+### tempo_log_work
 **Description**: Log time to a Jira issue
 **Use Cases**: Record work time, track daily activities
 
@@ -1278,7 +1293,7 @@ AND lastModified >= now("-30d")
 
 ---
 
-### 4. tempo_update_worklog
+### tempo_update_worklog
 **Description**: Update an existing worklog entry
 **Use Cases**: Correct time logged, update descriptions
 
@@ -1294,7 +1309,7 @@ AND lastModified >= now("-30d")
 
 ---
 
-### 5. tempo_delete_worklog
+### tempo_delete_worklog
 **Description**: Delete a worklog entry
 **Use Cases**: Remove incorrect entries
 
@@ -1304,7 +1319,7 @@ AND lastModified >= now("-30d")
 
 ---
 
-### 6. tempo_get_accounts
+### tempo_get_accounts
 **Description**: Get all Tempo accounts
 **Use Cases**: List accounts for time tracking, find account keys
 
@@ -1316,7 +1331,7 @@ AND lastModified >= now("-30d")
 
 ---
 
-### 7. tempo_get_account
+### tempo_get_account
 **Description**: Get detailed information about a Tempo account
 **Use Cases**: View account details, check status
 
@@ -1328,7 +1343,7 @@ AND lastModified >= now("-30d")
 
 ---
 
-### 8. tempo_get_teams
+### tempo_get_teams
 **Description**: Get all Tempo teams
 **Use Cases**: List teams, find team IDs
 
@@ -1340,7 +1355,7 @@ AND lastModified >= now("-30d")
 
 ---
 
-### 9. tempo_get_team
+### tempo_get_team
 **Description**: Get detailed information about a Tempo team
 **Use Cases**: View team details, check membership
 
@@ -1352,7 +1367,7 @@ AND lastModified >= now("-30d")
 
 ---
 
-### 10. tempo_get_team_worklogs
+### tempo_get_team_worklogs
 **Description**: Get all worklogs for a team within a date range
 **Use Cases**: Team capacity reports, sprint reviews
 
@@ -1366,7 +1381,7 @@ AND lastModified >= now("-30d")
 
 ---
 
-### 11. tempo_get_user_info
+### tempo_get_user_info
 **Description**: Get current user info (workerKey, username, accountId, displayName)
 **Use Cases**: Get workerKey for filtering worklogs, verify authentication
 
@@ -1378,7 +1393,7 @@ AND lastModified >= now("-30d")
 
 ---
 
-### 12. tempo_get_epic_worklogs
+### tempo_get_epic_worklogs
 **Description**: Get all worklogs for an Epic and its child issues in one API call
 **Use Cases**: Epic time tracking, aggregate time reports, sprint cost analysis
 
@@ -1392,7 +1407,7 @@ AND lastModified >= now("-30d")
 
 ---
 
-### 13. tempo_get_top_worklogs
+### 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
 
@@ -1431,7 +1446,7 @@ Buffer tools are used for local content management. All buffer operations are in
 
 **Data Transformation**: `buffer_transform` transforms JSON buffers (from Jira/Tempo searches) with JavaScript code for filtering, grouping, sorting, and output generation - minimizing token usage.
 
-### 1. buffer_create
+### buffer_create
 **Description**: Create a new buffer with initial content. Returns bufferId and structure.
 
 **TIP**: Call `help(topic="storage")` for XHTML syntax. Call `help(topic="plantuml")` for diagram syntax.
@@ -1485,7 +1500,7 @@ buffer_create({ content: [{"key":"PROJ-1"}], contentType: "json" })    // Native
 
 ---
 
-### 2. buffer_get_items
+### 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
 
@@ -1555,7 +1570,7 @@ buffer_get_items({ bufferId: "buf_xxx" })
 
 ---
 
-### 3. buffer_get_element
+### 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
 
@@ -1588,7 +1603,7 @@ buffer_get_element({
 
 ---
 
-### 4. buffer_set_items
+### 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
 
@@ -1652,7 +1667,7 @@ buffer_set_items({
 
 ---
 
-### 5. buffer_list
+### buffer_list
 **Description**: List all active buffers with their metadata. Buffers are cleaned up when session ends. Max buffers per session configurable via JICON_MAX_BUFFERS (default: 10); oldest unmodified evicted first when full.
 **Use Cases**: View active buffers, recover lost buffer IDs
 
@@ -1664,7 +1679,7 @@ buffer_set_items({
 
 ---
 
-### 6. buffer_clear
+### buffer_clear
 **Description**: Clear a specific buffer or all buffers
 **Use Cases**: Free up memory, clean up after processing
 
@@ -1676,7 +1691,7 @@ buffer_set_items({
 
 ---
 
-### 7. buffer_grep
+### buffer_grep
 **Description**: Search buffered content for patterns. Supports regex, context lines (-A/-B/-C), and case-insensitive (-i). Large results are buffered.
 **Use Cases**: Find specific content in large responses, locate text for editing
 
@@ -1698,7 +1713,7 @@ buffer_set_items({
 
 ---
 
-### 8. buffer_transform
+### buffer_transform
 **Description**: Execute JavaScript code in a secure QuickJS sandbox to transform buffer data.
 **Use Cases**: Server-side data transformation with full JavaScript expressiveness, generate XHTML tables for Confluence, custom filtering/grouping/aggregation
 
@@ -1928,7 +1943,7 @@ buffer_transform({
 - `assignee.displayName`, `reporter.displayName`
 - `created`, `updated`, `resolutiondate`
 - `labels` (array), `components[].name`
-- `timeoriginalestimate`, `timeestimate`, `timespent`
+- `timeoriginalestimate`, `timeestimate`, `timespent` (often null — use `buffer_get_schema` to check `optional` flag)
 
 **Workflow - Jira to Confluence table:**
 ```
@@ -1941,7 +1956,7 @@ buffer_transform({
 
 ---
 
-### 9. buffer_edit
+### buffer_edit
 **Description**: Edit buffer content. For XHTML: use element IDs (single or batch). For plain/json: use string replacement or append.
 **Use Cases**: Insert/replace/remove elements in Confluence pages, modify Jira/Tempo content, compose content from multiple buffers
 
@@ -2073,7 +2088,7 @@ confluence_draft_create({ pageId: "123", bufferId: "buf_A" })
 
 ---
 
-### 10. buffer_get_structure
+### buffer_get_structure
 **Description**: Get current element structure for an XHTML buffer
 **Use Cases**: View element IDs for editing, understand document structure
 
@@ -2107,7 +2122,7 @@ buffer_get_structure({ bufferId: "buf_xxx" })
 
 ---
 
-### 11. buffer_validate_xhtml
+### buffer_validate_xhtml
 **Description**: Validate buffered content as Confluence storage format (XHTML)
 **Use Cases**: Check content validity before writing, debug validation errors
 
@@ -2135,7 +2150,7 @@ buffer_get_structure({ bufferId: "buf_xxx" })
 
 ---
 
-### 12. buffer_get_schema
+### buffer_get_schema
 **Description**: Get the schema for a JSON buffer. Returns field names, types, and sample values from the actual data.
 **Use Cases**: Understand buffer structure before writing `buffer_transform` code, discover available fields for data processing
 
@@ -2150,7 +2165,7 @@ buffer_get_structure({ bufferId: "buf_xxx" })
 **Available Schema Types**:
 | Schema Type | Tools That Return It |
 |-------------|---------------------|
-| `jira_issue` | `jira_search_issues`, `jira_get_issue`, `jira_list_epic_children`, `jira_get_sprint_issues` |
+| `jira_issue` | `jira_search_issues`, `jira_get_issue`, `jira_get_issues`, `jira_list_epic_children`, `jira_get_sprint_issues` |
 | `jira_comment` | `jira_get_issue_comments` |
 | `jira_project` | `jira_list_projects`, `jira_get_project` |
 | `jira_board` | `jira_get_board` |
@@ -2166,7 +2181,16 @@ buffer_get_structure({ bufferId: "buf_xxx" })
 | `confluence_attachment` | `confluence_list_attachments` |
 | `confluence_draft` | `confluence_draft_list` |
 
-**Response includes**: `bufferId`, `schemaType`, `description`, `itemCount` (for arrays), `fields` (with type, required, description, sample)
+**Response includes**: `bufferId`, `schemaType`, `description`, `itemCount` (for arrays), `legend` (property definitions), `fields` (with type, required, optional, searchable, writable, jqlName, description, sample)
+
+**Field Properties**:
+| Property | Meaning |
+|----------|---------|
+| `required` | Always present with a non-null value |
+| `optional` | May be null when not set — use `== null` to check |
+| `searchable` | Can be used in JQL/CQL queries |
+| `writable` | Can be set via update API |
+| `jqlName` | JQL clause name when different from field name (e.g., `type` → `issuetype`) |
 
 **Example - Get schema before writing transform code:**
 ```typescript
@@ -2181,11 +2205,13 @@ buffer_get_schema({ bufferId: "buf_xxx" })
 //   schemaType: "jira_issue",
 //   description: "Jira issue with core fields flattened for easy access",
 //   itemCount: 45,
+//   legend: { required: "Always present...", optional: "May be null...", ... },
 //   fields: {
-//     key: { type: "string", required: true, description: "Issue key (e.g., PROJ-123)", sample: "PROJ-123" },
-//     summary: { type: "string", required: true, description: "Issue title/summary", sample: "Fix login bug" },
-//     status: { type: "string", required: true, description: "Current status name", sample: "In Progress" },
-//     assignee: { type: "string", required: false, description: "Assignee display name", sample: "John Doe" },
+//     key: { type: "string", required: true, searchable: true, description: "Issue key (e.g., PROJ-123)", sample: "PROJ-123" },
+//     summary: { type: "string", required: true, searchable: true, writable: true, description: "Issue title/summary", sample: "Fix login bug" },
+//     status: { type: "string", required: true, searchable: true, description: "Current status name", sample: "In Progress" },
+//     type: { type: "string", required: true, searchable: true, writable: true, jqlName: "issuetype", description: "Issue type name", sample: "Bug" },
+//     assignee: { type: "string", required: false, optional: true, searchable: true, writable: true, description: "Assignee display name", sample: "John Doe" },
 //     ...
 //   }
 // }
@@ -2212,7 +2238,7 @@ buffer_transform({
 
 Utility tools for time calculations. Always available with any Jira, Confluence, or Tempo action.
 
-### 1. workload_convert
+### workload_convert
 **Description**: Convert workload time between units (seconds, hours, days)
 **Use Cases**: Convert time values for display, calculate work estimates
 
@@ -2226,7 +2252,7 @@ Utility tools for time calculations. Always available with any Jira, Confluence,
 
 ---
 
-### 2. workload_sum
+### workload_sum
 **Description**: Sum multiple workload values and return total in all units
 **Use Cases**: Calculate total time from multiple entries, aggregate worklogs
 
@@ -2243,7 +2269,7 @@ Utility tools for time calculations. Always available with any Jira, Confluence,
 
 Utility tools for URL construction and parsing. Always available with any Jira, Confluence, or Tempo action.
 
-### 1. fullurl
+### fullurl
 **Description**: Convert Jira issue keys, Confluence page IDs, or relative paths into full URLs
 **Use Cases**: Generate clickable links for display, resolve relative Confluence paths
 
@@ -2272,7 +2298,7 @@ fullurl("/display/DOCS/Home") // → https://confluence.example.com/display/DOCS
 
 ---
 
-### 2. parseurl
+### parseurl
 **Description**: Parse a Jira or Confluence URL to extract identifiers (pageId, issueKey, draftId, etc.)
 **Use Cases**: Extract IDs from URLs users share, prepare input for other tools
 
@@ -2307,7 +2333,7 @@ fullurl("/display/DOCS/Home") // → https://confluence.example.com/display/DOCS
 
 Unified help system for all Jicon workflows and syntax guides. Always available with any Jira, Confluence, or Tempo action.
 
-### 1. help
+### help
 **Description**: Get Jicon MCP Server help - workflows and syntax guides
 **Use Cases**: Learn workflows, understand tool sequences, get syntax references
 
@@ -2353,7 +2379,7 @@ help(topic="analysis")       // LLM analysis tools guide
 
 Date resolution utility for pre-computing date ranges. Always available with any Jira, Confluence, or Tempo action.
 
-### 1. date_resolve
+### date_resolve
 **Description**: Resolve date expressions to concrete dates with business day counts
 **Use Cases**: Pre-compute date ranges for reports, time tracking, activity analysis
 
@@ -2401,6 +2427,50 @@ date_resolve(expression="this_month") // Current month to date
 
 ---
 
+## Whoami Tools (1)
+
+Unified user identity across all configured services.
+
+### whoami
+**Description**: Get the currently authenticated user from all configured services
+**Use Cases**: Verify credentials, get user keys for queries, check access across services
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| (none) | | | |
+
+**Returns**: User info from each configured service:
+```json
+{
+  "jira": {
+    "key": "JIRAUSER12345",
+    "name": "john.doe",
+    "displayName": "John Doe",
+    "emailAddress": "john.doe@example.com"
+  },
+  "confluence": {
+    "userKey": "JIRAUSER12345",
+    "username": "john.doe",
+    "displayName": "John Doe",
+    "personalSpace": {
+      "spaceKey": "~johndoe",
+      "spaceName": "John Doe",
+      "spaceType": "personal",
+      "homePageId": "123456",
+      "homePageTitle": "John Doe's Home"
+    }
+  }
+}
+```
+
+**Notes**:
+- Returns info from each configured service (Jira, Confluence)
+- Includes Confluence personal space info (for write-home restriction)
+- Errors are collected in `errors` array if any service fails
+- Available in all permission modes (readonly, full, custom)
+
+---
+
 ## PlantUML Tools (3)
 
 PlantUML validation and rendering via external server. Configure with `JICON_PLANTUML_SERVER_URL` environment variable.
@@ -2417,7 +2487,7 @@ PlantUML validation and rendering via external server. Configure with `JICON_PLA
 ```
 Include expansion is enabled by default. Whitelisted URLs: `plantuml-stdlib/*`, `plantuml/*`, `awslabs/aws-icons-for-plantuml/*`. See `help(topic="plantuml")` for examples.
 
-### 1. plantuml_validate
+### plantuml_validate
 **Description**: Validate PlantUML diagram syntax using a real PlantUML server
 **Use Cases**: Check diagram syntax before inserting into Confluence, debug diagram errors
 
@@ -2432,7 +2502,7 @@ Include expansion is enabled by default. Whitelisted URLs: `plantuml-stdlib/*`,
 
 ---
 
-### 2. plantuml_render
+### plantuml_render
 **Description**: Render PlantUML diagram to a specified format
 **Use Cases**: Generate ASCII art for terminal display, create images for documentation
 
@@ -2459,7 +2529,7 @@ plantuml_render({
 
 ---
 
-### 3. plantuml_status
+### plantuml_status
 **Description**: Check PlantUML server status
 **Use Cases**: Verify PlantUML server is available, troubleshoot connection issues
 
@@ -2518,7 +2588,7 @@ All data-heavy tools (search, list, get) **always** return buffered responses wi
 - `buffer_grep(bufferId, pattern)` - Search within buffered data
 
 **Always-Buffered Tools:**
-- **Jira**: `jira_search_issues`, `jira_get_issue`, `jira_list_projects`, `jira_get_project`, `jira_get_board`, `jira_get_sprints`, `jira_get_sprint_issues`, `jira_get_issue_comments`, `jira_get_issue_worklogs`, `jira_get_total_worklogs`
+- **Jira**: `jira_search_issues`, `jira_get_issue`, `jira_get_issues`, `jira_list_projects`, `jira_get_project`, `jira_get_board`, `jira_get_sprints`, `jira_get_sprint_issues`, `jira_get_issue_comments`, `jira_get_issue_worklogs`, `jira_get_total_worklogs`
 - **Confluence**: `confluence_search_content`, `confluence_list_spaces`, `confluence_get_space`, `confluence_get_page_children`, `confluence_get_comments`, `confluence_list_attachments`, `confluence_draft_list`
 - **Tempo**: `tempo_get_worklogs`, `tempo_get_worklog`, `tempo_get_accounts`, `tempo_get_account`, `tempo_get_teams`, `tempo_get_team`, `tempo_get_team_worklogs`, `tempo_get_epic_worklogs`