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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered structurally. The description adds value by disclosing the shape of the returned evidence chain, which matters because there is no output schema. It still omits return format details, pagination, or any cost/latency context, so it clears the lower annotation-backed bar without going beyond 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?

One sentence with zero filler, and the key content (the evidence chain) is front-loaded immediately. It is tight and scannable, though the missing verb makes it slightly less directive than it could be.

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

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

For a read-only, single-parameter tool with no output schema, the description partially covers the return content, which is the main gap. It is still incomplete on parameter meaning and on routing relative to siblings, so it is adequate but with clear holes.

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 single parameter incident_id has 0% schema description coverage and the description never mentions it or its expected format. Unlike a zero-parameter tool, this definition needs the description to compensate for the undocumented parameter, and it does not.

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 resource (an incident) and the exact content returned: impacted services, root cause, actions and why. This gives an agent a concrete sense of what the tool produces. However, it is phrased as a bare noun phrase and never explicitly distinguishes itself from overlapping siblings like get_blast_radius or rank_suspects, so differentiation is left to inference.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. With sixteen siblings including several that overlap on incident evidence (rank_suspects, get_blast_radius, recent_changes, find_similar_incidents), the agent gets no help deciding when this tool is the right choice.

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 safety (readOnlyHint=true, openWorldHint=false), and the description adds genuinely new behavior: the ranking is full-text with a service-affinity boost, and the response carries root causes and remediation. It does not mention pagination, empty-result behavior, or cost, but the ranking semantics are the non-obvious part and they are disclosed.

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 sentences, zero filler, purpose and mechanism front-loaded before the return-value note. 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?

No output schema exists, and the description compensates by naming what is returned (root causes and fixes). Combined with annotations covering the read-only profile, this is nearly complete for a 3-parameter search tool; only limit/result-count behavior is left ambiguous.

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 0%, so the description must carry the parameter burden. It explains the semantics of 'symptom' (full-text match target) and 'service' (boost signal, not a filter), which is real value beyond the schema, but 'limit' is never mentioned and defaults (limit=3, service=null) go unaddressed.

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: 'Search incident memory' with full-text match on past symptoms and a service-based boost. The mechanism plus the stated return (root causes and fixes) makes the tool's function unmistakable, though it never explicitly names a sibling like explain_incident or rank_suspects to sharpen the boundary.

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

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

Usage is only implied: an agent can infer this is for triage-time recall of past incidents, but there is no statement of when to use it versus explain_incident, rank_suspects, or recent_changes, and 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=false, so safety is covered. The description adds useful scope context (it reports both directions of impact), but says nothing about graph traversal depth, result size, or whether the dependency data is live or cached.

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?

A single front-loaded sentence that defines the two outputs in the order an agent would reason about them, with no filler or redundancy.

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

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

For a read-only, single-parameter tool with no output schema, the description conveys what the answer contains (affected callers, dependencies) and implies no mutation. It is nearly sufficient, missing only a note on identifier format or result granularity.

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?

One parameter with 0% schema description coverage, so the schema alone leaves `service` undefined. The description implies it is the service whose impact is being analyzed via the phrase 'if `service` misbehaves', but never states the expected identifier form or namespace, so it only partially compensates.

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 analysis resource and scopes it precisely into two directional components: upstream callers (who is affected) and downstream dependencies (what it depends on). This lets an agent distinguish it from trace_dependency_path, though it never names or contrasts that sibling 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?

The description is purely definitional; it never says when to reach for this tool versus trace_dependency_path, query_graph, or get_service_health, nor does it state prerequisites (e.g. that it is an incident-triage step). Usage can only be inferred from the sibling set.

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=false, so safety is covered. The description adds genuine behavioral context beyond them: results are de-duplicated into distinct messages with counts plus the latest raw entries, which tells the agent what the response actually looks like. It omits any note on volume limits or windowing, 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?

