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

Annotations already declare write (readOnlyHint=false), safe (destructiveHint=false) and open-world behavior, and the description adds meaningful context beyond that: the incident is public, it starts immediately in INVESTIGATING, and a version-specific caveat (Kener 4.1.7 and earlier do not email subscribers, #886) warns of a surprising side effect.

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

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

Three sentences, front-loaded with the primary action and only the optional attachments and the caveat following. Nothing is wasted, though the issue-reference aside is slightly tangential to invocation.

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 need no explanation, and the description covers purpose, optional inputs, and a notable behavioral quirk. For a single required-parameter creation tool it is nearly complete, lacking only explicit permission/visibility details.

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 five parameters, establishing a baseline of 3. The description adds only a small pointer (tags come from list_monitors) and otherwise repeats schema-level facts like the default INVESTIGATING state and optional first update.

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 gives a specific verb and resource ('Create a public incident') plus scope ('starting now, in state INVESTIGATING'), which clearly differentiates it from the read-oriented siblings (list_incidents, get_incident) and resolve_incident. It also names list_monitors as the source of monitor 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?

Usage is implied rather than spelled out: optional behaviors (attach monitors, post a first update) and the direction to get tags from list_monitors give some context, but there is no explicit when-to-use guidance relative to post_incident_update or resolve_incident, and no exclusions.

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 openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context by specifying that the incident's update timeline is included and ordered oldest first, which is not stated by 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 a single, front-loaded sentence with no wasted words. It efficiently communicates the core action and the notable return ordering 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 low-complexity, single-parameter read-only tool with full schema coverage, annotations, and an output schema, the description provides enough context for correct invocation. It states what is fetched and adds the timeline ordering, with no critical gaps for this tool's complexity.

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 single incident_id parameter is fully documented in the schema as a Kener incident ID. The description adds no further parameter semantics, so the baseline score of 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?

The description states a specific verb ('Get') and resource ('incident'), and explicitly scopes it to one incident rather than a list. This distinguishes it from list_incidents, create_incident, resolve_incident, and post_incident_update 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?

Usage is implied: retrieve a single incident by ID, as opposed to listing incidents. However, the description does not explicitly state when to use this tool versus alternatives or any prerequisites, leaving the agent to infer the selection 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 cover the safety profile (readOnlyHint=true, openWorldHint=true), so the description only needs to add query behavior — and it does, disclosing the newest-first ordering and the non-obvious default of hiding RESOLVED incidents, which an agent could otherwise get wrong. It says nothing about pagination or result volume, 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?

Two short sentences with zero filler; the scope constraint and the default filter are front-loaded in the order an agent needs them. Every clause 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, so return values need no explanation, and annotations cover safety; with only two fully documented parameters, the description supplies the remaining needed context (ordering and default filtering). It is close to complete, though it omits any note on result-set size or paging behavior.

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 both parameters carry defaults and descriptions, so the schema does the heavy lifting. The description's 'by default only open (not RESOLVED)' largely restates include_resolved's schema description rather than adding new semantics, so the baseline 3 applies.

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

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

States a specific verb+resource ('List incidents') plus two scope facts: ordering ('newest first') and the default filter ('only open (not RESOLVED)'). The plural 'list' form is inherently distinct from get_incident/resolve_incident, but no sibling is named, so it falls short of the explicit differentiation a 5 requires.

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 default-filter sentence implies when the tool is appropriate (browsing open incidents) and hints that include_resolved is the escape hatch, but it never states when to reach for get_incident, list_monitors, or any other sibling, and gives no exclusions or prerequisites.

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 openWorldHint=true, so the safety profile is covered. The description adds the returned field set and the cross-tool purpose, but says nothing about the hidden-monitor behavior or result volume, which is a modest but not severe gap.

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 with the core purpose front-loaded and no filler. The second sentence is terse but earns its place by pointing at a sibling workflow.

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 spelled out, and annotations carry the read-only safety signal. For a zero-required-parameter lister, the definition is adequate, with only the include_hidden semantics left entirely to the schema.

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

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

Schema description coverage is 100%, so include_hidden is already documented with its default in the schema. The parenthetical field list describes output, not the parameter, so the description adds no meaning beyond the structured field; 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?

The description states a specific verb ('List') and resource ('the monitors on this Kener instance') and even enumerates the fields returned (tag, name, status, type, category). It partially differentiates from siblings by tying the output to create_incident, though it doesn't explicitly contrast itself with list_incidents.

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 line 'Use the tags with create_incident' gives one concrete downstream use case, implying when an agent would call this tool. However, it offers no when-not guidance and doesn't compare against sibling tools like list_incidents, leaving selection largely 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 declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the mutation safety profile is covered. The description adds real value beyond them: the supplied state becomes the incident's current state, and the version-specific caveat that API updates do not email subscribers on Kener 4.1.7 and earlier (with issue reference). It does not cover auth/permission requirements or reversibility, so it falls 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?

Three short sentences, zero filler, and the core action is front-loaded ahead of the sibling pointer and the version caveat. Every sentence 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, return values need not be explained, and the description covers the action, its state side effect, the closing alternative, and a notable behavioral caveat. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, including the enum for state, so the schema already documents all three parameters; baseline 3 applies. The description only adds the semantic point that the state value becomes the incident's current state, which is minor 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 states a specific verb and resource ('Post a public update on an incident and set its state'), explicitly names the sibling it is not for ('To close an incident, use resolve_incident'), and clarifies the side effect that the supplied state becomes the incident's current state.

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-not guidance plus the alternative tool by name ('To close an incident, use resolve_incident'), so an agent can route between post_incident_update and resolve_incident without inspecting either schema.

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 (not readOnly, non-destructive) but the description adds valuable beyond-annotation detail: that it closes the incident and sets end time, and a versioned caveat about subscribers not being emailed on 4.1.7 and earlier (with issue reference). That's strong 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?

Three sentences, front-loaded with the action, then mechanism, then a caveat. Zero 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?

Output schema exists so return values needn't be explained; annotations carry the safety profile and the description fills the remaining gaps (side effects, end time, notification caveat). Complete for a two-param 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 documents both comment and incident_id well. The description adds no parameter-level syntax beyond noting the default comment exists implicitly; 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+resource and disambiguates from the sibling post_incident_update by explaining that resolution is implemented as a state RESOLVED update. The mechanism is clear, though it doesn't explicitly say 'not post_incident_update' as a routing hint.

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?

Clearly implies use when closing an incident versus post_incident_update, and explains the implementation equivalence with Kener's semantics. No explicit when-not statement, but the mechanism note gives solid context.

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