pwned.coffee

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety and network posture are covered structurally. The description adds beyond that by stating exactly what is produced ('a receipt: what you use, the version, affected or not, and the exact upgrade') and by scoping the accepted input formats, which is real behavioral context for a parser-style 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, no filler, and the capability statement is front-loaded before the alternative-tool pointer. The long format enumeration is dense but every item carries routing value; it could be tightened but nothing 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?

There is no output schema, and the description compensates by describing the receipt contents column by column. Combined with the format list, the read-only annotations, and the check_repo pointer, an agent has everything needed to choose and call this tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns extra by making the 'content' parameter concrete — it lists the actual lockfile formats the tool will parse, which is meaning the enum and string type alone do not convey. It does not add format-specific caveats (e.g. partial lockfiles) that would push it to a 5.

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 ('match the packages and versions in a lockfile against incidents that state fixed versions') plus the output ('print a receipt'), which is far more than a restatement of the name. It also enumerates accepted file types, so an agent can immediately tell whether its input qualifies, and it distinguishes itself from check_repo.

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?

Explicitly routes the multi-file case: 'For several files at once, use check_repo.' That is a concrete alternative with a selecting condition. It does not address when a different sibling would be preferable (e.g. lookup_cve for a single package), so it stops short of full when/when-not coverage.

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 useful behavioral context about the returned receipt: affected packages, exact fix commands, actions/images to check, and live incidents for the detected stack.

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 tightly written sentences: the first explains what to send, and the second explains what comes back. It is front-loaded and contains 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?

There is no output schema, so the description must explain the return value, and it does by summarizing the receipt contents. It gives enough context for an agent to understand the tool's purpose and inputs, though it does not detail error behavior or the receipt's exact structure.

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 parameter structure is already well documented. The description adds meaning by enumerating the kinds of files to include, such as lockfiles, Dockerfiles, workflows, wrangler.toml, vercel.json, next.config.*, and compose files.

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 action and scope: send project-defining files in one call and receive a consolidated receipt. It clearly implies a whole-repo check rather than a single-file check, especially through the enumerated file types and 'one receipt' framing, but it does not explicitly name or contrast with check_lockfile.

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 intended usage is implied by instructing the agent to send files that describe what a project runs, and the scope is clear from the file list. However, there is no explicit guidance on when to choose this over check_lockfile or when not to use 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 establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real value beyond that by disclosing the return payload (each change paired with its source, drawn from the same log as /corrections), which is what an auditing agent needs to trust the output. Minor gaps: no mention of result caps or ordering.

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

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

Three short sentences, front-loaded with what the tool returns and followed by the usage cue and input format. The noun phrase in sentence one is dense but every sentence carries distinct information.

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 only two fully-described parameters, read-only annotations, and no output schema, the description covers what is returned, why to call it, and accepted input forms — enough to call it correctly. Result size, ordering, and pagination behavior are the only unaddressed items.

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

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

Schema description coverage is 100%, so the schema already documents both the since format and the optional stack filter. The description restates the accepted timestamp/duration forms and adds '90m' beyond the schema examples, but says nothing about the stack parameter. Baseline 3 is appropriate.

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

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

The description names a concrete resource set (corrections, new tickets, fix-status changes) and a scope (since a point in time), plus the provenance payload each entry carries. It doesn't explicitly distinguish itself from the closest sibling, whats_new, which an agent could reasonably confuse with a 'what changed' tool.

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?

'Use it to audit what the board changed since your last run' gives a clear usage scenario, and the timestamp/duration note tells the agent how to frame the call. No exclusions or named alternatives are given, so the agent must infer when whats_new or todays_specials would 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 the safety profile (readOnlyHint=true, openWorldHint=false), and the description adds real value by enumerating what the payload contains — severity, patch status, fixed versions, timeline, sources — which matters because no output schema exists. It does not say what happens on an unknown id (error vs empty), 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?

A single dense sentence with zero filler; the accepted identifier forms come first and the returned fields follow. The noun-phrase framing ("The incident covering…") is slightly awkward as an opening but costs no clarity.

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 one-parameter, read-only lookup with no output schema, the description covers both input forms and the shape of the response. The remaining gap is failure behavior for an unrecognized id and the boundary with sibling tools.

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

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

Schema coverage is 100% and the single `id` parameter already documents accepted formats (CVE-2026-12345, GHSA-xxxx, HTTP2Shell). The description restates the same accepted identifiers without adding syntax, normalization, or resolution behavior, so it neither compensates nor detracts — baseline 3.

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 makes clear the tool returns an incident record (summary, severity, patch status, fixed versions, timeline, sources) for a CVE/GHSA id or named bug, which is specific and materially clearer than the name alone. It lacks an explicit verb and never names or contrasts with siblings like check_repo or check_lockfile, 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 statement of when to reach for this tool versus the sibling tools, and no preconditions or exclusions. An agent must infer the usage context purely from the tool name and the listed return fields.

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

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

Annotations already cover the safety profile (readOnlyHint, openWorldHint=false), so the bar is lower. The description still adds real context beyond them: the data is 'live ... right now' (a real-time snapshot, not an archive) and it returns severity, patch status and fixed versions. It does not state result volume, refresh cadence, or how far back 'right now' reaches.

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 purpose is correctly front-loaded in the first sentence, but roughly two-thirds of the text is a 60-item id dump that is hard to scan and largely bulk. The information is useful but poorly structured and oversized relative to the one-parameter 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?

A single optional parameter with full schema coverage, safety annotations, and no output schema: the description explains what the returned records contain and what the filter accepts, which is enough to call it. Missing only edge details such as result count, time window and pagination behavior.

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

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

Schema coverage is 100% and the schema already explains the array param with an example, so the baseline would be 3. The description earns an extra point by enumerating the accepted stack ids, which the schema does not do (zero enums), giving the agent the actual valid vocabulary.

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 opening sentence names a concrete resource (live security incidents: CVEs, breaches, supply-chain compromises) with the payload fields it returns. It's clear what the tool fetches, but it never contrasts itself with siblings like lookup_cve or whats_new, so the agent must infer the distinction.

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

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

The line 'Pass stack ids to see only what touches your stack' gives filtering usage, and 'Omit for everything' lives in the schema. There is no explicit when-to-use-this-vs-alternatives guidance (e.g. use lookup_cve for a specific CVE, whats_new for changelogs), leaving routing to inference.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: results are ordered newest-first and cover both created and updated incidents, which affects how an agent interprets the output. It omits any result-cap or pagination 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?

Three short sentences, zero padding, and the resource definition plus ordering are front-loaded before the usage hint and format list. Every sentence carries distinct information.

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

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

For a two-parameter, single-required, read-only tool with no output schema, the description covers resource scope, delta semantics, ordering, and accepted input formats. Only edge behavior (result caps, whether the stack filter is mandatory-adjacent, handling of resolved incidents) is left 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 coverage is 100%, so the baseline is 3. The description still adds value by documenting a relative-duration format ("90m") that the schema does not list, clarifying that minute granularity is accepted. The optional stack filter remains schema-only, which keeps this below a 5.

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 — incidents created or updated since a point in time — plus the ordering (newest first), so the agent knows exactly what comes back. It does not name or distinguish itself from the sibling diff_since, which serves a potentially overlapping delta role, 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?

"Use it to re-check only what changed since your last run" gives a clear, concrete usage context. No explicit exclusions or alternative-tool routing are provided (e.g., when to prefer diff_since or check_repo), so it stops short of a 5.

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