A single compact sentence with no filler, and the de-duplication detail is front-loaded after the resource. It loses a point only because the colon-list structure reads as a data spec rather than a complete instruction.

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 no output schema and 0% parameter coverage, the description should explain the three inputs and the default 200-line window; it explains none of them. It partially covers the return shape, but an agent still cannot confidently construct a call from this text alone.

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 0% for three parameters (service, lines, contains), so the description carries the full explanatory burden but only vaguely gestures at them via 'recent' and 'distinct messages'. The required 'service' selector and the 'contains' substring filter are never explained anywhere.

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 identifies the resource (recent log entries) and its de-duplicated shape, so an agent can tell it retrieves logs rather than incidents like the sibling tools. However, it is a noun fragment with no verb, and it describes output content more than the operation, leaving purpose only implicitly stated.

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?

There is no guidance on when to reach for this tool versus the incident-oriented siblings (explain_incident, recent_changes, get_service_health), nor any prerequisite or exclusion. The agent must infer usage entirely from the tool name.

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=false, so the safety profile is covered structurally. The description adds no behavioral context beyond the field list — nothing about lookup failures, freshness of on-call data, or scope limitations.

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?

A single tight sentence with no filler. It is front-loaded with the most important returned attribute, though the missing verb makes the opening less orienting than it could be.

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 no output schema, the field enumeration usefully signals what comes back, and annotations cover the read-only nature. However, the parameter remains entirely unexplained and no usage context is given, so it is only minimally 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 0% and the sole 'service' parameter is undocumented in both schema and description. The phrase 'for a service' loosely implies the input's role but gives no format or identifier semantics, so the description does not compensate for the gap.

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 reads as a list of returned fields (owning team, on-call, escalation path, runbooks) for a service rather than a clear verb+resource statement. An agent can infer it retrieves ownership metadata, and it is distinguishable from notify_owner, but the purpose is implied rather than stated.

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 guidance on when to use this tool versus siblings such as notify_owner or get_service_health. There is no mention of prerequisites, escalation context, or exclusions, leaving the agent to guess the trigger.

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=false, so the safety profile is covered. The description adds a genuinely useful trait the annotations lack: the 20-second freshness window. However, it does not explain what 'health' comprises or what happens when the optional service parameter is omitted.

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?

