statuspal

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

Annotations only provide destructiveHint=true, so the description carries the burden of explaining the impact. It states the incident is published to the 'LIVE public status page' and that notify=true emails subscribers, which are critical side effects. This goes beyond the generic destructive hint and gives the agent precise expectations about what will change.

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?

Three sentences, no waste. The main action is front-loaded ('PUBLISHES a new incident to the LIVE public status page'), followed by the type distinction and endpoint. Every sentence adds value, and the structure aids quick comprehension.

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 create tool with 8 parameters, the description covers the key behavior and semantics. It omits response format (no output schema) and does not explicitly mention that scheduled maintenance requires starts_at, but these are captured in the schema. The endpoint is provided, aiding integration context. Slightly more could be said about prerequisites, but the schema 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?

Schema description coverage is 100%, so the schema already documents all parameters well. The description reiterates the type enum semantics and endpoint, but adds little beyond the schema. It does not explain edge cases like required starts_at for scheduled maintenance (schema does). Thus, it meets the baseline but does not elevate 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 ('PUBLISHES') and resource ('a new incident to the LIVE public status page'), making the action unambiguous. It also distinguishes incident types ('major'/'minor' outage vs 'scheduled' maintenance), which sets it apart from siblings like update_incident or delete_incident. The endpoint is explicitly provided, reinforcing the 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?

The description clearly indicates this tool creates an incident and explains the type semantics, which guides when to use it for outages vs maintenance. However, it does not explicitly mention when not to use it (e.g., 'use update_incident to modify existing incidents') or any prerequisites. The guidance is clear but not exhaustive, and the sibling names imply alternatives without being 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?

Beyond the destructiveHint annotation, the description discloses that the update appears on the LIVE public status page and that notify=true triggers subscriber notifications. This adds meaningful behavioral context for an agent deciding whether the action is appropriate. 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?

One dense sentence front-loads the action and resource, then adds the endpoint and key behavioral caveat. No filler is present, and the examples and live-page warning earn their 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 a six-parameter mutation tool with a full input schema, the description plus annotations is sufficient to invoke it correctly: required parameters are in the schema, the public effect is stated, and the notify behavior is explained. It does not cover response/error details, but no output schema exists and these are not essential for correct 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 schema already documents every parameter. The description largely repeats the type examples and notify behavior already present in the schema rather than adding new parameter-specific meaning, so the baseline score 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 (POST an update), a specific resource (existing incident), and the lifecycle stage values. It also distinguishes itself from incident creation and read-only tools by explicitly targeting an existing incident on the LIVE public status page.

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 implies when to use it: when an incident already exists and the agent needs to post a status update. However, it does not explicitly mention alternatives such as statuspal_update_incident or state when not to use this tool, so guidance is mostly implied rather than explicit.

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, so the description's additional value is in emphasizing that deletion is permanent and affects the LIVE public status page. This goes beyond the annotation by clarifying the real-world consequence and irreversibility.

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?

One focused sentence plus the API endpoint. The destructive action is front-loaded ('DELETES... permanently removes'), making the tool's core behavior immediately visible with 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?

For a two-parameter delete tool with destructiveHint annotation and no output schema, this description covers the essential context: what is deleted, where, and that the deletion is permanent. An agent has enough 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 both parameters are already documented. The description adds the endpoint path showing subdomain and incident_id usage, but it does not enrich parameter meaning beyond what the schema provides.

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 ('DELETES') and resource ('incident') and adds critical scope ('from the LIVE public status page'). It clearly distinguishes this from sibling tools like statuspal_create_incident, statuspal_update_incident, and statuspal_get_incident by indicating a destructive delete 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?

The description makes the use case clear: use this tool when an incident must be removed from the public status page. It does not explicitly name alternatives, but the delete operation is unambiguous and the 'permanently removes' wording signals when not to use it casually.

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 readOnlyHint annotation already covers the read-only safety profile. The description adds the HTTP GET endpoint and ID-based lookup, which is consistent but does not disclose extra behavioral details such as not-found handling, response format, or auth requirements. With the annotation in place, this is adequate.

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?

Two short sentences deliver the core action and the exact endpoint. There is no filler, and the most important information is front-loaded before the optional path detail.

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 simple get-by-id operation with all parameters documented and a read-only annotation, the description is nearly complete. It does not describe the response shape or error behavior, but the phrase 'Get a single incident' sufficiently implies the returned resource for invocation purposes.

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 documents both subdomain and incident_id. The description does not add new parameter meaning beyond mapping them into the endpoint path, but no compensation is needed given the full schema coverage.

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 ('Get'), a specific resource ('a single incident'), and the key identifier ('by its id'). The word 'single' naturally distinguishes it from statuspal_list_incidents, and the endpoint template reinforces the exact operation without 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?

