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

The annotations already declare idempotency and non-read-only behavior, but the description adds valuable context by explaining escalation suppression, the no-op on already-acknowledged alerts, and especially the asynchronous nature: 'The response confirms the request was accepted, not that the alert changed.' This goes beyond the annotations and helps set agent expectations.

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

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

The description is largely well-structured and front-loaded, with the core behavior in the first sentence and clear sections for Args, Returns, and async behavior. It loses a point because the example's mention of 'note' is extraneous and inconsistent with the schema, and the Args section partially duplicates the schema's existing parameter description.

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

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

For a single-parameter tool, the description covers the key operator needs: what the action does, how it differs from closing, its idempotency, and how to verify success via jsm_get_request_status. The misleading 'note' in the example is the main completeness gap, and it could have also explicitly pointed to jsm_list_alerts for obtaining the full alert_id as the schema does.

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

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

The schema already fully documents alert_id with an example and the warning not to use the tinyId, so the description adds little beyond repeating that. The example then introduces a 'note="Investigating, RVS"' argument that is not part of the input schema and would violate additionalProperties=false, potentially misleading an agent into passing an invalid parameter.

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

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

The description uses a specific verb 'Acknowledge' and resource 'open JSM alert', and clearly states the effect: 'stopping further escalation notifications'. It also distinguishes itself from jsm_close_alert by stating 'It does not resolve the alert', which separates it from a key sibling tool.

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

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

The description explicitly states when to use it: 'Acknowledging signals that a human has picked the alert up.' It also names an alternative with the condition: 'use jsm_close_alert for that' when resolving. The no-op note for already-acknowledged alerts clarifies expected behavior in an edge case.

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

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

The description thoroughly discloses behavior beyond the annotations: the operation is asynchronous, it merges by key, untouched keys are preserved, and existing keys are overwritten without warning. This directly supports the destructiveHint=true annotation and adds material context the agent needs before calling.

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

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

The description is detailed but every sentence earns its place: purpose, distinction from notes, args, return shape, async warning, overwrite warning, and a concrete example. It is well-structured and front-loads the core behavior before edge-case warnings.

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

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

For a two-parameter mutation tool with an output schema, the description is complete: it covers async verification, return fields, destructive merge semantics, how to retrieve the full alert id, and provides a worked example. Nothing essential is left for the agent to guess.

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

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

Schema coverage is 100%, so the schema already documents both parameters and their types. The description adds useful context on top: full alert id vs tinyId, allowed value types, a concrete example, and the effect of merging/overwriting. This goes beyond the schema baseline without being redundant.

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

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

The description clearly states the tool attaches key/value context to a JSM alert and can overwrite existing properties. It also distinguishes extra properties from notes, making it easy to tell apart from sibling tools like jsm_add_alert_note.

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

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

The description explains when this tool is appropriate: for structured, programmatically readable context, unlike prose notes. It also gives explicit guidance on prerequisites and follow-up: read the alert first with jsm_get_alert to avoid clobbering keys, and verify completion with jsm_get_request_status because the action is asynchronous.

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

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

The description discloses the asynchronous behavior with a warning to verify via jsm_get_request_status, and notes the actor defaults to the credential owner. These traits are not captured in the annotations, which only cover readOnly/destructive hints. The 'without changing its state' clarification is valuable and consistent with the annotations.

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

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

The description is well structured with logical sections: usage, args, returns, async warning, and an example. The core purpose is front-loaded, and each section serves a purpose. The inclusion of the unsupported user/source params adds a minor structural blemish but overall it remains concise enough.

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

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

The description includes return shape, async warning, and a concrete example, plus strong guidance on alert_id. However, the contradiction between the documented optional args and the actual schema means an agent following the description could fail at runtime, which prevents it from being fully complete.

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

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

The input schema already documents alert_id and note at 100% coverage, so the description adds little for those parameters. However, the Args section mentions optional 'user' and 'source' parameters that are not defined in the schema, and additionalProperties is false, meaning they would be rejected. This misleading extra information actively harms parameter understanding.

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

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

