jira-alerts-mcp

Overview Schema Source Related Servers Discussions Admin

Edit a note on a JSM alert

jsm_update_alert_note

DestructiveIdempotent

Replace the full text of an existing JSM alert note to correct errors like wrong hostnames or stale conclusions. Read it first if appending; add a new note for updates.

Instructions

Replace the text of an existing note on a JSM alert.

Use it to correct a note you just wrote — a wrong hostname, a stale conclusion. Prefer adding a new note with jsm_add_alert_note for anything that reads as a development rather than a correction: the timeline is the record of what responders knew and when, and editing history out of it costs more than an extra line.

Args:

alert_id (string): the full alert id (not the tinyId)
note_id (string): id of the note to edit, from jsm_list_alert_notes
note (string): the replacement text

Returns the updated note: { "alert_id", "note_id", "note", "owner", "createdAt", "updatedAt" }

Unlike every other alert write, this one is synchronous. It answers with the note itself, so there is no requestId and nothing to verify with jsm_get_request_status.

This replaces the note's whole text. There is no append. Read the note first if you mean to add to it.

Examples:

"Fix my last note, the host is db-3 not db-2" -> jsm_list_alert_notes, take the id, then update with the corrected text

Constraints and errors:

HTTP 404 means the note id does not belong to that alert. Note ids come from jsm_list_alert_notes, not from the note's text.

Input Schema

TableJSON Schema

Name	Required	Description
`note`	Yes	Note text to record on the alert's activity timeline.
`note_id`	Yes	Id of the note to edit, from jsm_list_alert_notes. Not the note's text.
`alert_id`	Yes	Full alert id, e.g. '9b251e07-73c9-4907-9996-8cb53a6a20d0-1704440650350'. This is NOT the short tinyId shown in the JSM UI — get the full id from jsm_list_alerts first.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`id`	No
`note`	No
`owner`	No
`note_id`	No
`alert_id`	Yes
`createdAt`	No
`updatedAt`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv2.1.0Sep 12, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Addedv2.0.0Sep 8, 2026

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds real value beyond that: it is synchronous unlike every other alert write, returns the note itself so there is no requestId to verify with jsm_get_request_status, it replaces the whole text with no append, and 404 signals a note/alert mismatch. That is strong disclosure, though the destructive/idempotent semantics themselves are left implicit in 'replaces the note's whole text'.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the purpose and the correction-vs-development guidance, then args, returns, sync note, and constraints. Well organized, but the Args block duplicates schema descriptions near-verbatim and the Returns block repeats the output schema, so a little space is not earning its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers everything an agent needs: what it does, when to use it versus the alternative, that it is synchronous with no requestId follow-up, whole-text replacement with no append, and the 404 failure meaning. An output schema exists, yet the description still closes the verification loop with jsm_get_request_status, which is exactly the kind of cross-tool context that matters here.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all three params (including the full-alert-id-not-tinyId warning and note_id provenance). The Args section largely restates the schema, adding only that note is the 'replacement' text — a marginal increment over the schema's 'Note text to record'. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — 'Replace the text of an existing note on a JSM alert' — and immediately distinguishes itself from its nearest siblings (jsm_add_alert_note, jsm_delete_alert_note). An agent can tell what this does and what it is not without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use it ('correct a note you just wrote') versus the alternative ('prefer adding a new note with jsm_add_alert_note for anything that reads as a development'), with the reasoning that the timeline is the record of what responders knew. It even gives a worked example routing through jsm_list_alert_notes first.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.