Rootpath MCP Server

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

Annotations already declare this a non-read-only, non-idempotent, non-destructive mutation, and the description adds that a dependency edge is what gets persisted plus a hard evidence requirement. It does not disclose what happens on a duplicate add (relevant given idempotentHint=false) or whether the edge affects blast-radius/incident analysis.

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, the core action first and the evidence constraint second; nothing is wasted or 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?

Adequate for a simple 4-param mutation with no output schema, but an agent still lacks guidance on the undocumented `optional` flag, duplicate handling, and whether recorded edges are validated or rejected when inconsistent.

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 usefully defines caller, callee, and the expected evidence format (file and key or line), but leaves the `optional` boolean completely 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?

States a specific verb and resource — recording a caller→callee edge — which is clearly distinct from read-side siblings like trace_dependency_path, query_graph, and get_blast_radius. It stops short of explicitly naming those siblings as the read-only alternative.

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 by the name and the write semantics; the description never says when to add a dependency versus querying the graph, nor whether duplicates or self-edges are acceptable. The one constraint given ('evidence must say where you saw it') is a parameter requirement rather than 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 that this is a non-read-only, non-idempotent, non-destructive mutation. The description adds only that the runbook is plain text; it does not disclose what happens on repeated calls, whether attaching can overwrite an existing runbook, or what permissions are 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?

The description is a single front-loaded sentence with no wasted words. Its brevity is appropriate for the sentence itself, even though more content is needed elsewhere.

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 four-parameter mutation tool with no output schema and no parameter descriptions, the definition is too sparse. It leaves unresolved how runbook_id and title are used, whether attachment replaces existing data, and what a successful call returns.

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 must compensate for four undocumented required parameters. It clarifies that "steps" are plain-text and that the runbook is attached to a service, but says nothing about runbook_id or title.

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 clear verb and resource: "Attach a runbook" to a service, and clarifies that the runbook consists of plain-text steps. It does not explicitly distinguish this tool from siblings, but its purpose is specific enough for an agent to understand.

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 states what the tool does but gives no guidance on when to use it, when not to use it, or which sibling tools are alternatives. The agent must infer usage entirely from the single sentence.

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 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=true and openWorldHint=false, so safety and locality are covered. The description adds value by stating what the payload contains and the duplication-avoidance purpose, but says nothing about result size, pagination, or freshness for what is presumably a large graph-wide read. That leaves real gaps for an overview tool.

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

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

Two sentences: the first front-loads what is returned, the second gives the call-timing advice. No filler, though the leading clause is slightly ornamental where a verb-led sentence would be sharper.

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 carry return-value meaning, which it partly does by enumerating the entity types. However, for a graph-wide overview it omits scale/shape concerns (volume, truncation, whether results are summarized or exhaustive) that an agent needs to use the output correctly.

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

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

The tool takes zero parameters, so there is nothing to specify; baseline is 4. The description appropriately spends its space on output expectations instead of inventing argument guidance.

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 enumerates the returned inventory (per-label node counts, services with owner and dependencies, teams, flags), which tells an agent exactly what this resource is. It lacks a crisp action verb, and 'What the graph already knows' is slightly abstract, but the concrete content list keeps it from being vague relative to siblings like query_graph.

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?

Directly instructs 'Call this before mapping so you update instead of duplicating,' giving a clear trigger and rationale. It stops short of naming alternatives (e.g., query_graph vs. upsert_service), but the intended position in a workflow is unambiguous.

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

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