A single front-loaded sentence with no filler; the freshness window is stated up front. It is efficient, though arguably too terse to serve a tool with an undocumented parameter.

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 no output schema, no meaningful annotations beyond read-only, and an undocumented optional parameter, the description leaves the agent guessing about return contents and parameter behavior. It needs more than one clause to be callable with confidence.

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 0% for the single 'service' parameter, so the description carries the burden and fails: it never says whether 'service' selects one service or all, nor what the null default means. 'The services'' plural phrasing actually muddies whether the parameter is required.

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 (live service health) plus the data source (services' stats endpoints), which is clear enough to distinguish from get_logs or query_graph. It stops short of naming a sibling or scope of which services are covered.

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?

There is no when-to-use guidance, no stated prerequisites, and no mention of alternatives such as get_logs or trace_dependency_path for deeper diagnosis. The agent must infer that this is the quick triage check.

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, idempotentHint=false, and destructiveHint=false. The description usefully adds the delivery channel (Slack/Discord webhook) and the conditional 'if configured', which warns the agent the page may silently no-op — real added value. It still omits whether repeat calls re-page the same person and whether any auth is required.

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?

A single front-loaded sentence with no wasted words and the key mechanism (webhook paging) placed before the caveat. It is terse to the point of under-specification, but that is a completeness issue rather than verbosity.

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 side-effecting notification tool with three undocumented parameters, no output schema, and only partial annotation coverage, the description is too thin. It does not explain failure behavior, throttling, or what the caller should supply for message/incident_id.

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 0% for all three parameters, so the description carries the full burden. It only loosely implies that 'service' selects the owning team; it says nothing about message content expectations or what incident_id does when supplied versus omitted.

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 (Page) and resource (the on-call person of the owning team), which is clearly distinct from read-style siblings like get_owner. It does not explicitly name or contrast itself with any sibling, so it stops short of the 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?

There is no when-to-use guidance, no escalation-context cue, and no mention of alternatives such as get_owner (to look up a team) or open_incident (to record the incident). The usage context is only implied by the tool name.

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 disclose readOnly=false, destructive=false, idempotent=false, so the safety profile is covered. The description adds real behavioral value the annotations don't: the call may return a pre-existing open incident for the same services rather than creating a new one. It stops short of saying whether notifications fire or what happens to the incident lifecycle.

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?

A single sentence with a front-loaded verb and a useful parenthetical; nothing is wasted. It is terse to the point of being thin, but structurally it is well formed.

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 mutation tool with no output schema and 0% parameter documentation, the description omits severity options, what the returned incident looks like, and whether side effects such as owner notification occur. An agent could invoke it, but not confidently or 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 description coverage is 0% across four parameters, and the description compensates only by implication ('for these services' gestures at impacted_services). Title, symptom, and the severity default of SEV2 with no enumerated levels are left entirely undocumented, so the description does not close the gap.

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 ('open') and resource ('incident') with a scope qualifier ('in the graph'), which distinguishes it from resolve_incident and explain_incident. It doesn't name those siblings, so it stops short of full differentiation, but the purpose is unambiguous.

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 parenthetical implies the correct context (when you want to open an incident for a set of services) and hints at the dedup case, but there is no explicit when-to-use/when-not guidance and no routing to alternatives like find_similar_incidents before opening.

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, but the description adds real operational context beyond them: a 2s timeout and a 100-row cap, plus the RO_QUERY read-only constraint. It does not describe error behavior or what happens on timeout/truncation, which keeps it 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?

One sentence, front-loaded with the tool's role ('Escape hatch') and packed with the constraints an agent needs. Zero wasted words.

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 no output schema, the description carries the return burden and does state the 100-row cap, so the agent knows roughly what to expect. Missing graph-schema/query-dialect context, which is significant for a free-form Cypher tool in a domain with many structured siblings.

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 0% and the single 'cypher' parameter has no description, so the description must compensate. It does establish that the parameter is a read-only Cypher string (RO_QUERY), which is useful, but it adds no syntax, dialect, or node/edge-naming guidance an agent would need to write a valid query.

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: run read-only Cypher queries. The phrase 'Escape hatch' signals this is the general-purpose fallback, which differentiates it from the task-specific siblings like trace_dependency_path or get_blast_radius, though no sibling is named 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?

'Escape hatch' implies it should be used when the dedicated tools do not cover a need, which is meaningful implied guidance. However, there is no explicit statement of when to prefer this over the many sibling query tools, and no exclusion of use 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 cover the safety profile (readOnlyHint=true, openWorldHint=false), so the bar is lower, yet the description adds real substance: it explains the downstream dependency walk, the blended signals, and that it also returns the top suspect's runbooks and past incidents with fixes. It doesn't state latency or result-size bounds, 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 sentences, both load-bearing, with the core mechanism and the bonus return values front-loaded in a logical order. 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 no output schema, the description reasonably sketches what comes back (ranked suspects, runbooks, past incidents and fixes), but it leaves both input parameters unexplained and gives no hint of ranking scale or output shape, which is thin for a tool whose whole value is its ranked 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 0% for both parameters, so the description carries the full burden and drops it. 'symptom_service' is only loosely inferable from 'symptom', and window_minutes (default 60) is never explained as bounding the change-recency lookback.

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 (rank), resource (root-cause suspects), and the mechanism (dependency-graph walk combining live health, recent changes, centrality). This is clearly distinguishable from siblings like get_blast_radius or find_similar_incidents, which do not rank suspects.

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 a triage/root-cause investigation context but never states when to reach for this over get_blast_radius, trace_dependency_path, or find_similar_incidents, nor any prerequisite input condition. Usage is inferable but not 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 readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuine behavioral context: results are scoped through the dependency graph, not just the named service, and feature flags affecting those services are included. It omits defaults (120 minutes), pagination, and return shape, but with annotations present 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?

A single dense sentence with the returned resource front-loaded and the scoping constraint trailing. No filler, no repetition of the tool name. Slightly heavy on nested parentheticals but 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?

With no output schema the description must convey what comes back, and it does name the returned entities. But for an investigation tool it lacks usage framing, default behavior for the null service case, and any note on ordering or volume limits, leaving material gaps.

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

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

Schema coverage is 0%, so the description carries the param burden. It implicitly maps all three parameters - 'time window' for minutes, 'scoped to `service`' for service, 'plus everything it depends on' for include_dependencies - which is better than nothing. However it gives no default values, units, or format, and never explains what happens when service is null.

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 the resource precisely - deploys and feature-flag flips - and states the scoping semantics (graph traversal to `service` plus its dependencies). An agent can tell this apart from siblings like get_blast_radius or query_graph without opening the schema. It stops short of a clean verb (e.g. 'list'), but the content is unambiguous.

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?

There is no statement of when to use this tool versus alternatives such as rank_suspects, get_blast_radius, or explain_incident. The incident-investigation context is only implied by the sibling set. No prerequisites, no exclusions, no 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 this is a non-readonly, non-idempotent, non-destructive mutation, so the safety profile is covered. The description adds useful context that resolving also writes learnings into incident memory, but it does not disclose consequences of the non-idempotent flag (e.g., duplicate memory entries on retry) or permission requirements.

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 tight, front-loaded sentence with no wasted words. It is efficient, though given the undocumented parameter burden a little more detail would have earned 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 a state-changing, non-idempotent tool with no output schema and four undocumented parameters, the description is thin. It conveys the purpose and one side effect but omits required-input meaning, retry/idempotency behavior, and what resolution changes about the incident's state.

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 0% with 4 parameters (3 required), so the description carries the full burden of explaining them. It only loosely hints at 'summary' via 'what was learned' and never mentions incident_id or root_cause_service, leaving required inputs undocumented in both places.

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 ('Close') and resource ('the incident'), plus a secondary effect ('write what was learned into incident memory'). It reasonably differentiates from the sibling open_incident by implying finality, though it never names or contrasts with any sibling 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?

Usage is implied: this is the tool you call when an incident is over and you have a root cause. There is no explicit when/when-not guidance, no prerequisites, and no mention of alternatives such as explain_incident or verify_recovery that an agent might confuse with it.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is covered. The description usefully adds what state is lost (in-memory state such as connection pools), but it omits the notable fact that dry_run defaults to true, which materially changes what happens on a default call.

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?

A single front-loaded sentence with no filler; the core action leads and the clarifying parenthetical follows.

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, non-idempotent mutation with no output schema and 0% schema coverage, the description is too thin. It should at minimum explain the dry_run default and the required reason/incident_id, none of which appear.

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 0% across four parameters, and the description names none of them. Critically, it never mentions that dry_run defaults to true or that reason is required, so an agent gets no help on the parameters that govern behavior.

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 (restart) and resource (a service's container), and the parenthetical clarifies what restarting actually does. It is distinguishable from the sibling rollback_service, though it does not name that sibling explicitly, keeping it short of a 5.

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?

There is no guidance on when to restart versus when to roll back (rollback_service), or on preconditions such as confirming an incident. The only implied usage is the parenthetical example of stuck connection pools, which is a symptom, not a when-to-use rule.

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=false, so the mutation profile is covered structurally. The description adds real semantic value by explaining what 'rollback' concretely does (redeploy the previous version). However, it omits the critical behavioral fact that dry_run defaults to true, meaning the call does not actually mutate unless explicitly overridden — a safety-relevant detail given destructiveHint=true.

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?

A single front-loaded sentence with zero filler, which is efficient. It is arguably under-sized for a destructive four-parameter operation, but no sentence is wasted.

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

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

For a destructive mutation with no output schema and 0% parameter documentation, the description should cover permissions, reversibility, dry-run behavior, and the required reason/incident context. It covers none of these, leaving the agent materially under-informed before an irreversible action.

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 0% across four parameters, so the description must carry the burden and does not. Only `service` is implied by the prose; the required `reason` string, the `dry_run` default, and the optional `incident_id` linkage are entirely unexplained in both schema and description.

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+resource: it redeploys the prior version of a named service, which is more precise than the bare name 'rollback_service'. It implicitly distinguishes itself from sibling restart_service (a restart vs. a redeploy of the previous version), but never names or contrasts with any sibling 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?

There is no when-to-use guidance, no preconditions, and no mention of alternatives such as restart_service, verify_recovery, or explain_incident. The agent must infer that this is the escalation path after a bad deploy.

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=true, and idempotentHint=false, so the safety profile is covered structurally. The description adds real value beyond that by disclosing latency and mechanism ('takes effect within a second, no deploy'), but it omits critical behavior for a destructive write: that dry_run defaults to true and that a reason is required.

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 short, front-loaded sentence with no filler, and the parenthetical adds genuinely useful operational detail. It is arguably undersized for a destructive five-parameter tool, which is a sizing issue rather than wasted verbiage.

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, non-idempotent mutation with no output schema and zero parameter documentation, the description leaves too much out: the dry_run default that gates whether anything actually happens, why a reason/incident_id is required, and what the effect on live traffic is. Annotations cover safety but not invocation correctness.

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 0% across 5 parameters, so the description carries the full burden and largely fails. The phrase 'on or off' loosely maps to the enabled boolean, but flag, reason, incident_id, and especially dry_run (which defaults to true, meaning a naive call may not actually apply the change) are entirely unexplained.

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 ('turn on or off') and resource ('feature flag'), so an agent knows exactly what state change is being requested. It does not name any sibling or contrast itself with rollback_service/restart_service, but the action is unambiguous and clearly distinct from the read-oriented siblings.

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

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

There is no when-to-use guidance, no stated prerequisites, and no mention of alternatives (e.g. flipping a flag vs. rolling back a service). The only contextual hint is 'no deploy', which implies this is the fast path, but the agent is left to infer the situation in which that matters.

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=false, so safety is covered. The description adds one genuinely useful behavioral trait beyond that — that results include live health per hop — but says nothing about failure modes (e.g. unreachable or non-existent services) or how the path is computed.

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?

A single front-loaded sentence with no filler. The parenthetical 'algo.SPpaths' is internal jargon that adds little for an agent deciding whether to call the tool.

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

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

With no output schema, the description must convey what comes back; 'live health per hop' is a start but leaves the response shape, path-finding semantics (hop count vs. latency), and error behavior unspecified.

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 0% for two required parameters, so the description carries the burden — yet it never explains from_service/to_service. The parameter names are largely self-explanatory, which keeps this at an adequate 3 rather than lower, but no added meaning is provided.

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: computing the shortest call path between two named services, and adds the distinguishing detail that health is reported per hop. It does not explicitly contrast with siblings like get_blast_radius or query_graph, so it falls short of a 5.

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?

There is no when-to-use guidance, no prerequisites, and no named alternative. The agent must infer that this is the tool for path tracing rather than graph querying or blast-radius analysis purely from the name.

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=false, so safety is covered. The description does add real behavior beyond that: this is a blocking poll requiring two consecutive healthy samples, with a timeout exit. It omits the poll interval, whether the call blocks the caller, and whether a timeout is an error or a returned 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?

A single front-loaded sentence with the success criterion and the fallback clause; nothing is wasted and the key condition is not buried.

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 no output schema and no parameter descriptions, the description should say what a call yields on success versus timeout, and roughly how long polling takes between samples. It states the success condition clearly but leaves the return contract and cadence unstated.

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 0%, so the description must carry the load for both parameters. It names `service` and alludes to the timeout, but never explains the service identifier format or confirms the units of timeout_seconds (seconds, per the name and the default).

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: poll live health of a named service until it passes. The two-consecutive-samples criterion and the timeout fallback make the purpose concrete and distinguishable from a single-shot get_service_health, though it doesn't name that sibling 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?

Usage is only implied: 'until healthy ... (or time out)' suggests this is a post-remediation confirmation step, but the description never states when to reach for it instead of get_service_health, 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.