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

Annotations carry the safety profile, and the description goes well beyond them: it discloses the asynchronous contract ('the response confirms the request was accepted, not that the alert changed'), the no-op idempotency behavior, and the exact return shape. The response-shape detail is partly redundant with the output schema, which keeps this from a 5.

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?

Front-loaded with the action and its effect, then prerequisites, args, return and async caveat, in a scannable order with no filler prose. The closing example is the weak point: it is over-formatted and invents a parameter, slightly muddying an otherwise tight 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?

For a one-parameter mutation with an output schema, everything needed to call and verify it is present: the id format requirement, the async acceptance semantics, the follow-up verification tool, and the non-resolving scope. Nothing an agent needs 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% and the schema already warns that alert_id is the full id, not the tinyId, so the description adds little on that front. Worse, the trailing example implies a 'note' argument ('note="Investigating, RVS"') that does not exist in the schema and would be rejected by additionalProperties:false — a misleading detail, but the schema itself remains authoritative.

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 verb+resource ('acknowledge an open JSM alert') plus the immediate effect ('stopping further escalation notifications'). It explicitly distinguishes itself from the nearest sibling by name — jsm_close_alert resolves, this does not — so an agent can separate the two without opening either 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?

Gives explicit when-to-use (a human has picked the alert up), an explicit when-not/alternative ('It does not resolve the alert — use jsm_close_alert for that'), and an edge-case rule ('Acknowledging an already-acknowledged alert is a no-op'). It also routes the agent to jsm_get_request_status for verification.

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 call is asynchronous, that it merges by key, and that an existing key is overwritten without warning. These are non-obvious operational traits an agent must know, and they are stated directly rather than left to inference.

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?

It is front-loaded with the purpose, then structured into args, returns, an async warning, merge semantics, and an example. Every block is informative, though the args/returns restatements overlap with the schema and the trailing example is truncated, adding minor 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 an async mutation tool with a nested object param and an output schema, the description covers the async requirement, the verification path, the overwrite/merge semantics, and pre-read guidance. Nothing an agent needs to call 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 both params are already documented, but the description reinforces the critical alert_id vs tinyId distinction and adds a worked example mapping a natural-language request to the extra_properties object. The added example value slightly exceeds the schema-only baseline.

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 ('Attach arbitrary key/value context to a JSM alert') and distinguishes the action from sibling tools by contrasting it with notes ('the structured half of an alert, next to the prose in its description'). An agent can select it over jsm_add_alert_note or jsm_update_alert_field without further reading.

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 names concrete use cases (runbook link, region, deploy, trace id), gives the alternative behavior (prose notes vs programmatic properties), and routes to two follow-up tools: read first with jsm_get_alert and verify with jsm_get_request_status. This is explicit when-to-use and what-to-do-next 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 only declare the generic safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=true). The description adds two behaviors annotations cannot express: the operation is asynchronous and must be verified via jsm_get_request_status with the returned requestId, and it appends to the timeline without mutating alert state.

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?

