From b9822f310de4d744b34deea3c74f1ea6635fd748 Mon Sep 17 00:00:00 2001 From: Guillaume BOURGEOIS Date: Wed, 2 Sep 2026 13:56:28 +0200 Subject: [PATCH] docs(jira): say what to type in each command field MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Every input carried a description, and most of them restated the field name: "Comment ID" for comment_id, "Board ID" for board_id, "JQL query string" for query. That is a label, not help. An operator filling get_incidents for the first time has no way to learn from it that the fetch appends its own created >= watermark clause and an ORDER BY, that writing either breaks it, that the watermark box is filled by the alert rule rather than by hand, or that a run makes a single call and silently drops whatever exceeds max. 103 input fields rewritten to answer two questions instead: what goes in this box, and where do I get it. Formats are shown by example rather than named — 2026-09-30 rather than "yyyy-mm-dd", soc,phishing rather than "comma-separated" — and every field holding an id now names the command that returns it: get_id_by_attribute for an assignee, board_list for a board, get_comments for a comment, get_issue for an attachment, get_link_types for a link type and for which issue belongs on which side of it. Fields that replace rather than append say so, since labels and components quietly drop whatever is left out. --- integrations/jira/manifest.yaml | 210 ++++++++++++++++---------------- 1 file changed, 105 insertions(+), 105 deletions(-) diff --git a/integrations/jira/manifest.yaml b/integrations/jira/manifest.yaml index a9bf1ee..bf21c3c 100644 --- a/integrations/jira/manifest.yaml +++ b/integrations/jira/manifest.yaml @@ -1,8 +1,8 @@ id: jira name: Jira -version: 1.0.1 +version: 1.0.2 description: "Atlassian Jira (REST API, Cloud and On-Prem/Data Center) — issue lifecycle (create/read/edit/delete, transitions, assign), comments, web + issue links, attachments (upload/download/delete), field and user lookups, agile boards/sprints/epics, plus issue ingestion (get_incidents) with an OCSF mapper. Basic (email + API token) or Personal Access Token authentication. Stdlib-only, no extra Python dependencies." -changelog: "1.0.1 — A personal access token silently outranked Basic credentials, so an unusable value left in pat turned every call into an opaque 401. Basic authentication now wins whenever username and api_key are both set, pat serves the rest, and a 401/403 names the method it used and whether the other was configured and ignored. Three configurations that cannot work are refused with the reason instead of being sent to Jira: no usable credential, the Cloud gateway URL without a cloud_id, and a cloud_id set against any other host. HTML error pages are condensed to their message rather than dumped whole, and a non-JSON body reports what answered and where. 1.0.0 — Initial release: JQL ingestion + query, full issue CRUD and transitions, comments, links, attachments, fields/users, and agile board/sprint/epic listing. Cloud (API v3, ADF bodies) and On-Prem (API v2) supported." +changelog: "1.0.2 — Command field help rewritten: every input now says what to type, in what format, and which command finds the value, instead of restating the field name. get_incidents explains that the fetch adds its own created >= watermark clause and ORDER BY, that the watermark is filled by the alert rule, and that a run does not page. Assignee, board, sprint, comment and attachment fields name the command that returns their id. 1.0.1 — A personal access token silently outranked Basic credentials, so an unusable value left in pat turned every call into an opaque 401. Basic authentication now wins whenever username and api_key are both set, pat serves the rest, and a 401/403 names the method it used and whether the other was configured and ignored. Three configurations that cannot work are refused with the reason instead of being sent to Jira: no usable credential, the Cloud gateway URL without a cloud_id, and a cloud_id set against any other host. HTML error pages are condensed to their message rather than dumped whole, and a non-JSON body reports what answered and where. 1.0.0 — Initial release: JQL ingestion + query, full issue CRUD and transitions, comments, links, attachments, fields/users, and agile board/sprint/epic listing. Cloud (API v3, ADF bodies) and On-Prem (API v2) supported." category: ticketing # Per-instance configuration. For Jira Cloud set cloud_id (found at @@ -41,9 +41,9 @@ commands: risk: read inputs_schema: properties: - query: { type: string, description: "JQL query (e.g. status != Done). Do not add an ORDER BY — the fetch adds one." } - after: { type: string, description: "Lower bound on created time, ISO8601 or epoch (incremental fetch watermark, applied as created >= ...)" } - max: { type: number, description: "Maximum issues to fetch (default 50)" } + query: { type: string, description: "JQL selecting the issues to ingest, e.g. project = SOC AND status != Done. Empty means every issue the account can read. The fetch appends its own created >= watermark clause and ORDER BY created ASC — do not write either yourself." } + after: { type: string, description: "Only issues created at or after this instant: ISO8601 like 2026-09-01T14:00:00Z, or an epoch in seconds or milliseconds. Leave empty — the alert rule fills it with the previous run's watermark." } + max: { type: number, description: "Issues per run, default 50. The fetch makes one call and does not page, so a run that would exceed this silently drops the rest: raise it, or shorten the rule's interval." } required: [] outputs_schema: { properties: {} } ingest: @@ -56,10 +56,10 @@ commands: risk: read inputs_schema: properties: - query: { type: string, description: "JQL query string" } - max_results: { type: number, description: "Maximum issues (default 50)" } - next_page_token: { type: string, description: "Token for the next page (Jira Cloud only)" } - start_at: { type: number, description: "Index of the first issue (On-Prem; Cloud uses next_page_token)" } + query: { type: string, description: "JQL, e.g. project = SOC AND created >= -7d ORDER BY created DESC. Unlike the ingestion fetch, the ordering here is yours to set." } + max_results: { type: number, description: "Issues per page, default 50." } + next_page_token: { type: string, description: "Cloud only. The nextPageToken from the previous response, to get the page after it. Empty for the first page." } + start_at: { type: number, description: "On-Prem only. Index of the first issue: 0, then 50, then 100… Cloud pages with next_page_token instead." } required: [query] outputs_schema: { properties: {} } - id: get_issue @@ -68,8 +68,8 @@ commands: risk: read inputs_schema: properties: - issue_id: { type: string, description: "Issue ID (issue_id or issue_key required)" } - issue_key: { type: string, description: "Issue key, e.g. PROJ-123 (issue_id or issue_key required)" } + issue_id: { type: string, description: "Numeric issue ID, e.g. 10042 — the id field the fetch returns. Give this or issue_key." } + issue_key: { type: string, description: "Issue key as shown in Jira, e.g. SOC-1423. Give this or issue_id." } required: [] outputs_schema: { properties: {} } @@ -79,19 +79,19 @@ commands: description: "Create a new issue. Provide project_key (or project_name), issue_type_name (or issue_type_id) and a summary." inputs_schema: properties: - project_key: { type: string, description: "Project key (project_key or project_name required)" } - project_name: { type: string, description: "Project name (resolved to a key; project_key or project_name required)" } - issue_type_name: { type: string, description: "Issue type name, e.g. Task, Bug (issue_type_name or issue_type_id required)" } - issue_type_id: { type: string, description: "Issue type ID (issue_type_name or issue_type_id required)" } - summary: { type: string, description: "Issue summary (required)" } - description: { type: string, description: "Issue description" } - priority: { type: string, description: "Priority name, e.g. High, Medium" } - labels: { type: string, description: "Comma-separated labels" } - components: { type: string, description: "Comma-separated component names (must already exist)" } - assignee_id: { type: string, description: "Assignee account ID (Cloud)" } - assignee: { type: string, description: "Assignee username (On-Prem)" } - due_date: { type: string, description: "Due date (yyyy-mm-dd)" } - fields_json: { type: string, description: "Raw fields JSON merged into the request (advanced; wins on key conflicts)" } + project_key: { type: string, description: "Project key — the prefix of its issue keys, so SOC for SOC-1423. Give this or project_name." } + project_name: { type: string, description: "Project display name, e.g. Security Operations. It must match exactly one project. Give this or project_key, which is the faster path." } + issue_type_name: { type: string, description: "Issue type as the target project names it, e.g. Task, Bug, Incident. Types are per-project. Give this or issue_type_id." } + issue_type_id: { type: string, description: "Numeric issue type ID, e.g. 10004. Give this or issue_type_name, which is usually easier to read." } + summary: { type: string, description: "The issue title, one line. This is what shows in every Jira list." } + description: { type: string, description: "Body text. Write plain text: it is converted to Atlassian Document Format on Cloud." } + priority: { type: string, description: "Priority name exactly as the project defines it, e.g. Highest, High, Medium. An unknown name is rejected." } + labels: { type: string, description: "Comma-separated, no space inside a label, e.g. soc,phishing. Unknown labels are created." } + components: { type: string, description: "Comma-separated, e.g. Network,Endpoint. Components must already exist in the project — Jira will not create them." } + assignee_id: { type: string, description: "Cloud: the account ID, e.g. 5b10a2844c20165700ede21g. get_id_by_attribute turns a name or email into one." } + assignee: { type: string, description: "On-Prem: the username, e.g. jdupont. get_id_by_attribute turns a name or email into one." } + due_date: { type: string, description: "Date only, yyyy-mm-dd, e.g. 2026-09-30." } + fields_json: { type: string, description: "Advanced. A JSON object merged into Jira's fields payload, for anything the boxes above do not cover, e.g. {\"customfield_10010\": \"SOC-2\"}. Its keys win over those boxes." } required: [summary] outputs_schema: { properties: {} } - id: edit_issue @@ -99,19 +99,19 @@ commands: description: "Edit an issue's fields, and/or move it with status/transition (see jira-list-transitions)." inputs_schema: properties: - issue_id: { type: string, description: "Issue ID (issue_id or issue_key required)" } - issue_key: { type: string, description: "Issue key (issue_id or issue_key required)" } - summary: { type: string, description: "New summary" } - description: { type: string, description: "New description" } - priority: { type: string, description: "Priority name" } - labels: { type: string, description: "Comma-separated labels (replaces existing)" } - components: { type: string, description: "Comma-separated component names (replaces existing)" } - assignee_id: { type: string, description: "Assignee account ID (Cloud)" } - assignee: { type: string, description: "Assignee username (On-Prem)" } - due_date: { type: string, description: "Due date (yyyy-mm-dd)" } - status: { type: string, description: "Target status name — transitions the issue (mutually exclusive with transition)" } - transition: { type: string, description: "Transition name to apply (mutually exclusive with status)" } - fields_json: { type: string, description: "Raw fields JSON merged into the request (advanced)" } + issue_id: { type: string, description: "Numeric issue ID, e.g. 10042 — the id field the fetch returns. Give this or issue_key." } + issue_key: { type: string, description: "Issue key as shown in Jira, e.g. SOC-1423. Give this or issue_id." } + summary: { type: string, description: "Replacement title. Leave empty to keep the current one." } + description: { type: string, description: "Replacement body, plain text. Replaces the whole description; it does not append." } + priority: { type: string, description: "Priority name exactly as the project defines it, e.g. Highest, High, Medium. An unknown name is rejected." } + labels: { type: string, description: "Comma-separated, e.g. soc,phishing. Replaces the whole list: a label left out is removed." } + components: { type: string, description: "Comma-separated, e.g. Network,Endpoint. Replaces the whole list, and each must already exist in the project." } + assignee_id: { type: string, description: "Cloud: the account ID, e.g. 5b10a2844c20165700ede21g. get_id_by_attribute turns a name or email into one." } + assignee: { type: string, description: "On-Prem: the username, e.g. jdupont. get_id_by_attribute turns a name or email into one." } + due_date: { type: string, description: "Date only, yyyy-mm-dd, e.g. 2026-09-30." } + status: { type: string, description: "Status you want the issue to end in, e.g. Done. The command finds a transition that leads there. Run list_transitions on the issue to see what it allows right now. Use this or transition, not both." } + transition: { type: string, description: "Transition to apply by name, e.g. Start Progress — one of those list_transitions returns for this issue. Use this or status, not both." } + fields_json: { type: string, description: "Advanced. A JSON object merged into Jira's fields payload, for anything the boxes above do not cover, e.g. {\"customfield_10010\": \"SOC-2\"}. Its keys win over those boxes." } required: [] outputs_schema: { properties: {} } - id: delete_issue @@ -119,8 +119,8 @@ commands: description: "Delete an issue (its sub-tasks are deleted too)." inputs_schema: properties: - issue_id: { type: string, description: "Issue ID (issue_id or issue_key required)" } - issue_key: { type: string, description: "Issue key (issue_id or issue_key required)" } + issue_id: { type: string, description: "Numeric issue ID, e.g. 10042 — the id field the fetch returns. Give this or issue_key." } + issue_key: { type: string, description: "Issue key as shown in Jira, e.g. SOC-1423. Give this or issue_id." } required: [] outputs_schema: { properties: {} } - id: assign_issue @@ -128,10 +128,10 @@ commands: description: "Assign an issue to a user (assignee_id for Cloud, assignee for On-Prem)." inputs_schema: properties: - issue_id: { type: string, description: "Issue ID (issue_id or issue_key required)" } - issue_key: { type: string, description: "Issue key (issue_id or issue_key required)" } - assignee_id: { type: string, description: "Assignee account ID (Cloud)" } - assignee: { type: string, description: "Assignee username (On-Prem)" } + issue_id: { type: string, description: "Numeric issue ID, e.g. 10042 — the id field the fetch returns. Give this or issue_key." } + issue_key: { type: string, description: "Issue key as shown in Jira, e.g. SOC-1423. Give this or issue_id." } + assignee_id: { type: string, description: "Cloud: the account ID, e.g. 5b10a2844c20165700ede21g. get_id_by_attribute turns a name or email into one." } + assignee: { type: string, description: "On-Prem: the username, e.g. jdupont. get_id_by_attribute turns a name or email into one." } required: [] outputs_schema: { properties: {} } - id: list_transitions @@ -140,8 +140,8 @@ commands: risk: read inputs_schema: properties: - issue_id: { type: string, description: "Issue ID (issue_id or issue_key required)" } - issue_key: { type: string, description: "Issue key (issue_id or issue_key required)" } + issue_id: { type: string, description: "Numeric issue ID, e.g. 10042 — the id field the fetch returns. Give this or issue_key." } + issue_key: { type: string, description: "Issue key as shown in Jira, e.g. SOC-1423. Give this or issue_id." } required: [] outputs_schema: { properties: {} } @@ -151,10 +151,10 @@ commands: description: "Add a comment to an issue." inputs_schema: properties: - issue_id: { type: string, description: "Issue ID (issue_id or issue_key required)" } - issue_key: { type: string, description: "Issue key (issue_id or issue_key required)" } - comment: { type: string, description: "Comment body" } - visibility: { type: string, description: "Restrict visibility to a role, e.g. Administrators" } + issue_id: { type: string, description: "Numeric issue ID, e.g. 10042 — the id field the fetch returns. Give this or issue_key." } + issue_key: { type: string, description: "Issue key as shown in Jira, e.g. SOC-1423. Give this or issue_id." } + comment: { type: string, description: "Comment text, plain — it is converted to Atlassian Document Format on Cloud." } + visibility: { type: string, description: "Project role the comment is limited to, by name, e.g. Administrators. Empty means anyone who can see the issue can read it." } required: [comment] outputs_schema: { properties: {} } - id: get_comments @@ -163,9 +163,9 @@ commands: risk: read inputs_schema: properties: - issue_id: { type: string, description: "Issue ID (issue_id or issue_key required)" } - issue_key: { type: string, description: "Issue key (issue_id or issue_key required)" } - limit: { type: number, description: "Maximum comments (default 50)" } + issue_id: { type: string, description: "Numeric issue ID, e.g. 10042 — the id field the fetch returns. Give this or issue_key." } + issue_key: { type: string, description: "Issue key as shown in Jira, e.g. SOC-1423. Give this or issue_id." } + limit: { type: number, description: "Comments to return, newest last, default 50." } required: [] outputs_schema: { properties: {} } - id: edit_comment @@ -173,11 +173,11 @@ commands: description: "Edit an existing comment on an issue." inputs_schema: properties: - issue_id: { type: string, description: "Issue ID (issue_id or issue_key required)" } - issue_key: { type: string, description: "Issue key (issue_id or issue_key required)" } - comment_id: { type: string, description: "Comment ID" } - comment: { type: string, description: "New comment body" } - visibility: { type: string, description: "Restrict visibility to a role" } + issue_id: { type: string, description: "Numeric issue ID, e.g. 10042 — the id field the fetch returns. Give this or issue_key." } + issue_key: { type: string, description: "Issue key as shown in Jira, e.g. SOC-1423. Give this or issue_id." } + comment_id: { type: string, description: "Numeric comment ID, e.g. 10231 — returned by get_comments." } + comment: { type: string, description: "Replacement text, plain. Replaces the comment entirely." } + visibility: { type: string, description: "Project role the comment is limited to, by name, e.g. Administrators. Empty means anyone who can see the issue can read it." } required: [comment_id, comment] outputs_schema: { properties: {} } - id: delete_comment @@ -185,9 +185,9 @@ commands: description: "Delete a comment from an issue." inputs_schema: properties: - issue_id: { type: string, description: "Issue ID (issue_id or issue_key required)" } - issue_key: { type: string, description: "Issue key (issue_id or issue_key required)" } - comment_id: { type: string, description: "Comment ID" } + issue_id: { type: string, description: "Numeric issue ID, e.g. 10042 — the id field the fetch returns. Give this or issue_key." } + issue_key: { type: string, description: "Issue key as shown in Jira, e.g. SOC-1423. Give this or issue_id." } + comment_id: { type: string, description: "Numeric comment ID, e.g. 10231 — returned by get_comments." } required: [comment_id] outputs_schema: { properties: {} } @@ -197,12 +197,12 @@ commands: description: "Add a remote web link (URL) to an issue." inputs_schema: properties: - issue_id: { type: string, description: "Issue ID (issue_id or issue_key required)" } - issue_key: { type: string, description: "Issue key (issue_id or issue_key required)" } - url: { type: string, description: "URL to link" } - title: { type: string, description: "Link title" } - summary: { type: string, description: "Link summary" } - relationship: { type: string, description: "Relationship to the issue, e.g. causes" } + issue_id: { type: string, description: "Numeric issue ID, e.g. 10042 — the id field the fetch returns. Give this or issue_key." } + issue_key: { type: string, description: "Issue key as shown in Jira, e.g. SOC-1423. Give this or issue_id." } + url: { type: string, description: "Full URL, scheme included, e.g. https://riposte.example.com/incidents/482." } + title: { type: string, description: "The clickable text on the issue, e.g. Riposte incident 482." } + summary: { type: string, description: "One line shown under the title. Optional." } + relationship: { type: string, description: "How the link reads on the issue, e.g. causes, relates to, documents. Free text; empty leaves Jira's default wording." } required: [url, title] outputs_schema: { properties: {} } - id: link_issues @@ -210,10 +210,10 @@ commands: description: "Create a link between two issues (see jira-get-link-types for link_type names)." inputs_schema: properties: - inward_issue: { type: string, description: "Inward issue key or ID" } - outward_issue: { type: string, description: "Outward issue key or ID" } - link_type: { type: string, description: "Link type name, e.g. Blocks, Duplicate" } - comment: { type: string, description: "Optional comment to add to the inward issue" } + inward_issue: { type: string, description: "One end of the link, key or numeric ID, e.g. SOC-1423. get_link_types gives each type's inward and outward wording, which tells you which issue goes on which side." } + outward_issue: { type: string, description: "The other end, key or numeric ID, e.g. SOC-1500. See get_link_types for which side is which." } + link_type: { type: string, description: "Link type by name, e.g. Blocks, Relates, Duplicate — exactly as get_link_types returns it." } + comment: { type: string, description: "Comment recorded alongside the link. Optional." } required: [inward_issue, outward_issue, link_type] outputs_schema: { properties: {} } - id: get_link_types @@ -231,10 +231,10 @@ commands: description: "Attach a file to an issue (content provided as base64)." inputs_schema: properties: - issue_id: { type: string, description: "Issue ID (issue_id or issue_key required)" } - issue_key: { type: string, description: "Issue key (issue_id or issue_key required)" } - file_name: { type: string, description: "Attachment file name" } - content_base64: { type: string, description: "File content, base64-encoded" } + issue_id: { type: string, description: "Numeric issue ID, e.g. 10042 — the id field the fetch returns. Give this or issue_key." } + issue_key: { type: string, description: "Issue key as shown in Jira, e.g. SOC-1423. Give this or issue_id." } + file_name: { type: string, description: "Name the file gets in Jira, e.g. report.pdf. Its extension decides the content type sent to Jira." } + content_base64: { type: string, description: "The file's bytes, base64-encoded. In a playbook this comes from an earlier block's file output rather than being typed." } required: [file_name, content_base64] outputs_schema: { properties: {} } - id: get_attachment @@ -243,7 +243,7 @@ commands: risk: read inputs_schema: properties: - attachment_id: { type: string, description: "Attachment ID (from jira-get-issue)" } + attachment_id: { type: string, description: "Numeric attachment ID, e.g. 10520 — get_issue lists them under attachments." } required: [attachment_id] outputs_schema: { properties: {} } - id: delete_attachment @@ -251,7 +251,7 @@ commands: description: "Delete an attachment by attachment ID." inputs_schema: properties: - attachment_id: { type: string, description: "Attachment ID" } + attachment_id: { type: string, description: "Numeric attachment ID, e.g. 10520 — get_issue lists them under attachments." } required: [attachment_id] outputs_schema: { properties: {} } @@ -262,8 +262,8 @@ commands: risk: read inputs_schema: properties: - limit: { type: number, description: "Maximum fields (default 50)" } - offset: { type: number, description: "Starting index (default 0)" } + limit: { type: number, description: "Fields per page, default 50." } + offset: { type: number, description: "Index of the first row, for paging: 0, then 50, then 100…" } required: [] outputs_schema: { properties: {} } - id: get_id_by_attribute @@ -272,8 +272,8 @@ commands: risk: read inputs_schema: properties: - attribute: { type: string, description: "Display name or email address to search for" } - max_results: { type: number, description: "Maximum candidates to consider (default 50)" } + attribute: { type: string, description: "A display name or an email, e.g. Jean Dupont or jean.dupont@example.com. Returns the account ID (Cloud) or username (On-Prem) that the assignee boxes expect." } + max_results: { type: number, description: "How many matches to weigh before giving up on an exact one, default 50." } required: [attribute] outputs_schema: { properties: {} } - id: get_user_info @@ -282,9 +282,9 @@ commands: risk: read inputs_schema: properties: - account_id: { type: string, description: "Account ID (Cloud)" } - key: { type: string, description: "User key (On-Prem)" } - username: { type: string, description: "Username (On-Prem)" } + account_id: { type: string, description: "Cloud: the account ID, e.g. 5b10a2844c20165700ede21g. One of the three is enough." } + key: { type: string, description: "On-Prem: the user key, e.g. JIRAUSER10100. One of the three is enough." } + username: { type: string, description: "On-Prem: the username, e.g. jdupont. One of the three is enough." } required: [] outputs_schema: { properties: {} } @@ -295,12 +295,12 @@ commands: risk: read inputs_schema: properties: - board_id: { type: string, description: "Return only this board" } - board_name: { type: string, description: "Filter by board name" } - project_key_id: { type: string, description: "Filter by project key or ID" } - type: { type: string, description: "Board type: scrum, kanban or simple" } - limit: { type: number, description: "Maximum boards (default 50)" } - offset: { type: number, description: "Starting index (default 0)" } + board_id: { type: string, description: "Numeric board ID to return on its own, e.g. 42. Empty lists them all." } + board_name: { type: string, description: "Keep only boards whose name contains this text, e.g. SOC." } + project_key_id: { type: string, description: "Keep only boards of one project, by key or numeric ID, e.g. SOC." } + type: { type: string, description: "One of scrum, kanban or simple. Empty returns every type." } + limit: { type: number, description: "Boards per page, default 50." } + offset: { type: number, description: "Index of the first row, for paging: 0, then 50, then 100…" } required: [] outputs_schema: { properties: {} } - id: board_issue_list @@ -309,10 +309,10 @@ commands: risk: read inputs_schema: properties: - board_id: { type: string, description: "Board ID" } - jql_query: { type: string, description: "JQL to filter the issues" } - limit: { type: number, description: "Maximum issues (default 50)" } - offset: { type: number, description: "Starting index (default 0)" } + board_id: { type: string, description: "Numeric board ID, e.g. 42 — returned by board_list." } + jql_query: { type: string, description: "Extra JQL narrowing the result, e.g. status = \"In Progress\" AND assignee IS EMPTY. Applied on top of the filter this list already has." } + limit: { type: number, description: "Issues per page, default 50." } + offset: { type: number, description: "Index of the first row, for paging: 0, then 50, then 100…" } required: [board_id] outputs_schema: { properties: {} } - id: board_sprint_list @@ -321,9 +321,9 @@ commands: risk: read inputs_schema: properties: - board_id: { type: string, description: "Board ID" } - limit: { type: number, description: "Maximum sprints (default 50)" } - offset: { type: number, description: "Starting index (default 0)" } + board_id: { type: string, description: "Numeric board ID, e.g. 42 — returned by board_list." } + limit: { type: number, description: "Sprints per page, default 50." } + offset: { type: number, description: "Index of the first row, for paging: 0, then 50, then 100…" } required: [board_id] outputs_schema: { properties: {} } - id: sprint_issue_list @@ -332,10 +332,10 @@ commands: risk: read inputs_schema: properties: - sprint_id: { type: string, description: "Sprint ID" } - jql_query: { type: string, description: "JQL to filter the issues" } - limit: { type: number, description: "Maximum issues (default 50)" } - offset: { type: number, description: "Starting index (default 0)" } + sprint_id: { type: string, description: "Numeric sprint ID, e.g. 137 — returned by board_sprint_list." } + jql_query: { type: string, description: "Extra JQL narrowing the result, e.g. status = \"In Progress\" AND assignee IS EMPTY. Applied on top of the filter this list already has." } + limit: { type: number, description: "Issues per page, default 50." } + offset: { type: number, description: "Index of the first row, for paging: 0, then 50, then 100…" } required: [sprint_id] outputs_schema: { properties: {} } - id: epic_issue_list @@ -344,11 +344,11 @@ commands: risk: read inputs_schema: properties: - epic_id: { type: string, description: "Epic ID (epic_id or epic_key required)" } - epic_key: { type: string, description: "Epic key (epic_id or epic_key required)" } - jql_query: { type: string, description: "JQL to filter the issues" } - limit: { type: number, description: "Maximum issues (default 50)" } - offset: { type: number, description: "Starting index (default 0)" } + epic_id: { type: string, description: "Numeric epic ID, e.g. 10310. Give this or epic_key." } + epic_key: { type: string, description: "Epic key, e.g. SOC-900. Give this or epic_id." } + jql_query: { type: string, description: "Extra JQL narrowing the result, e.g. status = \"In Progress\" AND assignee IS EMPTY. Applied on top of the filter this list already has." } + limit: { type: number, description: "Issues per page, default 50." } + offset: { type: number, description: "Index of the first row, for paging: 0, then 50, then 100…" } required: [] outputs_schema: { properties: {} }