The description makes clear this is for fetching one incident when the incident_id is known. It does not explicitly name alternatives or exclusions, but the contrast with listing, creating, updating, and deleting incidents is strongly implied by the wording.

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 readOnlyHint annotation already establishes that this is a safe read operation. The description adds the endpoint shape and scoping to a single service, but does not describe response contents, pagination, rate limits, or authentication behavior. With annotations covering the safety profile, this is adequate but not rich.

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 compact and front-loaded: it states what the tool does in the first sentence and adds the relevant endpoint in the second. There is no filler or redundant restatement of the tool name.

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 low-complexity, read-only lookup with a fully documented schema, the description is largely complete. Because there is no output schema, it could have clarified what the returned status payload contains, but 'current status of a single service' gives a reasonable expectation of 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 schema provides 100% description coverage for both parameters, including the subdomain override note. The description reinforces that service_id is the primary selector and shows the parameter positions in the URL, but it does not add significant meaning 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 clearly states the operation: get the current status of a single service by its id. It also includes the exact API route, which distinguishes it from sibling tools like statuspal_get_status, statuspal_get_summary, and statuspal_list_services.

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 clearly implies when to use this tool: when you need the current status of a specific service and know its service_id. It does not explicitly name alternatives or when-not-to-use conditions, but the single-service scoping provides sufficient context.

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 readOnlyHint annotation already communicates the read-only nature, and the description aligns with it by saying 'Get'. The description adds the endpoint and scopes the result to the aggregate status type, but it does not disclose additional behavioral details such as response format, auth requirements, or rate limits. This is acceptable given the annotation coverage.

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 a single concise sentence with the core action front-loaded, followed by the precise endpoint. There is no wasted text, and every element contributes to understanding the tool's purpose.

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 simple read-only tool with one optional parameter, the description is nearly complete: it states what is returned (aggregate status type) and how to invoke it. However, it does not explicitly differentiate itself from the closely related get_summary or get_service_status tools, so slightly more contextual guidance would make it 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 schema provides 100% coverage for the only parameter, subdomain, including its meaning and override behavior. The description does not add significant parameter-level semantics beyond what the schema already states, so a baseline score 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?

The description clearly states the action ('Get') and resource ('current overall status'), and the parenthetical 'aggregate status type' helps distinguish it from per-service or summary tools. The endpoint is also provided, but it does not explicitly name or contrast sibling tools, which prevents a top score.

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 implies when to use the tool—when the overall status is needed—but provides no explicit guidance about when not to use it or which sibling alternative to choose. The phrase 'aggregate status type' offers some context, but the description does not mention get_service_status or get_summary.

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, and the description adds the concrete HTTP method/path (GET /status_pages/{subdomain}/summary) and the exact response shape, listing all top-level fields. This goes beyond the annotation by clarifying what the summary contains, though it does not discuss authentication or rate limits.

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 a single front-loaded sentence that states the operation, emphasizes scope, lists the returned fields, and provides the endpoint. Every piece of information earns its place, and there is 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?

For a simple read-only summary tool with one optional parameter and no output schema, the description is complete: it names the endpoint, enumerates the response fields, and the schema handles the parameter meaning. Nothing needed to correctly invoke the 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 schema already covers the single optional parameter at 100% and explains that it overrides STATUSPAL_SUBDOMAIN. The description only references the parameter in the endpoint path and adds no additional semantic detail, so the baseline score 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?

The description uses a specific verb ('Get') and resource ('status-page summary') and enumerates exactly what is returned, including status_page, services[], incidents[], and current_status_type. The capitalized 'FULL' helps distinguish this aggregate summary from sibling resource-specific tools, though it does not explicitly name a sibling or state what it is not.

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 phrase 'FULL status-page summary' implies this is the comprehensive snapshot tool, which provides some usage context compared to sibling list/detail tools. However, it does not explicitly state when to prefer this over statuspal_get_status or statuspal_list_incidents, nor does it mention any exclusions or alternatives.

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 readOnlyHint annotation already signals safety, and the description adds meaningful behavioral detail: the exact response envelope, pagination cursors, total_count, and the HTTP endpoint. This gives the agent a clear model of what the call returns and how pagination behaves.

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 compact, front-loaded with the core purpose, and every sentence earns its place: what it does, what it returns, how to paginate/filter, and the underlying endpoint. No filler or redundant restatement of the 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 description covers the return format, pagination, filtering, and endpoint despite there being no output schema. It is sufficient for a 5-param, zero-required read-only tool, though it omits details like valid type values or explicit auth notes, leaving a small 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?