The description states a specific verb ('Append a note') and resource ('a JSM alert's activity timeline') and immediately clarifies the action does not change alert state. This clearly differentiates it from sibling tools like jsm_update_alert_note, jsm_add_alert_tags, and jsm_acknowledge_alert.

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

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

The description gives explicit use cases: 'record triage findings, link a runbook or dashboard, or leave context for the next responder' and states what it does not do: 'does not acknowledge, close, or reassign the alert.' It does not explicitly name sibling alternatives for those excluded actions, but the guidance is still clear and actionable.

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

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

Goes well beyond the annotations by disclosing that the action is asynchronous and must be verified via jsm_get_request_status with the returned requestId, that responders are additive, and the specific failure mode (HTTP 422 / failed status means responder_id doesn't exist or has the wrong type). No contradiction with idempotentHint=true or readOnlyHint=false.

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

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

Well-structured and front-loaded with the core purpose, followed by labeled sections for Args, Returns, async warning, example, and error handling. The Args section partially duplicates the fully-documented schema, which is mild redundancy, but every other sentence earns its place and the headers make scanning efficient.

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

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

For a mutating, asynchronous tool this is as complete as it gets: it documents the return shape (requestId enabling follow-up), names the follow-up tool, explains the failure mode, provides a usage example, and tells where to source valid IDs. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds genuine value beyond the schema: the example maps natural-language intent ('Page the database team on this') to responder_type, and the error-handling section clarifies what a wrong responder_id/type produces behaviorally. The Args block itself is largely redundant with the schema, limiting the additional credit.

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

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

The description uses a specific verb-resource pair ('Add a responder... to an existing JSM alert') and names the four entity types the responder can be. The additive scoping note ('does not remove the existing ones') helps distinguish it from assignment-style siblings, and the stated outcome (notified and accountable) makes the effect concrete.

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

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

It gives a clear when-to-use signal: 'pull in another team once triage shows the alert belongs elsewhere.' It also routes the agent to jsm_get_request_status for async verification and jsm_list_schedules for finding IDs. It does not explicitly name alternatives to avoid (e.g., jsm_assign_alert), but the additive-vs-replace distinction serves that role implicitly.

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

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

Annotations only signal mutation and idempotency; the description goes further by disclosing the asynchronous request/response pattern, requiring follow-up via jsm_get_request_status with the returned requestId, and warning that tags are case-sensitive. This is meaningful behavioral context far beyond the annotations and no contradiction exists.

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

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

The description is front-loaded with the core action, uses clear section labels (Args, Returns, IMPORTANT), and every paragraph earns its place — including the illustrative tagging example. The motivational sentence about grouping is slightly expansive but supports usage decisions without bloating the definition.

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

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

With a rich output schema and annotations already covering mutation/idempotency, the description supplies the missing operational details: asynchronous behavior, verification step, error-prone id confusion, and case-sensitivity. An agent has everything needed to select and invoke this tool correctly.

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

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

The input schema already documents both parameters at 100% coverage, and the description still adds value: it emphasizes using the full alert_id rather than tinyId, gives a concrete example, and explains why casing must match existing tags. The Args list largely repeats the schema, but the prose around additive and case-sensitive behavior deepens the semantics.

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

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

The first sentence states a specific action ('Add one or more tags to a JSM alert') and the additive semantics ('existing ones stay') clarify exactly what the tool does. This cleanly distinguishes it from sibling operations such as removing tags because add is explicitly non-destructive.

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

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

The description explains when tagging is useful — grouping/filtering with jsm_list_alerts (tag:"db") and organizing incident-related alerts — and advises aligning casing with existing team conventions. It does not explicitly state when to prefer a sibling like jsm_remove_alert_tags, so there is no direct alternative exclusion, but the intended context is clear.

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

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

The description adds important behavioral context beyond the annotations: the action is asynchronous, a requestId is returned, and callers must verify completion with jsm_get_request_status. It also discloses likely error causes (HTTP 422 / failed status = bad account id or no JSM Operations access), which the annotations do not cover.

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

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

The description is well organized with clear sections for args, returns, async behavior, account_id caveats, examples, and errors. Key information is front-loaded, and even the longer portions earn their place by preventing common failure modes.

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

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

Given the tool's mutation, asynchronous behavior, and the need for valid account ids, the description covers everything an agent needs: what it does, when to use it, parameter nuances, return shape, verification step, and error interpretation. The output schema and sibling context further fill any remaining gaps.

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

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

Even though the input schema already documents both parameters well, the description adds practical meaning: alert_id must be the full id rather than tinyId, and account_id is not an email or display name. It also tells the agent where to find valid account ids (jsm_get_on_call, jsm_get_alert) and gives a concrete id format.

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

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

The description opens with a specific action and outcome: 'Make one person the owner of a JSM alert, so it is clear who is working it.' It also distinguishes this tool from jsm_add_alert_responder and routing rules, so an agent can tell it apart from siblings without guessing.

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

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

Explicit guidance is given: use this when triage has decided whose problem it is, and for a single alert rather than a class of alerts. It names the alternative (jsm_add_alert_responder) and explains when that alternative is appropriate, plus notes that routing rules handle classes of alerts.

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

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

The description discloses important non-obvious behaviors beyond annotations: the action is asynchronous, requires verification via jsm_get_request_status, cannot be reopened, and recurring conditions create a new/fresh alert rather than reviving the record. These traits align with destructiveHint=true and idempotentHint=true without contradicting them.

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

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

The description is well-structured with short labeled sections and front-loaded purpose. It is longer than necessary, however, because the Args and Returns sections largely duplicate the schema and output schema, and the example introduces an unsupported parameter. Overall it remains scannable and purposeful.

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

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

The description is rich: it covers async behavior, verification, one-way semantics, when to avoid, and the exact return shape. It is incomplete only because of the phantom 'note' parameter in the example, which could cause an agent to construct an invalid request, and because it does not clarify what happens when attempting to close an already-closed alert.

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

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

Schema coverage is 100%, so the baseline is 3, but the description introduces a misleading 'note' argument in the example ('note="Resolved by rollback of build 4412"') that is not present in the input schema and would be rejected by additionalProperties:false. The Args section merely restates what the schema already says about alert_id, adding no genuine semantic value beyond the schema.

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

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

The description opens with a specific verb and resource: 'Close a JSM alert, marking it resolved and ending all notifications for it.' It also clarifies the lifecycle role ('Closing is how an alert leaves the open queue') and implicitly differentiates from acknowledge/delete siblings by noting it is one-way and not for active work.

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

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

Explicit when-to-use guidance is provided: 'Prefer jsm_acknowledge_alert while work is still in progress' and 'Don't use when: the alert is still being worked — acknowledge instead.' It also warns the operation is effectively one-way, so the agent understands the consequence before invoking.

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

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

The description goes far beyond the annotations: it discloses that the alert 'pages people,' that the API is asynchronous with a 200 rather than 202 status, that the response contains no alert id, and that alias reuse on an open alert silently increments instead of creating. It also documents required auth scopes and responder routing bypass, all beyond the structured annotations.

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

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

The description is long but exceptionally well-organized with Args, Returns, IMPORTANT, Alias, Examples, and Constraints sections. It front-loads the most important warning ('This pages people') and each sentence carries distinct value, making the length appropriate for the tool's complexity.

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

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

The description covers purpose, usage criteria, return shape, async behavior, how to obtain the real alert id, alias semantics, concrete examples, required permissions, and likely error causes. The output schema doesn't provide this contextual information, so the description fully compensates.

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

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

Even with 100% schema coverage, the description adds substantial meaning: message is the only required field, alias is the de-duplication key with safe-retry versus no-op consequences, responders bypass routing rules, priority omission defers to routing, and there is deliberately no 'user' parameter. These semantics are critical for correct invocation and are not obvious from the schema alone.

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

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

The description states a specific action and resource ('Create a new alert in Jira Service Management Operations') and immediately distinguishes the tool from siblings: 'not to leave a note, which is jsm_add_alert_note, and not to record something nobody needs to act on.' It also notes the absence of a 'user' argument compared to other write tools, removing ambiguity.

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

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

Explicitly prescribes when to use it: 'Create one when a human wants an incident tracked and escalated,' and names the alternative jsm_add_alert_note for notes. It also explains when to use alias-based retries and how to follow up via jsm_get_request_status or jsm_get_alert.

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

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

Annotations already indicate destructive and non-read-only behavior, but the description adds substantial context: deletion has no undo, destroys notes/activity/attachments/timing, is asynchronous and requires verification via jsm_get_request_status, and needs a separate delete:ops-alert grant. This fully discloses the behavioral weight of the operation beyond what the annotations alone convey.

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

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

The description is longer than average, but every sentence is load-bearing: the most important warning is front-loaded, the destructive implications are explained, the narrow justifications are named, async behavior is highlighted, and permission constraints are included. The use of bold, section headers, and bullet-like structure makes the length navigable rather than bloated.

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

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

For a destructive asynchronous mutation tool with one parameter and an output schema, the description covers every essential decision factor: what is destroyed, when deletion is justified, when it is not, how to confirm user consent, how to verify completion, and what permission is required. The return shape is described and the output schema exists, so no critical context is missing.

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

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

Schema description coverage is 100%, and the schema already explains that alert_id must be the full alert id rather than the tinyId, provides an example, and directs the agent to jsm_list_alerts. The description's Args line repeats 'full alert id (not the tinyId)' but adds no new parameter-level semantics beyond the schema. The pre-call instruction to read the alert is usage guidance, not parameter semantics.

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

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

The description states a specific action: permanently delete a JSM alert and everything recorded on it. It explicitly distinguishes itself from jsm_close_alert by explaining what is lost in deletion versus what is preserved when closing. This makes the tool's purpose unmistakable and clearly differentiated from its siblings.

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

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

The description gives unusually explicit when-to-use and when-not-to-use guidance: it names the narrow cases that justify deletion, warns it is 'almost never the right tool,' and enumerates forbidden uses such as tidying up, clearing queues, or looping over search results. It also requires reading the alert back and obtaining explicit user consent before calling.

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

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

Annotations already mark this as destructive and non-readonly, but the description adds substantial behavior beyond that: there is no undo, no confirmation step at the API, the operation is synchronous, the API returns 204 with no body, no requestId is available, and a separate delete:ops-alert grant is required. This is exactly the kind of context an agent needs before calling a destructive tool.

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

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

The description is longer than average, but it is well-structured into purpose, args, returns, safety warning, synchronous behavior, and permissions. Every section carries important information for a destructive operation, though some statements like 'There is no undo' and 'The note is gone the moment this returns' are mildly redundant.

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

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

For a destructive mutation with sensitive side effects, the description covers return shape, error/permission context, synchronous behavior, and user-confirmation expectations. Nothing needed to safely call this tool is missing, especially given the annotations also flag destructiveness.

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

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

The schema already has 100% coverage with clear descriptions for both parameters, so the baseline is 3. The description adds useful emphasis that alert_id must be the full id and not the tinyId, and that note_id should come from jsm_list_alert_notes, which reinforces the correct source without inventing new semantics.

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

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

The description states a specific action and resource: permanently remove a note from a JSM alert's timeline. It also distinguishes itself from the sibling jsm_update_alert_note by explicitly saying that correction is not this tool's purpose.

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

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

The description gives explicit when-to-use guidance: only for notes that should never have been written, such as pasted credentials or personal information. It also gives a clear when-not-to-use directive by naming jsm_update_alert_note as the alternative for notes that merely turned out to be wrong, plus a strong instruction to confirm with the user and quote the note before deletion.

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

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

The description discloses the side effect of paging people out of band, the async request/response pattern, and the need for user confirmation. It also explains error behavior for invalid escalation IDs. These details go beyond the annotations and accurately represent the action's behavior.

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

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

The description is somewhat repetitive, particularly around paging people and distinguishing escalation IDs from team/schedule IDs, but the extra details serve important disambiguation and safety purposes. Overall it is well-organized with clear sections for arguments, returns, constraints, and examples.

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

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

The description includes the return shape, async verification instructions, common error causes with HTTP 422, and examples. It provides enough context for an agent to decide when to use the tool and what to expect, complementing the input schema and annotations effectively.

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

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

Both parameters are fully described in the schema, with additional context in the description. The alert_id description clarifies that the full ID is required, not the tinyId, and the escalation_id description distinguishes escalation policies from team and schedule IDs. The description includes a concrete example for alert_id.

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

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

The description clearly states the action: 'Push a JSM alert into an escalation policy immediately' and distinguishes it from sibling alert actions by specifying that it pages the next people in the policy now. The title and description align on the verb and resource.

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

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

It gives a concrete condition for use: 'when an alert is not getting picked up and waiting out the escalation timer is not acceptable.' It also explicitly instructs to confirm with the user before escalating and notes the async nature of the action, providing clear usage guidance.

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

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

Goes well beyond the annotations (destructiveHint=true, openWorldHint=true, idempotentHint=false): it discloses async execution with an explicit verification step, the silent no-op on unrecognised names with the consequence that 'a successful receipt is not evidence that anything ran', and the fact that the server cannot see what the action does. The production-impact framing ('a request to run somebody's automation against production') gives the agent a concrete risk model beyond the boolean hints.

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

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

Long but dense with unique safety-critical content: the guessing warning, async verification, and per-integration constraint all earn their place and the core purpose is front-loaded in the first sentence. Minor deduction because the 'Args:' and 'Returns:' lines duplicate information already present in the input schema and output schema.

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

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

The output schema covers return values and annotations cover the safety profile, so the description's remaining job is the open-world danger, which it handles fully. Every identified failure mode — guessing names, silent no-ops, cross-integration mismatches, async receipt without execution — is addressed with an actionable instruction.

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

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

Schema coverage is 100% and both schema descriptions are already rich: alert_id explains the tinyId distinction and how to obtain the full id, and action_name explains the not-free-text caveat. The description's Args section largely restates this same information, adding no new parameter-level semantics, so the baseline 3 applies.

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

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

Opens with a specific verb+resource: 'Run one of your organisation's own custom alert actions', concretely illustrated with examples like 'Restart service' or 'Roll back deploy'. This clearly separates it from the sibling built-in operations (acknowledge, snooze, assign, escalate, close) by scoping it to org-configured automation rather than platform features.

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

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

Provides strong contextual guidance: the agent is told the action name must match a real configured action, is explicitly instructed to 'Ask the user which action they mean, and confirm before running it', and is routed to the follow-up tool jsm_get_request_status for async verification. It also notes per-integration name scoping, though it does not explicitly enumerate which sibling alternatives to prefer instead.

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

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

Annotations already mark the tool as read-only and idempotent, and the description adds substantial behavioral context: it documents that responder ids are resolved to names when credentials allow, that a 404 usually means a tinyId was passed, and that alias lookup only works for open alerts. This goes well beyond the structured annotations.

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

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

The description is long but every section earns its place: a scoped purpose statement, usage guidance, parameter summary, return expectations, examples, and error handling. It is front-loaded with the most important information and structured with clear labels, making it easy to scan.

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

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

For a tool with three parameters, a rich return shape, and potential error traps, the description covers everything an agent needs: when to use it, what parameters mean, what the response contains, how to handle the likely 404, and two concrete example queries. The output schema further covers return fields, so nothing critical is missing.

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

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

Schema coverage is 100%, so the schema already documents all three parameters thoroughly. The description adds extra value with worked examples for id-based and alias-based lookups, clarifies the tinyId limitation, and explains the difference between identifier and alias endpoints, which helps the agent choose values correctly.

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

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

The description uses a specific verb ('Retrieve') with a clear resource ('a single JSM alert') and enumerates the included fields (description, custom details/extraProperties, responders, tags, dedupe count). It explicitly contrasts the output with the thinner jsm_list_alerts record, so an agent can distinguish it from sibling tools.

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

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

The description explicitly states when to use this tool ('after jsm_list_alerts when you need the payload an integration attached') and when the list endpoint is sufficient. Error handling notes clarify that tinyIds are rejected and aliases only resolve against open alerts, guiding correct invocation and recovery.

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

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

The description adds substantial behavioral detail beyond the readOnly/idempotent annotations: it explains that responders are Atlassian account IDs that the tool resolves to names, that missing Jira user scope still returns IDs with a note, and that HTTP 401 indicates a specific scope gap rather than bad credentials. This gives the agent a clear failure-mode interpretation.

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

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

The description is well-structured with clear sections for purpose, usage, arguments, return value, examples, and error handling. Every section adds information an agent needs, and the most critical purpose statement is front-loaded.

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

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

The description covers the full calling context: parameters, return shape, scope requirements, error semantics, and example phrasing. Combined with the annotations and output schema, nothing essential is missing for correct selection and invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description enriches parameter meaning with illustrative examples such as 'Who is on after the shift that covers Thursday?' mapping to date="2026-08-27T12:00:00Z" and clarifying that 'next' is computed relative to the date. These examples help the agent map natural-language intent to parameter values.

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

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

The description opens with a precise verb and resource: 'Return the responders who take over the next shift on a JSM schedule, and when that shift begins.' This clearly distinguishes it from sibling tools like jsm_get_on_call and jsm_get_schedule_timeline by emphasizing the 'next shift' and its start time.

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

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

It explicitly states when to use the tool: 'Use this for handover messages and for deciding whether an alert can wait for the next rotation.' It also gives concrete examples and suggests combining with jsm_list_alerts, though it does not explicitly state when not to use it or name alternatives like jsm_get_on_call.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context beyond this: it resolves Atlassian account ids to display names, identifies 'participants' as the field to read, explains that an empty result is a valid answer rather than a failure, and details 401/404 semantics including the specific missing OAuth scope.

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

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

The description is long but tightly organized into Args, Returns, Examples, and Error handling sections, with every sentence earning its place. The most important usage distinction is front-loaded, and the error handling section preempts common failure modes an agent would otherwise have to discover by trial.

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

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

Given the tool's complexity, the description covers everything an agent needs: parameter semantics, return shape, the key field to read, example invocations, and failure interpretation. The presence of an output schema plus this rich narrative makes the tool fully self-contained for correct selection and invocation.

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

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

Although schema coverage is 100%, the description adds meaning beyond the schema: it explains when schedule_id is a name versus an id, gives concrete ISO 8601 examples for the date argument, clarifies the practical difference between flat=true and flat=false, and maps natural-language example queries to actual parameter settings. This is genuinely additive rather than redundant.

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

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

The description opens with a specific verb and resource: 'Return the responders currently on-call for a JSM schedule', and immediately clarifies that it can also evaluate a past or future timestamp. It distinguishes itself from siblings by framing the tool as 'who do I wake up?' and 'who was on-call when this incident started?', which separates it from jsm_get_next_on_call and jsm_list_schedules.

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

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

The description explicitly states what this tool is for, including the post-incident review use case with the 'date' argument. It gives concrete example prompts mapped to parameter values, and in error handling it directs the agent to jsm_list_schedules for 404s, providing clear routing to an alternative tool.

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

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

Annotations already indicate readOnly/idempotent/non-destructive, and the description adds important async behavior: writes return immediately and do not apply synchronously, so this endpoint is necessary to confirm the action landed. The 404-usually-queued error note is additional behavioral context beyond what annotations provide.

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

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

The description is front-loaded with the core purpose and then efficiently covers rationale, arguments, return shape, example, and error handling in clearly labeled sections. No sentence is filler; the length is justified by the non-obvious async behavior.

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

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

For a status-check tool with simple parameters, annotations covering safety, an output shape, a runnable example, and retry guidance, the description fully equips an agent to select and invoke the tool correctly. The async verification context closes the main completeness gap.

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

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

Input schema coverage is 100%, so the schema already documents both parameters. The description still adds value by showing a concrete request_id example and giving the exact flow (write tool returns requestId -> pass as request_id), though its Args section largely restates the schema's parameter descriptions.

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

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

The description opens with a specific verb and object: 'Check whether an asynchronous alert action actually succeeded.' It also explains the requestId verification mechanism and distinguishes this tool from immediately re-reading the alert, so an agent can tell it apart from jsm_get_alert and jsm_list_alerts without inspecting the schema.

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

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

It explicitly states when to use this tool: after any JSM alert write returns a requestId, and it tells the agent not to use immediate re-reads as verification. It also provides an example ('After jsm_acknowledge_alert returns requestId...') and error-handling guidance for the queued case, so usage context is unambiguous.

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

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

Annotations already mark the tool as read-only and idempotent, and the description adds substantial behavior beyond that: the approximate three-week window, responder resolution to names, interpretation of shift types like 'override' and 'historical', and specific HTTP 401 troubleshooting context. This gives the agent useful operational expectations.

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

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

The description is long but well-structured and every section earns its place: purpose, usage guidance, parameters, return shape, examples, and error handling. The most important scoping statement is front-loaded, making it easy for an agent to quickly decide whether to use this tool.

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

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

For a read-only scheduling tool with a rich output schema, the description covers the key gaps an agent would face: what the window covers, what shift types mean, how responders appear, and how to diagnose auth failures. Nothing essential is missing for correct selection and invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's Args section largely mirrors the schema rather than adding new parameter-level semantics, though the examples provide some usage nuance. Overall, the schema already carries the parameter documentation burden.

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

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

The description names a specific verb and resource: returning on-call rotation periods and shift boundaries for a JSM schedule. It further differentiates itself from jsm_get_on_call by explicitly framing this as the tool for boundary questions rather than single-moment queries.

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

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

It explicitly states when to use this tool ('questions about shift boundaries rather than a single moment'), gives concrete example queries, and contrasts it with jsm_get_on_call. It even explains the cost tradeoff of using schedule_identifier_type='name', giving clear selection guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: logs are system-generated, sorted newest-first by default, and opaque cursors are used for pagination. This is useful beyond what annotations provide.

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

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

The description is well-structured with a clear opening sentence, an explicit use-case section, an Args list, a Returns sample, and examples. Every section earns its place and the most important scoping information ('system-generated' vs human comments) is front-loaded.

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

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

With five parameters, a clear output schema, annotations, and sibling context, the description covers everything an agent needs: what the tool does, when to use it, which sibling to use instead, parameter semantics, response shape, and worked examples. No critical information is missing.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds extra value by explaining that alert_id is the full id and not the tinyId, suggesting how to obtain it via jsm_list_alerts, and providing concrete examples that map use cases to parameter choices. This goes beyond simple schema repetition.

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

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

The description states a specific verb and resource: 'List the system activity log for a JSM alert', and enumerates the content covered: 'every state transition, notification, escalation and automated action'. It also distinguishes itself from jsm_list_alert_notes, so an agent can tell it apart from sibling tools.

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

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

The description gives explicit when-to-use guidance with example queries like "why did nobody get paged?" and "when was this escalated and to whom?", and explicitly says human comments live in jsm_list_alert_notes instead. This clear exclusion and alternative make the usage boundary unambiguous.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior, and the description adds meaningful context beyond that: default ordering, opaque cursor pagination rather than numeric offsets, the distinction between human notes and integration updates, and response format behavior. This is rich, accurate behavioral disclosure.

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

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

The description is well structured with clear sections: overview, usage rationale, arguments, return shape, examples, and a pagination caveat. Every sentence contributes practical information, and the most decision-relevant detail (what this tool returns and when to use it) is front-loaded.

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

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

Given the output schema and rich annotations, the description is fully adequate for an agent to select and invoke the tool correctly. It covers ordering, pagination, the full alert id requirement, response formats, and example usage. Nothing an agent needs for correct invocation is missing.

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

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

Input schema coverage is 100%, so the baseline is 3. The description adds value by emphasizing that alert_id is the full id and not tinyId, explaining the opaque cursor semantics again, and giving example parameter combinations for natural-language use cases. This goes beyond merely restating schema field descriptions.

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

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

The description states a specific verb ('List'), a specific resource ('notes on a JSM alert's activity timeline'), and the default ordering ('newest first'). It clearly identifies these as human comments, distinguishing them from related alert actions and from the sibling log tool.

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

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

The description gives actionable guidance: 'Read them before acting on an alert so you don't repeat work someone already did.' It also provides example queries showing when to use different limits and orderings. It does not explicitly compare to siblings like jsm_list_alert_logs, but the context is clear enough.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior, and the description reinforces this. It adds genuinely useful constraints beyond annotations: offset + limit must stay below 20000, malformed queries return HTTP 400, field names are case-sensitive, and the response includes pagination details.

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

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

The description is long but well-structured with sections for arguments, return values, examples, and constraints. Some content duplicates the schema and output schema, but the examples and error constraints earn their place for an entry-point tool.

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

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

The description is self-sufficient: it explains what the tool does, how to use every parameter, what the response looks like, and which failure modes to expect. With the output schema and detailed examples, an agent has everything needed to call the tool correctly.

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

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

The input schema covers all parameters at 100%, so the baseline is already strong. The description adds value with query examples, field:value syntax guidance, default values restated in context, and practical constraints like the 20000-record paging limit that are not fully expressed in the schema.

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

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

The description clearly identifies the tool as the search/list entry point for Jira Service Management alerts, with a specific verb and resource. It differentiates itself by noting it resolves tinyId to the full alert id required by other alert tools and explicitly states it is read-only, which separates it from sibling mutation tools.

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

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

The description gives strong context: it is the entry point for almost every alert workflow, useful for finding open/unacknowledged alerts, filtering by priority/team/tag, and resolving tinyIds. It does not explicitly name sibling alternatives like jsm_get_alert for single-alert lookups, but the read-only statement and entry-point framing make the intended usage clear.

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

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

Goes well beyond the readOnlyHint/idempotentHint annotations by disclosing that it makes no API call, needs no credentials, works even when the token is missing or wrong, and explaining read-only mode's effect on toolset registration. The unverified field semantics and the JSM_TOOLSETS restart requirement add important operational context.

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

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

The description is long but front-loaded with purpose, then flows into usage, return shape, and examples. The inline JSON return block partially duplicates the output schema, so it is not maximally concise, but all sections carry meaningful guidance for a meta-tool that needs careful interpretation.

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

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

Covers selection criteria, failure modes (unverified), credential-less operation, the restart limitation, and how to interpret fields like selected vs enabled. With an output schema already present, nothing an agent needs to correctly invoke and interpret this tool is missing.

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

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

The input schema already covers response_format with an enum and default description, and coverage is 100%. The description only restates the default and format choices without adding meaning beyond the schema, so a baseline of 3 is appropriate.

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

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

States a specific action and resource: 'Report every toolset this server knows about, whether it is currently loaded, and how to load one that is not.' This clearly differentiates it from the alert- and schedule-focused sibling tools and establishes it as a meta-capability tool.

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

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

Gives explicit when-to-use guidance: 'Call this before telling the user something is impossible' and 'What can you do here?' — call rather than guessing. It also covers the unverified-toolset scenario and tells the agent to quote the reason, making the decision process concrete.

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

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

The annotations already mark the tool read-only, idempotent, and non-destructive. The description adds substantial behavioral context beyond that: it documents the response envelope, pagination fields, default output format, and even explains a likely HTTP 401 cause (missing read:ops-config:jira-service-management scope) that distinguishes this family from alert tools. This is far beyond what annotations provide.

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

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

Every section earns its place: purpose, usage routing, parameter summary, return shape, examples, and error handling. The most important usage guidance is front-loaded, and the rest is compact and scannable.

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

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

For a read-only list tool with no required parameters, this is complete. It includes the output structure, pagination semantics, example invocations, and a likely auth failure cause. An agent has everything needed to call it successfully and interpret the result.

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

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

The input schema has 100% coverage, with each parameter already documented by name, type, default, and constraints. The description largely restates the parameters, but it does add light semantic value by tying limit/offset to pagination and providing an example that says matching on the returned name is how you find a specific schedule id. That is useful but not a major addition.

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

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

The description states a specific action ('List') and a specific resource ('on-call schedules configured in JSM Operations'), then names the key fields returned: ids, owning teams, and timezones. It also differentiates itself from sibling tools like jsm_get_on_call and jsm_get_next_on_call by explicitly positioning itself as the entry point for discovering schedule ids and rotations.

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

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

It gives clear when-to-use guidance: use when you need a schedule id for jsm_get_on_call or jsm_get_next_on_call, or when you want to enumerate existing rotations. This explicitly names sibling tools and the selection condition, so an agent can route correctly without opening any other definitions.

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

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

Beyond the annotations, the description discloses that the action is asynchronous, that a successful receipt does not prove removal, and that missing keys are silently ignored. It also explains the permission distinction between delete:ops-alert and write:ops-alert. These are meaningful behavioral details not available from the schema or annotations.

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

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

The description is well-structured with a clear first-sentence purpose, Args, Returns, an IMPORTANT async warning, a caveat about receipt semantics, and a constraints/errors section. Every sentence earns its place and the formatting makes the critical warnings easy to scan.

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

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

For a destructive, asynchronous tool, the description covers everything an agent needs: what to pass, what is returned, how to verify completion, what the semantics of a non-existent key are, and what permission is required. It is self-sufficient for correct invocation and follow-up.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the key semantics ('full alert id not tinyId', 'keys, not values') but does not add meaning beyond what the schema already provides. It is accurate but not additive.

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

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

The description opens with 'Remove properties from a JSM alert by key', a specific verb-plus-resource statement that clearly identifies the operation. It distinguishes this from sibling tools that deal with tags, notes, or adding properties, and the title reinforces the same scope.

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

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

The description gives clear operational guidance: the action is asynchronous, must be verified with jsm_get_request_status, and removal of absent keys is not an error. It also states the required delete grant. It does not explicitly contrast with alternatives like jsm_remove_alert_tags or jsm_add_alert_extra_properties, but the behavior and prerequisites are clear enough for an agent to know when to use it.

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

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

Annotations already mark this destructive/non-read-only/idempotent; the description adds meaningful behavioral detail beyond that: the action is asynchronous and returns a requestId to poll, a no-op removal still returns a successful receipt, and a separate delete:ops-alert grant is required. No contradiction with annotations.

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

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

The description is front-loaded with the core action, then organized into Args/Returns/IMPORTANT/Constraints. Every sentence earns its place: async polling, exact matching, permission requirements, and edge-case behavior are all included without redundancy.

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

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

For a two-parameter mutation with an output schema, the description covers everything an agent needs: required permission, async verification path, exact-match behavior, and the silent-success edge case. The siblings list and schema round out the context.

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

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

Input schema already covers both parameters at 100%, including the full-id-vs-tinyId warning and case-sensitivity. The description reinforces these and adds practical guidance on how to choose tag values (read current tags first rather than guessing casing), slightly exceeding the schema. It doesn't change the baseline much because the schema already does most of the work.

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

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

The description opens with a specific verb and resource: 'Remove one or more tags from a JSM alert.' This clearly distinguishes it from siblings like jsm_add_alert_tags and jsm_remove_alert_extra_properties, and the title and description agree.

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

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

It gives clear when-to-use context: removed tags are exactly/case-sensitively matched, and it instructs reading current tags with jsm_get_alert first and polling jsm_get_request_status after. It does not explicitly name an alternative tool for adding tags or state a when-not-to-use condition, so it falls just short of a 5.

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

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

The annotations already indicate this is a mutating, non-destructive, idempotent action, but the description adds important behavioral detail beyond that: the action is asynchronous and returns a requestId that must be checked via jsm_get_request_status. It also reveals edge behavior like past end_time instants causing immediate un-snoozing and snoozing a closed alert having no effect.

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

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

The description is longer than average, but it is tightly organized into purpose, usage, arguments, async warning, time handling, examples, and constraints. Every paragraph earns its place by addressing a distinct operational risk, with the most critical caveats (async execution and absolute-time semantics) appearing early.

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

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

Given the tool's non-obvious async behavior, time-format sharp edges, and terminal behavior for closed alerts, the description is complete. It covers how to invoke the tool, how to verify the result, what errors or misleading outcomes to expect, and what the return payload looks like, while the output schema covers the exact returned shape.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes well beyond the schema. It warns that alert_id is the full id and not the tinyId, clarifies that end_time is an absolute instant rather than a duration, gives concrete ISO 8601 examples, and tells the agent how to handle a relative request like 'give it an hour'. The only blemish is the schema's contradictory 'Must be in the future — a past instant is accepted' phrasing, which the description resolves correctly.

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

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

The description uses a specific verb ('Silence ... notifications') and resource ('a JSM alert') and clarifies that it is a temporary pause which resumes later. It distinguishes the action from closing an alert, so an agent can immediately tell it apart from the sibling jsm_close_alert.

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

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

It explicitly frames snoozing as the right choice when there is 'nothing to do until the maintenance window ends' and explains why closing would be wrong because it removes the alert from the open queue and loses the open-problem state. This gives clear when-to-use and when-not-to-use guidance against a relevant alternative.

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

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

Beyond the annotations (readOnly=false, idempotent=true), the description discloses that the action is asynchronous and should be verified via jsm_get_request_status, that it restarts paging and can cause a phone to ring, and that unacknowledging an already-unacknowledged alert is a no-op. These details align with and enrich the annotations rather than contradicting them.

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

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

The description is front-loaded with its core purpose and uses clear sections including Args, Returns, IMPORTANT, Examples, and Constraints. It is somewhat long, and the example imports a non-existent `note` parameter, but nearly every other sentence carries meaningful operational guidance.

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

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

For a mutating alert tool with an output schema, the description covers return shape, asynchronous verification, idempotency, and human-impact warning, so an agent has enough to invoke it correctly. The only real gap is the misleading example that references a `note` parameter not present in the input schema.

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

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

The schema already fully documents alert_id at 100% coverage, so the baseline is 3; the description adds little beyond repeating the full-id warning. However, the example line `note="Handing back, on another incident"` introduces a `note` argument that is absent from the schema and disallowed by additionalProperties=false, which could mislead an agent into passing an invalid parameter.

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

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

The first sentence states the exact action ('Return an acknowledged JSM alert to unacknowledged') and the consequence ('escalation notifications resume'). This is a specific verb+resource phrasing that clearly distinguishes the tool from sibling alert-mutation actions, and the 'does not close, snooze or reassign' line reinforces the boundary.

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

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

It gives an explicit when-to-use scenario ('picked it up by mistake, or got pulled onto something else') and explicitly excludes alternative behaviors by stating it does not close, snooze, or reassign. It also adds practical advice about warning the person before restarting paging, which helps an agent decide when to invoke the tool.

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

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

Beyond the annotations, the description discloses that the action is asynchronous, overwrites rather than appends, and may change paging behavior when priority is raised. It also warns that not reading the current value first can destroy content written by someone else. These behavioral traits are concrete and directly relevant to safe invocation, and there is no contradiction with the annotations.

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

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

The description is longer than average, but every section earns its place: purpose, arguments, return value, async behavior, destructive warning, alternative tool, field-specific constraints, and examples. The key warning about overwriting is front-loaded after the summary, and the structure makes the important caveats easy to find.

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

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

The description is complete for a destructive, asynchronous mutation tool. It covers what the operation does, how to invoke it correctly, what to do after invocation, what pitfalls exist, and which siblings to use instead. The output schema plus provided return example fill in the response contract, so nothing essential is missing.

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

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

Even though schema description coverage is 100%, the description adds substantial meaning: alert_id must be the full id and not the tinyId, priority must be exactly P1–P5, message should be one line, and an empty description clears it. It also clarifies that there are no user/source arguments, which helps the agent avoid confusion with other tools.

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

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

The description opens with a specific verb and resource: 'Overwrite one field on an existing JSM alert' and immediately enumerates the three possible fields. It clearly distinguishes itself from sibling write tools by contrasting with jsm_add_alert_note, and the purpose is unambiguous even without reading the schema.

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

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

The description gives explicit when-to-use guidance: correcting an alert once more is known, and warns against using it to append context. It names the exact alternative (jsm_add_alert_note) and tells the agent to read the current value first with jsm_get_alert. It also explains the async follow-up step with jsm_get_request_status.

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

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

Annotations already mark destructiveHint and idempotentHint, and the description adds important behavior beyond that: this operation is synchronous unlike other alert writes, returns the updated note with no requestId, replaces the entire note text with no append, and has a specific 404 meaning. This is exactly the kind of behavioral context an agent needs.

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

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

The description is longer than average, but every section earns its place: primary behavior, usage guidance, parameter semantics, return behavior, destructive warning, example, and error meaning. It is well-structured with headers and front-loaded warnings, making it easy to scan.

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

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

For a 3-parameter mutation with an output schema and rich annotations, this description is complete. It covers why to use it, what it does, how it behaves differently from siblings, what gets replaced, what returns, and how to interpret a common error. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's Args section adds meaningful clarification: alert_id must be the full id not the tinyId, note_id is sourced from jsm_list_alert_notes, and note is the complete replacement text. It reinforces and slightly extends the schema without merely repeating it.

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

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

The description states a specific action ('Replace the text of an existing note') on a specific resource (a JSM alert note), and explicitly contrasts it with jsm_add_alert_note. This makes it immediately distinguishable from sibling note tools.

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

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

It clearly says when to use this tool: to correct a note just written. It also explicitly says when NOT to use it and which sibling to prefer instead: use jsm_add_alert_note for anything read as a development, because the timeline is the record. The example reinforces this decision.

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