Front-loaded with the core action, then scope constraint, use cases, args, return, and a worked example — a sensible order with little filler. The Args and Returns blocks partially duplicate the schema and output schema, which is the only real padding.

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 an async mutation with an output schema and annotations, this covers the essentials: the exact identifier to supply, the state-preservation guarantee, the async follow-up tool, and a concrete example. The only gap, the phantom user/source arguments, is a correctness slip rather than a missing concept.

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 already 100% for the two real parameters, and the description's alert_id/note notes largely restate the schema. Worse, the Args block advertises 'user' and 'source' as optional parameters that do not exist in the schema, which declares additionalProperties: false — an agent following the description could pass arguments that get rejected.

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 verb and resource (append a note to a JSM alert's activity timeline) plus the crucial scope constraint that it does not change alert state. It explicitly separates itself from siblings jsm_acknowledge_alert, jsm_close_alert and jsm_assign_alert, so an agent can route correctly without opening a 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?

Names concrete use cases (record triage findings, link a runbook/dashboard, leave context for the next responder) and states what the tool is NOT for. It also points to the follow-up tool (jsm_get_request_status) required after the async call, which is exactly the when-to-use guidance an agent needs.

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 non-destructive, idempotent, open-world behavior, and the description goes further by disclosing that the operation is asynchronous, that the returned requestId must be verified via jsm_get_request_status, and what HTTP 422 implies. The 'responders are additive' note reinforces the non-destructive annotation rather than contradicting it.

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?

Front-loaded with the action and its effect, then structured into args, returns, async warning, example, and error handling sections. Slightly repetitive of the schema in the Args block, but every section carries information an agent needs.

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 an output schema present, the description need not explain return values, yet it still summarizes them and adds the critical async-verification step. Error handling and id-discovery guidance (jsm_list_schedules) round out a definition complete enough to call the tool correctly on the first try.

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 all three parameters and the enum are already documented in the schema, including the alert_id-vs-tinyId warning. The description largely restates these and adds only a worked example mapping a natural-language request to responder_type='team', which is marginal added meaning over 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?

States a specific verb (add) and resource (responder) plus the accepted responder kinds, and scopes it to an existing JSM alert. It is distinguishable from adjacent siblings such as jsm_assign_alert and jsm_escalate_alert because it names the responder categories explicitly.

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 a concrete usage trigger ('pull in another team once triage shows the alert belongs elsewhere') and states the key constraint that responders are additive rather than replacing existing ones. It does not explicitly contrast itself with jsm_assign_alert or jsm_escalate_alert, which would be needed for 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?

Annotations declare the safety profile (not read-only, idempotent, non-destructive), but the description adds genuinely new behavioral context: the operation is asynchronous and must be verified via jsm_get_request_status with the returned requestId, plus the case-sensitivity caveat that 'DB' and 'db' are distinct tags. These are exactly the traits an agent cannot infer from 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?

Well front-loaded with the core action in the first sentence, then structured with headers for tags, args, returns, async warning, and examples. It is somewhat long and the Returns block largely duplicates the output schema, but no sentence is wasted for an agent that needs the async and casing 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 with a full output schema and annotations, the description covers everything needed: argument meaning, the async verification follow-up tool, the case-sensitivity pitfall, and an intent-to-arguments example. The output schema carries return details, so the brief Returns listing is sufficient.

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 adds practical meaning beyond the schema: it reinforces that alert_id is the full id (not tinyId) and turns the case-sensitivity rule into actionable guidance ('match whatever the team already uses rather than inventing a casing') with a concrete example. This is modest added value over a fully documented 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?

States a specific verb and resource ('Add one or more tags to a JSM alert') and immediately clarifies the additive semantics ('existing ones stay'), which cleanly distinguishes it from the sibling jsm_remove_alert_tags. The agent knows exactly what the tool does without opening the schema.

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

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

Explains the purpose of tags in the workflow — grouping and later retrieval via jsm_list_alerts with tag:"db" — and provides an example mapping a user intent to arguments. It stops short of naming the removal sibling or stating when not to use it, so it is strong context but not full when/when-not routing.

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 the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description goes well beyond them: it discloses that the call is asynchronous, mandates verification via jsm_get_request_status with the returned requestId, and maps the common failure mode (HTTP 422 / failed status) to its cause. That is exactly the added behavioral context the annotations cannot carry.

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?

Front-loads the core purpose and the sibling distinction, then layers args, return shape, async caveat, example, and error mapping in a scannable order. Some content (the account id format and the 'not an email' warning) is repeated from the schema, which is the only thing keeping it from a 5.

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?

Despite an output schema existing, the description still surfaces the return shape and — more importantly — the asynchronous requirement to poll jsm_get_request_status, which an agent would otherwise miss. Combined with the error mapping and id-source guidance, nothing needed to invoke this correctly is absent.

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 compensates for the ambiguity traps: it stresses full alert id vs tinyId, and account_id as an Atlassian id rather than email/display name, plus how to obtain one from jsm_get_on_call or jsm_get_alert. This largely duplicates the schema text, however, so it is useful reinforcement rather than net-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?

States a specific verb and resource ('Make one person the owner of a JSM alert') and immediately contrasts it with the nearest sibling, jsm_add_alert_responder, by explaining that assignment confers ownership while adding a responder does not. An agent can select between the two without opening either 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?

Gives explicit when-to-use ('when triage has decided whose problem it is'), an explicit scope exclusion ('for that one alert rather than a class of them — routing rules, not assignment, are how a class of alerts finds its team'), and a prerequisite workflow example for the common on-call case. This is close to the ideal for routing 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?

With annotations already declaring destructive and idempotent behavior, the description adds critical context: the action is asynchronous, must be verified via jsm_get_request_status, and is effectively one-way (a closed alert cannot be reopened through this API). It also explains that recurring conditions create fresh alerts rather than reviving the closed record.

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?

Front-loaded with purpose and one-way behavior, then structured into Args, Returns, IMPORTANT, Examples, and Don't use when. Slightly long because the Returns section duplicates the output schema and the example includes a phantom note parameter, but overall it is efficient and well organized.

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, the description covers the essential operational details: the need to verify with jsm_get_request_status, the one-way nature of closing, and the preferred alternative while work is ongoing. Since an output schema exists, the return-value summary is extra but harmless, and 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 fully documents alert_id. The description's Args section merely repeats the full-id vs tinyId distinction, and its example introduces a note parameter that is absent from the schema (additionalProperties: false), which could mislead an agent. Baseline 3 is appropriate because the description adds no valid parameter semantics 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?

States a specific verb and resource ('Close a JSM alert') and immediately clarifies the effect ('marking it resolved and ending all notifications'). It distinguishes itself from siblings by naming jsm_acknowledge_alert as the preferred tool while work is in progress.

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 says when to use it (alert leaves the open queue) and when not to use it ('Don't use when: the alert is still being worked — acknowledge instead'). It also names the alternative tool (jsm_acknowledge_alert) with a clear condition.

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?

Adds substantial context beyond the annotations: alerts page people and enter routing/escalation rules, the endpoint has no actor override (unlike other write tools), the call is asynchronous and 200 does not mean synchronous, the response confirms acceptance not existence, alias de-duplication semantics drive safe-retry vs silent no-op, responders bypass routing, and the required write scope. Annotations only cover the safety profile; the description carries the real behavioral burden.

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-organized into purpose, args, returns, alias, examples, and constraints/errors. It is long, but almost every line earns its place given a 12-parameter mutation tool. The single 'IMPORTANT' paragraph is dense but front-loads the async gotcha well.

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 12-parameter, nested-object, async mutation tool, this covers the async gotcha (no alert id), the alias retry semantics, the required scope, the responder override behavior, and the 422 failure mode. Despite an output schema being present, the description correctly explains why knowing the requestId matters — retrieval paths are named. Nothing an agent needs 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 already 100%, so baseline would be 3, but the description adds meaning beyond the schema: it explains that alias is the de-duplication key with a concrete retry example, that responders bypass routing, that omitting priority lets routing rules decide, that source can be 'claude-mcp', and what 422 means. This is real value-add over 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?

States a specific verb and resource ('Create a new alert in Jira Service Management Operations') and explicitly differentiates from the sibling jsm_add_alert_note by naming it and describing the contrasting use case. An agent can pick this tool without opening any 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?

Explicit when-to-use ('when a human wants an incident tracked and escalated') and when-not ('not to leave a note, which is jsm_add_alert_note, and not to record something nobody needs to act on'). Names the alternative tool by name. Nothing is left to inference.

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 flag destructiveHint=true and openWorldHint=true, but the description goes well beyond them: it enumerates exactly what is lost (notes, activity log, attachments, timing), states there is no undo and the loss is global, discloses the asynchronous nature and the verification path via jsm_get_request_status, and calls out the separate delete:ops-alert:jira-service-management grant. That last point is a high-value behavioral disclosure an agent could not infer from the schema.

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 front-loaded with the decisive warning ('This is almost never the right tool') and organized into purpose, justification cases, args, async note, and constraints. Every section earns its place for an irreversible operation, though the safety argument is restated enough that it could be trimmed slightly.

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?

Return values are covered by the output schema and safety by the annotations, so the description need not repeat them; it instead supplies the missing pieces: the destruction scope, the async verification step, the required scope, and the pre-call confirmation workflow. Nothing an agent needs to call this correctly is absent.

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 documents alert_id with a full example and the tinyId warning, so the schema carries the weight. The description's 'not the tinyId' remark is redundant with the schema field description. Baseline 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 verb and resource ('Permanently delete a JSM alert and everything recorded on it') with an explicit scope statement about what is destroyed. It also draws a sharp line against the closest sibling, jsm_close_alert, so an agent can distinguish the two without opening either 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?

Explicit when-to-use (credentials/PII that must not persist, or a flood of alerts from a misconfigured integration) and when-not (never to tidy up, clear a queue, or loop over search results). It names the alternative jsm_close_alert and the condition that selects it, plus a required pre-flight workflow of reading the alert back and getting an explicit yes.

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 flag destructiveHint/idempotentHint, but the description adds genuinely new behavior: there is no undo or confirmation step at the API, the call is synchronous and returns 204 with no body (so no requestId to poll), and it requires a separate delete:ops-alert:... grant that a write:ops-alert token may lack (403 risk). It also prescribes quoting the note text back 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?

Front-loads the destructive action, then the usage rule, then the irreversible/no-undo warning, then args, returns, and constraints. Every sentence carries operative information — the 204/no-requestId and separate-permission notes are not padding.

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, permission-gated mutation this is complete: irreversibility, required grant, failure mode (403), argument sourcing (from jsm_list_alert_notes), and a return shape are all covered. An output schema exists, so the brief Returns line is sufficient rather than redundant.

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 the schema already documents both parameters, including the full-id-vs-tinyId distinction and that note_id is not the note text. The description only restates these, adding no syntax or sourcing detail beyond the schema, 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?

States a specific verb and resource ('Permanently remove a note from a JSM alert's timeline') and explicitly distinguishes the operation from jsm_update_alert_note, so an agent can separate the two destructive-ish note tools without reading either 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?

Gives an explicit when-to-use ('only for a note that should never have been written — a pasted credential, personal information, wrong alert') and an explicit when-not with the named alternative ('a note that turned out to be wrong: that is what jsm_update_alert_note is for'). The rationale for the distinction is even supplied.

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 cover safety flags, but the description adds substantial behavior they do not: the call is asynchronous, must be verified via jsm_get_request_status with the returned requestId, and pages people out of band ahead of their agreed schedule. It also maps the failure mode (HTTP 422) to a specific cause. No contradiction with idempotentHint/destructiveHint.

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?

Front-loaded purpose with clean sections (Args, Returns, IMPORTANT, Examples, Constraints) and no wasted framing. It loses a point for repeating the escalation_id-is-not-a-team-id warning three separate times, which pads the length.

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?

Even though an output schema exists, the description states the return shape and, more importantly, the async verification step an agent must take. Combined with the parameter guidance and error handling, nothing needed to invoke this 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 the baseline is 3, but the description reinforces the two easily-confused id types (full alert id vs tinyId; escalation id vs team/schedule id) and attaches the concrete consequence of passing the wrong one (422 rather than escalating to something adjacent). This meaning is largely duplicated from the schema, so it earns a bump rather than a top score.

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 verb and resource ('Push a JSM alert into an escalation policy') plus the immediate-vs-scheduled distinction that separates it from passive escalation. An agent can tell this apart from jsm_assign_alert or jsm_execute_alert_action without opening the schema.

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

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

Gives an explicit triggering condition ('an alert is not getting picked up and waiting out the escalation timer is not acceptable') and an explicit caution to confirm with the user before acting on their behalf. The when-not case is implied by 'rather than waiting for it to escalate on its own.'

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?

Adds substantial context beyond annotations: explains the action is asynchronous, that an unrecognised name is accepted and silently does nothing (so a receipt is not evidence of execution), and that names are per-integration. Annotations declare destructiveHint=true, and the description reinforces the danger with production-impact warnings, not contradiction.

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 front-loaded with the core purpose, then args, returns, and a critical warning. The structure is clear, though the warning section is somewhat verbose and repeats the schema's own guidance about guessing action names.

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?

An output schema exists, so return values needn't be explained further. The description covers the asynchronous follow-up, error semantics (silent success on unknown names), and integration scoping — everything an agent needs to invoke this dangerous tool responsibly.

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, including the alert_id vs tinyId distinction and the action_name warning. The description reiterates the key gotchas (full alert id not tinyId; exact configured name) but adds little beyond what the schema provides, warranting a 4 rather than higher.

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 verb (run) and resource (custom alert action), with concrete examples like "Restart service" and "Roll back deploy". It distinguishes itself from siblings by naming jsm_get_request_status as the verification tool and noting the action is user-configured, which no sibling does.

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 explicit when-to-use (running a team's configured automation against an alert) and strong when-not guidance (do not guess an action name; ask the user and confirm). It names the follow-up tool jsm_get_request_status for verification.

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 readOnly, idempotent, non-destructive, open-world. The description still adds real behavior beyond them: responder ids are resolved to names when credentials allow, aliases only resolve against OPEN alerts, and HTTP 404 usually means a tinyId was passed. These operational constraints are not derivable from annotations or schema.

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?

Front-loaded purpose sentence, then grouped Args/Returns/Examples/Error handling sections. Every section carries distinct information; nothing is redundant filler.

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-resource getter with rich annotations and an output schema, this is complete: it covers purpose, routing from the list sibling, identifier pitfalls, error recovery, and alias scoping. An agent has everything needed to call it 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?

Schema coverage is 100%, so baseline is 3, but the description goes further with worked examples showing identifier/identifier_type usage in context (e.g. alias lookup for a closed vs open alert) and repeats the tinyId caveat. It adds marginal interpretive value over the fully documented 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?

States a specific verb and resource (retrieve full detail of a single JSM alert) and enumerates the payload fields returned. It explicitly differentiates from the sibling jsm_list_alerts by noting the list endpoint returns a thinner record.

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 says to use this 'after jsm_list_alerts when you need the payload an integration attached' — naming the alternative and the condition that selects this tool. The examples reinforce the intended sequencing.

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?

Adds rich context beyond annotations: explains identifier resolution to names, discloses the Jira user scope caveat, and gives a precise 401 diagnosis distinguishing a scope gap from a bad credential. This is the kind of operational insight structured fields cannot carry.

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?

Front-loaded with the core purpose, followed by usage, args, returns, examples, and error handling in a scannable format. Slightly list-heavy but each section earns its place.

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 purpose, usage, parameter details, return shape (even though output schema exists), identifier resolution behavior, and a specific error condition. Complete for an agent to call this correctly in a JSM ops 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?

Schema description coverage is 100%, so the baseline is 3. The description restates parameter meanings but adds little beyond the schema (e.g., it doesn't elaborate on the flat=true/false structure beyond what schema says).

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?

Specific verb+resource+scope: 'Return the responders who take over the next shift on a JSM schedule, and when that shift begins.' Clearly distinguished from sibling jsm_get_on_call (current shift) and jsm_get_schedule_timeline by the word 'next'.

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 use cases ('handover messages', 'deciding whether an alert can wait for the next rotation') and cross-tool examples with jsm_list_alerts. It does not, however, explicitly contrast with jsm_get_on_call (current on-call), which an agent may confuse with this one.

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 past the readOnly/idempotent/non-destructive annotations that already cover the safety profile: it discloses that account ids are resolved to names, that ids still return without the Jira user scope, that an empty result is a meaningful answer rather than a failure, and that a 401 here is a scope gap distinct from alerts.

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?

Front-loaded purpose, then args, returns, examples, and error handling in clearly labeled blocks. The 'Returns' block restates what the output schema already provides, which is some redundancy, but no section is filler.

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 annotations, a full output schema, and 100% parameter coverage already present, the description still supplies the non-obvious pieces: the resolved 'participants' field is called out as the field to read, plus scope-gap diagnosis and empty-result semantics.

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, but the description adds meaning beyond it: the cost tradeoff of schedule_identifier_type='name' (one extra lookup) and the concrete intent of 'flat' (rotation/escalation nesting vs. flat list). The parameter list largely mirrors the schema, keeping it short of a 5.

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 verb and resource ('Return the responders currently on-call for a JSM schedule') and immediately scopes it with the optional timestamp evaluation window. An agent can distinguish it from jsm_get_next_on_call and jsm_get_schedule_timeline without inspecting either 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?

Gives concrete usage framing ('who do I wake up?', 'who was on-call when this incident started?') and routes to jsm_list_schedules on a 404. It stops short of explicitly contrasting with the two closest siblings, jsm_get_next_on_call and jsm_get_schedule_timeline, so the alternative selection is only partly spelled out.

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 readOnly, idempotent and non-destructive, but the description adds substantial behavior beyond them: the async/eventually-consistent nature of writes, and the error-handling hint that a 404 shortly after a write means the request is still queued and should be retried. This is exactly the kind of context an agent needs to invoke it correctly.

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 front-loaded with the core purpose, then args, returns, examples, and error handling in scannable sections. Slightly verbose in repeating the full return shape despite an existing output schema, but every section earns its place.

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 an async-status tool with an output schema and full annotation coverage, the description is complete: it explains the async workflow, how to obtain the parameter, and how to interpret a transient failure. Nothing needed to call 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 the baseline is 3, but the description adds meaning: it ties request_id to its origin ('the requestId returned by a write tool') and gives a concrete example using jsm_acknowledge_alert. It also restates response_format's purpose, though the schema already covers that.

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 verb and resource ('Check whether an asynchronous alert action actually succeeded') and explains the async requestId model. It clearly distinguishes itself from the write tools and from re-reading the alert, so an agent can tell it apart from siblings like jsm_get_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?

Explicitly says when to use it (after any JSM alert write returns a requestId) and when not to (do not just re-read the alert and find it unchanged). It names the write actions that produce a requestId, giving clear routing 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 establish it as a safe, idempotent read, and the description adds genuinely new behavior: responders are resolved to display names rather than account ids, the returned window spans roughly three weeks around the requested date, and specific 401 remediation ('missing read:ops-config:jira-service-management'). It also explains the semantic meaning of shift types ('historical', 'override'), which the annotations cannot 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?

Front-loaded with purpose and the key usage discriminator, then organized into Args, Returns, Examples, and Error handling. It is on the long side, and the full Returns JSON block substantially duplicates an output schema that already exists, which is the only real waste.

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 tool with an output schema and full annotation coverage, this is complete: it explains the window semantics, responder resolution, argument meanings, concrete invocation examples, and auth-scope failure mode. An agent has everything needed to call it correctly 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?

Schema description coverage is 100%, so the schema already documents all four parameters including defaults and enums. The description's Args block largely restates that content, adding only marginal value (the code-format schedule_id example in the error section is minor). Baseline 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 verb and resource ('Return the on-call rotation periods for a JSM schedule') and immediately clarifies scope: 'who covers each shift, and exactly when each shift starts and ends.' It explicitly differentiates itself from the sibling jsm_get_on_call by framing the tool around boundaries rather than a single moment.

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 an explicit selection rule ('the tool for any question about shift boundaries rather than a single moment') plus four natural-language question examples that map to arguments. It also names the alternative and why it fails ('calling jsm_get_on_call at guessed timestamps takes many calls and still cannot find a boundary exactly').

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, idempotentHint and destructiveHint=false, so safety is covered. The description adds context the annotations don't: that logs are system-generated, that ordering defaults to newest-first, and how cursor paging continues via next_cursor. It does not discuss rate limits or retention, keeping it short of a 5.

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?

Purpose is front-loaded, followed by args, returns and examples in a predictable order. It is slightly verbose because the Args section duplicates content already present at 100% schema coverage, but nothing is ambiguous or padded.

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 paginated read tool with a declared output schema, the description supplies everything an agent needs: what the log contains, ordering, cursor paging, ID format caveat, and task examples. Return values are also spelled out, which is redundant but harmless.

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%, including the alert_id vs. tinyId distinction and the opaque-cursor semantics for offset, so the schema already carries parameter meaning. The description's Args block largely restates that; the examples are the only marginal addition, so 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?

States a specific verb (list) and resource (the system activity log for a JSM alert) and enumerates the event types it contains (state transitions, notifications, escalations, automated actions). It explicitly separates itself from jsm_list_alert_notes ('human comments live in ... instead'), so an agent can disambiguate without opening a 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?

Gives concrete task framings — 'why did nobody get paged?' and 'when was this escalated and to whom?' — plus two worked examples mapping user intent to exact argument values. It names the sibling that covers the adjacent use case (notes vs. logs).

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 the safe read-only, idempotent profile, so the bar is lower. The description still adds real context: newest-first default, that integrations append re-fire/resolution updates for deduplicated alerts, and that pagination uses opaque cursors rather than numeric offsets.

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?

Front-loads the purpose and the triage rationale, then organizes Args, Returns, Examples and a cursor note into scannable blocks. It is slightly long because the Args and Returns sections re-state what the schema and output schema already provide.

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?

An output schema exists and an explicit Returns block and pagination contract are supplied, so return handling is fully covered. Required vs optional params, defaults, enums and the cursor round-trip are all described, leaving nothing an agent needs to call this 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?

Schema coverage is 100% so the baseline is 3, but the description goes beyond it by pairing parameters with intent-driven examples (triage check vs full history) and warning that alert_id must be the full id, not the UI tinyId. Most of the Args list does duplicate the schema descriptions, which caps it at 4.

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 verb and resource ('List the notes ... recorded on a JSM alert's activity timeline') and immediately clarifies what notes are ('human comments'), which distinguishes this from the sibling log-listing tool. An agent can identify the operation without opening the schema.

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

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

Gives a clear when-to-use rule ('Read them before acting on an alert so you don't repeat work') and two natural-language examples that map intent to arguments. It does not explicitly name the nearest alternative (jsm_list_alert_logs) or state when not to use it, so it falls short of full routing 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 cover readOnly, idempotent, openWorld, and non-destructive. The description adds valuable operational behavior: offset+limit cannot exceed 20000 and malformed queries return HTTP 400 with case-sensitive field names. That is 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?

Front-loaded with purpose and role, then breaks into args, returns, examples, and constraints. It is somewhat long and the returns block duplicates the existing output schema, but the structure is clean and every section has some practical value.

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?

Complete for a search/list tool with six optional parameters and a high schema coverage. It covers when to use it, input syntax, output shape, pagination limits, error behavior, and examples, so an agent has everything needed to invoke it 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?

Schema description coverage is 100%, so baseline is 3. The description adds a cross-parameter constraint ('offset + limit must stay below 20000') and clarifies query error semantics, which the schema does not cover. It mostly repeats schema defaults and enums otherwise.

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 verb+resource ('Search and list alerts') and scope ('in Jira Service Management Operations'). It distinguishes itself from sibling tools by declaring itself the entry point for alert workflows and the resolver of tinyId to full alert id.

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 clear context: entry point for alert workflows, use to find open/unacknowledged alerts, filter by priority/team/tag, resolve tinyId. It excludes mutation ('reads only — never creates or modifies') but does not name specific alternative siblings (e.g., jsm_get_alert, jsm_create_alert) for particular cases.

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 cover readOnly/idempotent/destructive, but the description adds substantial non-annotation context: it makes no API call, needs no credentials, works even when the token is missing or wrong, and discloses the unverified toolset caveat with the exact enabling syntax and the reason it was blocked (plan exclusion or unheld permission). This is rich, clearly-earned 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?

Front-loaded with purpose and the 'call before declaring impossible' guidance, followed by a well-structured Returns block and concrete examples. It is on the long side, and some sentences (the parenthetical about 'selected') could be tightened, but nearly every sentence earns its place.

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?

An output schema exists, yet the description still explains the semantics an agent needs to interpret it correctly: what 'selected' vs 'enabled' means, what 'unverified' signals, and why. Combined with the usage examples and the restart caveat, nothing an agent needs to select or 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?

Schema coverage is 100% and the single response_format parameter is fully documented in both schema and description (with the markdown/json tradeoff spelled out: 'markdown' is compact, 'json' returns every field). The baseline for full coverage is 3; the added nuance about what 'json' returns nudges it up.

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 verb and resource ('report every toolset this server knows about, whether it is currently loaded, and how to load one that is not') and clearly distinguishes itself from its siblings, which are all alert/schedule operations. An agent can immediately tell this is a meta/discovery tool, not an API operation.

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 call it: 'Call this before telling the user something is impossible' and 'call this rather than guessing from your tool list.' It also names the failure mode it resolves (absent tool = not enabled vs. not supported) and the exact remedy (JSM_TOOLSETS env var), plus the caveat that restart is required.

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, non-destructive behavior, and the description goes beyond them with a non-obvious operational detail: a 401 here while alert tools work indicates a missing 'read:ops-config:jira-service-management' scope rather than bad credentials. Pagination via has_more/next_offset is also disclosed, which is real behavioral context an agent needs for multi-page traversal.

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 front-loaded: purpose, then when-to-use, then args, return shape, examples, error handling. Slightly redundant in repeating the parameter defaults and the full return payload that the schema and output schema already provide, but the structure is clean and skimmable.

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 purpose, routing to downstream tools, parameter limits, pagination, example invocations, and a specific auth-scope failure mode. With annotations and an output schema present, this is more than complete for a read-only list tool.

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 all three parameters (limit, offset, response_format) are already documented in the schema, including ranges and defaults. The description's Args block largely restates that, and the mention of matching on name in the example adds only marginal semantics. Baseline 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?

Specific verb ('List') plus resource ('on-call schedules configured in JSM Operations') with the fields returned (ids, owning teams, timezones) named. It clearly separates itself from the alert-oriented siblings by scope, so an agent can route between the two families without opening a 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?

Explicitly says 'Start here when you need a schedule id for jsm_get_on_call or jsm_get_next_on_call', naming the downstream alternatives and the condition that selects them. It also covers the exploratory case ('which rotations exist at all'), leaving no usage ambiguity.

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 (destructive/idempotent/openWorld), it discloses the async execution model, the exact verification path, that removing a nonexistent key is silently non-erroring (so a receipt proves nothing), and the separate delete:ops-alert:jira-service-management grant. These are precisely the behavioral traits structured fields cannot 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?

Front-loaded with the action, then Args, Returns, an IMPORTANT async warning, and Constraints. Every block earns its place and nothing is padding despite covering several distinct concerns.

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?

Output schema exists, yet the description still adds the async/verification workflow, silent-success caveat, and the required OAuth scope — everything an agent needs to invoke and confirm this destructive, asynchronous tool.

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 the schema already explains both keys ("Keys, not values") and alert_id ("NOT the short tinyId"). The description restates this same guidance, so it is useful reinforcement but adds no meaning beyond the schema; 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?

Specific verb + resource + scope: "Remove properties from a JSM alert by key." It is unambiguously distinct from the sibling jsm_add_alert_extra_properties and the field-mutating tools, and it clarifies that it operates on property keys, not fields or tags.

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 concrete operational guidance: it is asynchronous, must be verified via jsm_get_request_status with the returned requestId, and the caller should read the alert back if removal confirmation matters. It never explicitly names a sibling alternative or a when-not-to-use case (e.g., use jsm_update_alert_field for standard fields), so it stops short of 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?

Goes well beyond the annotations (destructiveHint/idempotentHint) by disclosing that the operation is asynchronous, that matching is case-sensitive and exact, that no-op removals still succeed, and that a separate delete:ops-alert:jira-service-management grant is required and may 403 where adding tags succeeds. This is rich, actionable behavioral 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?

Front-loaded with a one-line purpose, then Args/Returns/IMPORTANT/Constraints – each section earns its place. Slightly long with some repetition of schema content, but no filler.

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 async verification, permission requirements, error behavior, and no-op caveats, and an output schema already exists so return values need not be re-explained. Nothing an agent needs to call this 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 the baseline is 3, but the description reinforces the critical alert_id-vs-tinyId distinction and the exact/case-sensitive tag matching semantics that drive correct invocation. The overlap with the schema docs keeps it from a 5.

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 verb+resource ('Remove one or more tags from a JSM alert') and is immediately distinguishable from its sibling jsm_add_alert_tags. An agent knows exactly what operation this performs.

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 routes the agent to jsm_get_alert to read current tags before acting, and to jsm_get_request_status to verify the asynchronous result. It also warns that silent no-match removals still return success, which is genuine when-to-use/when-to-be-careful 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?

Adds substantial behavior beyond annotations: asynchronous execution with a required follow-up verification call (jsm_get_request_status), reversal semantics (resumes as if untouched), and the past-instant trap that masquerades as a failure. Annotations cover safety/idempotency, but the async contract and time-handling sharp edge are genuinely new value. Output/return shape is documented.

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?

Front-loaded with purpose and rationale, then args, returns, and the time-handling warning. It is somewhat long but every section earns its place (the time-handling and async notes are high-value). Minor redundancy between description and schema on the past-instant caveat.

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 2-param async mutation tool with an output schema and full annotation coverage, this covers purpose, rationale, return contract, verification path, error case, and the tricky time semantics. An agent has everything needed to call it 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?

Schema coverage is 100% so the baseline is 3, but the description adds real meaning: it warns that alert_id is NOT the tinyId, explains end_time is an absolute instant rather than a duration, and that a bare local time should be avoided in favor of an explicit offset. That goes beyond the schema's field-level 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?

States a specific verb (snooze/silence) and resource (JSM alert notifications), with scope defined as 'until a specific instant, after which it resumes as if untouched.' It explicitly distinguishes itself from the closest sibling (close_alert) by explaining why closing is wrong here.

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 an explicit when-to-use scenario ('we know, and there is nothing to do until the maintenance window ends') and an explicit when-not-to ('Closing it would remove it from the open queue and lose the fact that it is still an open problem'). It also notes the closed-alert no-op case. This is unambiguous routing 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 idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description goes beyond them by disclosing async execution, the verification path (jsm_get_request_status with the requestId), the escalation/paging side effect, and the no-op-on-unacked behavior — a genuinely useful behavioral layer. Minor deduction because the async guidance duplicates what the returned requestId field already implies.

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 front-loaded: purpose first, then when-to-use, args, returns, async warning, examples, constraints. The Returns block is redundant given an output schema exists, and the example invents a 'note' field, slightly diluting an otherwise tight structure.

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 mutation with an output schema, the definition covers the safety profile (async, no-op case, paging restart), the verification workflow, and a concrete example — everything an agent needs to call it correctly and warn the user.

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 alert_id fully, including the tinyId caveat. The description only restates 'the full alert id (not the tinyId)', adding no new syntax. The example's 'note=' argument does not exist in the schema, which is mildly misleading rather than clarifying.

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 precise verb+resource: 'Return an acknowledged JSM alert to unacknowledged, so escalation notifications resume.' It also explicitly delimits scope against siblings — 'does not close, snooze or reassign' — mapping directly to jsm_close_alert, jsm_snooze_alert, and jsm_assign_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?

Gives a concrete when-to-use ('someone acked an alert they cannot actually work — picked it up by mistake') plus explicit when-not via the close/snooze/reassign exclusion. It even adds a behavioral caution to communicate before acting, which no sibling definition would provide.

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 cover the safety profile (destructiveHint=true, idempotentHint=true, openWorldHint=true), and the description adds substantial behavior beyond that: the action is asynchronous and must be verified via jsm_get_request_status, it overwrites rather than appends, reading first avoids destroying existing content, and raising priority can change paging. None of this is recoverable from the annotations alone.

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?

It is well front-loaded — the core action leads, followed by args, async caveat, the overwrite warning, and examples. It is longer than average, and the Args block partially restates the schema, but nearly every sentence carries actionable information.

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, async, open-world mutation with three required params, the description covers everything an agent needs: what is overwritten, async verification path, the priority enum constraint, the append-vs-replace pitfall, and the paging side effect. An output schema exists, so return-value explanation is not required.

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 adds genuine value: it stresses alert_id is the full id not the tinyId, pins priority to exact values P1–P5 (rejecting 'high' or '1'), and clarifies that 'value' means the new value with no user/source arguments unlike other write tools. Some content overlaps the schema, keeping it just short of a 5.

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 ('overwrite') and resource ('one field on an existing JSM alert') and enumerates the exact fields (priority, message, description). It explicitly distinguishes itself from siblings jsm_add_alert_note and jsm_update_alert_note, so an agent can route correctly without opening a 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 gives explicit when-to-use context (correcting an alert once triage knows more than the raising integration) and a clear when-not-to-use rule with a named alternative: use jsm_add_alert_note if you mean to append rather than replace. This is exactly the alternative-routing guidance the dimension rewards.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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