Annotations already 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 readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the bar is lower; the description adds that `at_iso` defaults to now, which explains the temporal behaviour. However it does not disclose what happens on a duplicate recording (idempotentHint=false suggests new records are appended, but that is left for the agent to infer), nor that unknown `kind` values are apparently unsupported despite the schema accepting any string.

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; the kind-first structure means the agent learns the discriminator before the per-kind fields. The parenthetical enumeration is dense but readable. Only minor cost: the reader must parse nested parentheses to extract which fields belong to which kind.

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 9-parameter mutation tool with 0% schema description coverage and no output schema, this is roughly adequate but not sufficient: the required `author` and the optional `note` are undocumented, and nothing is said about the return value or whether the record is visible to recent_changes afterwards. It covers the discriminating parameters well but leaves the mandatory identity field unexplained.

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 must carry the load, and it does most of it: it maps the deploy fields (service, version, prev_version) and flag fields (flag, enabled) to their respective kinds and specifies `at_iso` as ISO 8601 defaulting to now. It omits the required `author` parameter entirely and never mentions `note`, which is a real gap given that author is one of only two required fields, costing a point.

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 (Record) plus the two discriminated resource shapes: a deploy (service, version, prev_version) and a flag flip (flag, enabled). An agent can distinguish it from read-only siblings like recent_changes or get_logs, though it never names a sibling explicitly. The kind-discriminated field grouping is precise enough to guide the call.

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 — the description tells you which kind to pick for a deploy vs a flag flip, which is real intra-tool routing guidance. But it never says when to record a change versus simply reading recent_changes, nor whether this is for changes you performed or changes observed in an incident timeline. No prerequisites or exclusions are stated.

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

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

Annotations already declare readOnly=false, destructive=false, and notably idempotent=false, so the description need only add mutation context. It adds the key fact that registration couples the flag to affected services, but says nothing about duplicate-flag behavior, which matters given idempotent=false.

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

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

One tight sentence with zero padding, and the resource is front-loaded. Brevity is somewhat at the expense of the missing parameter and usage detail, but the sentence itself earns its place.

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

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

For a non-idempotent mutation with four undocumented parameters and no output schema, a single sentence is not enough. An agent lacks guidance on required fields, duplicate handling, and what registration returns or affects.

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 four title-only parameters. The description clarifies 'flag' and 'affects' (the services whose behaviour changes) but leaves 'team' and 'description' completely unexplained in both schema and prose.

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 ('Register') and resource ('a feature flag and the services whose behaviour it changes'), which is more informative than the bare name. It does not explicitly distinguish itself from the sibling set_feature_flag, so the register-vs-toggle split 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 set_feature_flag or any other sibling. The agent must guess that this is for declaring a new flag plus its blast-radius services rather than changing a flag's value.

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 declare a non-read-only, non-idempotent mutation, and the description echoes 'create or update' but adds no operational context: whether omitted fields clear existing values (channel/on_call default to empty strings), whether unknown teams are auto-created, or whether this overwrites membership wholesale. For a non-idempotent write with zero schema documentation, that is a meaningful 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?

A single front-loaded sentence enumerating the managed fields with no filler. It is efficient, though arguably too terse for a five-parameter mutation.

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?

A non-idempotent write tool with no output schema, no parameter documentation, and unknown overwrite semantics needs more: what is returned, what is replaced, and what happens on invalid input are all unaddressed.

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 must compensate. It does gloss the fields ('who is on call now' for on_call, 'the team it escalates to' for escalates_to), but gives no format detail for members (emails? usernames?) or channel, and does not explain the empty-string/null defaults.

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 pair ('Create or update') and resource ('team'), and enumerates the fields it manages (channel, members, on_call, escalates_to). This distinguishes it from the read/diagnose siblings, though no sibling covers the same resource so differentiation is easy.

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 call this versus alternatives, no prerequisites (must the team already exist?), and no mention of who should invoke it. The agent must infer everything about timing and conditions.

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=false and destructiveHint=false, so the safety profile is largely covered. The description adds that the owning team may be created or updated and clarifies tier meaning, but it does not disclose update overwrite behavior, permissions, or response behavior.

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

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

The description is two compact sentences with the core action front-loaded and the ambiguous tier field clarified immediately. There is no wasted text.

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 five-parameter mutation tool with no output schema, the description is too thin. It omits update semantics, return expectations, and most parameter meanings, leaving the agent dependent on sparse schema titles and annotations.

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 needs to compensate. It only clarifies tier values and briefly references the owning team; it leaves name, team, description, and internet_facing semantics mostly undocumented beyond their schema titles.

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: 'Create or update a service.' It also hints at the owning-team side effect, but it does not differentiate the action from sibling tools such as set_team or other service lifecycle tools.

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

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

The description gives no explicit guidance on when to use upsert_service versus set_team, add_dependency, restart_service, or rollback_service. It implies a create/update operation but provides no alternatives, prerequisites, or 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=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.