Schema coverage is 100%, so the description need not repeat parameter meanings. It adds modest guidance by explaining that before/after are pagination cursors and type is a filter, but this largely restates what the schema already provides rather than adding 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 the specific action 'List incidents' and the resource scope 'for a status page,' matching the tool name while clearly distinguishing it from sibling incident mutation tools and other list tools. The return shape and endpoint further identify this as the read-only incident listing 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?

Provides clear context: this is for listing incidents on a status page and explains how to paginate with before/after cursors and filter with type. It does not explicitly name alternative tools or exclusions, but the intended use is unambiguous from the description and sibling context.

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 read-only, and the description adds pagination behavior via before/after cursors plus the concrete GET endpoint. This is useful beyond the schema, though it does not describe default limits or response shape.

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?

Three short sentences front-load the purpose, then give pagination and endpoint context with no filler. Every sentence contributes.

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 simple read-only list tool with no required parameters, the purpose, pagination, and endpoint are covered. It could mention the return format or default limit, but nothing essential is missing for selecting and invoking it.

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 each parameter is already documented. The description's mention of before/after cursors for pagination reinforces, but does not substantially add to, the schema definitions.

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: lists the metrics configured on a status page. This clearly separates it from sibling listing tools such as statuspal_list_incidents and statuspal_list_services, and the endpoint reinforces the target 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?

The phrase 'List the metrics configured on a status page' gives clear context for when to call this tool (need metrics for a status page). It does not name alternatives or state when not to use it, but no prerequisites or competing conditions are left unexplained.

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 readOnlyHint annotation already covers the safety profile, so the bar for additional behavioral disclosure is lower. The description adds meaningful behavioral context by specifying the endpoint pattern and the response shape (id, name, current_incident_type, children[]), which is especially valuable since there is no output 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?

The description is compact and front-loaded: the primary action and result shape come first, followed by a precise endpoint reference. Every sentence earns its place, with no filler or repetition.

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 simple read-only list operation with one optional parameter, the description is nearly complete. It provides the resource, endpoint, and key returned fields, which compensates for the lack of an output schema. Minor omissions such as pagination or ordering are not critical for this tool's obvious purpose.

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 parameter description already explains that subdomain overrides STATUSPAL_SUBDOMAIN. The main description reinforces that subdomain appears in the endpoint path but does not add significant meaning beyond the schema, so the baseline score 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?

The description uses a specific verb ('List') and resource ('services on a status page'), and even enumerates the returned fields ({id, name, current_incident_type, children[]}). This clearly distinguishes the tool from sibling tools like statuspal_list_incidents or statuspal_get_service_status, and the explicit REST endpoint leaves no 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?

The description clearly conveys the core use case: retrieving the list of services for a status page. However, it does not explicitly state when to prefer this tool over siblings such as statuspal_get_service_status or statuspal_get_status, nor does it mention any exclusions or alternatives. Usage guidance is implied rather than explicit.

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 include destructiveHint=true, and the description adds meaningful context by emphasizing that changes hit the 'LIVE public status page' and by giving the exact PUT endpoint. This warns the agent that modifications take effect publicly, which is useful beyond the structured annotation. It does not contradict 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 compact and front-loaded with the core action, then gives the endpoint and the affected fields. Every sentence earns its place and there is 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?

With 8 parameters fully described in the schema and a destructiveHint annotation present, the description covers the essential operation scope and public impact. It lacks an explicit note about the update response format and does not clarify the relationship with create_incident_update, but for actually invoking the call with correct parameters the definition is largely 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?

Schema description coverage is 100%, so the bulk of parameter semantics lives in the schema. The description's field list (title/type/services/timing) mirrors several parameters but adds no new constraints or format details beyond what the schema already documents.

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 ('UPDATES') and resource ('existing incident on the LIVE public status page'), and enumerates the changed fields (title/type/services/timing). It is clear enough to distinguish from create/delete/get/list siblings, though it does not explicitly demarkate from statuspal_create_incident_update, which could be confused with posting a new incident update entry.

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?

No explicit when-to-use or when-not-to-use guidance is provided. The description implies that this tool is for updating existing incident details, but it does not contrast it with the sibling statuspal_create_incident_update, which seems closely related and could be the right choice for appending a status update.

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