Is the internet OK?

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

Annotations already declare read-only, idempotent, open-world, so the bar is lower, yet the description still adds latency expectations, the degraded 'unknown' outcome when no lockfile is parseable, and what the response contains at a high level. It doesn't discuss rate limits or failures on private/missing repos, leaving minor gaps.

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

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

Front-loaded with the core operation and then layered with scope, output meaning, and latency. Dense and nearly waste-free, though the ecosystem list and long compound sentences make it heavier than necessary.

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 burden of explaining return values and does so: the four-level scale plus 'unknown', the prioritization guidance, plain-language exploit impact, and where the full list lives. Nothing an agent needs to call and interpret this correctly is missing.

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

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

Schema coverage is 100% and both parameters are well documented in the schema, including the size trade-off of 'full'. The description adds no additional parameter guidance beyond reinforcing that the default answer is summarized. Baseline 3 is appropriate when the schema carries this much weight.

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

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

Specific verb and resource: 'Checks a public GitHub repo', immediately narrowed by scope (lockfiles at latest commit, every folder, 14 named ecosystems). This is clearly distinguishable from check_stack and the incident-oriented siblings, which deal with different objects entirely.

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

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

Gives clear applicability boundaries: public repos only, needs a readable lockfile, and 'unknown' otherwise. It also signals cost ('a first look at a big repo takes a few seconds') which helps an agent decide when to invoke. It does not, however, name check_stack or explain when that alternative should be preferred.

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 read-only, idempotent, non-destructive, open-world, so the description rightly spends its words elsewhere: the scoring scale (yes/mostly/kind-of/no/unknown), the exact-version precondition for 'unknown', what gets returned (which packages to update and to which version), and a privacy guarantee that only names and versions reach the flaw database. That is genuine context beyond the annotations; only rate limits/response shape are untouched.

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

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

Purpose and matching semantics are front-loaded, and nearly every clause carries information (input formats, scoring scale, sibling routing, privacy). The single dense paragraph with semicolon-chained clauses makes it harder to scan than it needs to be, though little is actually 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 5-parameter, zero-required, no-output-schema tool, the description supplies what an agent needs to call it correctly: three alternative input modes, accepted formats, the meaning of the returned verdict scale, and the mutation/privacy profile. Nothing essential is left to inference.

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

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

Schema coverage is already 80%, so the baseline is 3; the description adds real meaning on top by explaining that an exact pinned version triggers full flaw matching while a range or missing version is only compared against explained incidents, and by noting that a lockfile filename engages the repo check's readers, which separate dev dependencies.

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 opens with a concrete verb and scope ('Checks a project's dependencies and a person's apps') and immediately explains the matching logic (exact-version packages vs. every known flaw; ranges/apps vs. incidents only). It explicitly distinguishes itself from sibling check_repo, which handles public GitHub repos.

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 tells the agent exactly what to supply (packages, product ids, or the raw text of a lockfile, with a list of accepted lockfile names) and routes the public-repo case to check_repo instead. Missing only an explicit statement of when this tool is not appropriate beyond that one routing case.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description earns credit for what it adds: explicit sort order (oldest first), the set of event categories emitted, and the cursor contract for continuation. It does not mention whether `next` is absent when caught up or how far back events are retained, which would complete the polling picture.

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 compact sentences, front-loaded with the what-and-ordering, followed by the continuation instruction. Every clause carries information; no filler.

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

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

For a single optional-parameter read tool with no output schema, the description covers scope, ordering, and continuation well enough to call it correctly. It stops short of describing the shape of an individual event or how `next` is surfaced, which matters slightly more here because there is no output schema to fall back on.

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

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

Schema coverage is 100% and already documents `since` as an ISO date defaulting to the last 7 days, so the baseline is 3. The description adds genuinely new meaning by establishing that `since` doubles as the cursor field fed from a previous response's `next`, which the schema does not state.

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 resource and verb-like behavior ('what changed since a date, oldest first') and enumerates the event types included (incidents created/updated/resolved, service up/down). It is distinguishable from list_incidents by being a change feed rather than a list, 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?

The polling pattern ('keep `next` and pass it as `since` next time to watch') implies the primary use case, but there is no explicit guidance on when to choose this over list_incidents or get_incident, nor any exclusion 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds only that resolved incidents are also returned; it says nothing about what happens for a bad or unknown id.

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, id source and example front-loaded, nothing superfluous.

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?

There is no output schema, and the description does not indicate what the returned incident contains (fields, timeline, severity) or how errors surface for unknown ids. For a simple single-record getter this is a modest but real gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by giving the id's concrete format and a worked example (2026-10-14-nextjs-rce) that the schema's 'The incident id.' does not provide.

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

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

States the resource (one incident) and the lookup key (id), which is enough for an agent to distinguish it from list_incidents, internet_status and the check_* siblings. The verb is only implied, but the intent 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?

Names the two sibling tools that produce valid ids (list_incidents, internet_status), which tells the agent the upstream call. It also clarifies both open and resolved incidents are retrievable. No explicit when-not-to-use 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 readOnly, idempotent, non-destructive, so safety is covered; the description adds genuinely new behavioral context, namely the 5-minute refresh cadence which tells the agent results may be slightly stale. It also enumerates what the response contains (per-service state and group, incidents with remediation).

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 covers purpose, payload, and refresh rate with no filler. The service list is illustrative rather than exhaustive, which keeps it compact, though the ellipsis makes the enumeration slightly loose.

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 correctly carries the burden of explaining return values: summary sentence, per-service state and group, and incidents with recommended action. Only minor gaps remain, such as whether the service list is fixed or user-configured.

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 for the description to clarify; baseline 4 applies. The description does not falsely imply any inputs.

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 resource and scope: the live status of the whole internet, aggregating watched services and open incidents. An agent can tell this is a broad summary rather than a single-incident lookup, but it never names the sibling tools (list_incidents, get_incident, check_stack) it differs from.

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 aggregate nature and 'one-sentence answer' suggest it's a first-stop check before drilling into a specific incident. There is no explicit when-to-use vs when-to-call-get_incident guidance and no stated 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, idempotentHint, and closed-world, so the safety profile is covered. The description adds genuine behavioral value: results are sorted worst-first and each item carries impact, remediation, affected packages/products, and a page link. It could still note whether results can be empty or are bounded.

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 front-loaded sentence that names the resource, ordering, and returned fields with zero filler. The parenthetical examples add disambiguation without bloat.

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?

There is no output schema, but the description compensates by enumerating the fields each incident returns (impact, recommended action, affected packages/products, page). The only gap is the undocumented severity filtering behavior, otherwise an agent has what it needs to call and interpret this tool.

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

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

Schema description coverage is 100% and the single severity parameter is fully documented with an enum, so the schema does the heavy lifting. The description never mentions the severity filter, adding no meaning beyond the schema; baseline 3 applies.

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

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

States a specific verb (list) and resource (open incidents) and elaborates with concrete examples of what counts as an incident (critical flaws, big outages, supply-chain attacks). It does not explicitly distinguish itself from the sibling get_incident, though 'list' vs 'get' is reasonably inferable.

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?

Implicitly scoped to currently open incidents and ordered worst-first, which hints at usage. However, it never says when to pick this over get_incident (fetch one) or check_stack/check_repo, and gives no prerequisites or exclusions.

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