Watchlist

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

Beyond annotations, the description discloses that the watchlist is persisted in a local file, that 'check' is stateful and reports only deltas since the last check, and what kinds of changes are reported: new CVEs, CISA KEV additions, EPSS jumps, and verdict changes. It does not cover permission requirements or concurrency behavior, but the annotations already establish the safety profile and the description adds meaningful operational context.

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

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

The description is three focused sentences with no filler. It front-loads the core resource definition, then explains the key 'check' behavior, and ends with the scheduler usage note. Each sentence contributes useful 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?

The description explains the important 'check' behavior and return content well, which is valuable given there is no output schema. However, it does not describe what add/remove/list return or confirm how those actions interact with the local file, leaving some gaps for an agent invoking non-check actions. It is minimally adequate but not complete across all actions.

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 both parameters are already documented in the input schema, including the action enum and software format examples. The description reinforces the meaning of 'check' and links software entries to am_i_affected, but it does not add much parameter-level detail beyond what the schema already provides. A 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 identifies a specific resource, a saved watchlist of software the user runs, and explains what the 'check' action does. It also distinguishes this from the sibling am_i_affected tool by saying check runs am_i_affected on every entry and reports changes. However, it does not explicitly frame the tool as managing add/remove/list actions, leaving that to the schema.

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 clear usage context: 'check' is for detecting changes since the last check and the same check can be scheduled via the CLI watch command. It implies am_i_affected is the per-entry building block, helping an agent decide between one-off checking and watchlist monitoring. It stops short of explicitly naming when not to use the tool or spelling out add/remove/list usage.

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