krabbot-devtools

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

With no annotations, the description carries the full disclosure burden. It explains the detection categories (hallucinated names, typosquats, OSV, EPSS, Scorecard), the output format, and even operational context (autonomous agent, free tier). It does not mention rate limits or error behavior, but significant behavior is 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?

The description is multi-sentence but every clause contributes: purpose, rationale, detection methods, output interpretation, and operational note. It is front-loaded with the main action. Slightly verbose but justified by the risk context.

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 simple two-parameter tool with no output schema, the description provides the output format (0-100 risk score), the detection scope, and the recommended usage, making it self-sufficient. Minor gaps include error handling and rate limits, but the 'free tier' note hints at limitations.

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 input schema already documents both parameters with examples and an enum. The description adds context about why the package name matters (LLM hallucination) and how download volume is used, but does not redefine the parameters. Since schema coverage is 100%, 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 opens with a specific verb phrase 'Check whether a software package is safe to install' and clarifies the timing ('BEFORE running npm install or pip install'). It also mentions detection capabilities and the risk score, clearly distinguishing from siblings like check_stack_eol.

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 explicitly states when this tool is essential ('when a package name came from an LLM suggestion') and explains the threat model (slopsquatting). It does not explicitly name alternatives or exclusions, but the context is clear and actionable.

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?

Given no annotations are provided, the description carries the full burden of disclosure. It clearly explains the scoring mechanism (0-100 based on deadline proximity, effective dates, comment-window closures, document class, significance flag) and the filtering behavior. It also discloses autonomous operation ('Operated by an autonomous AI agent (Krab Bot); the free tier is used here'), which is critical for the agent to understand limitations (e.g., free tier constraints).

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 well-structured paragraphs with zero wasted words. The first sentence states the core purpose, followed by context on why the tool is needed (Federal Register noise), the scoring methodology, usage guidance, parameter hints, and an important limitation and operational note. Every sentence 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 tool with no output schema, the description covers all critical aspects: purpose, methodology, filtering, scope, limitations, and operational constraints. The 4 parameters are well-documented in both schema and description, and the context of sibling tools is handled via clear differentiation. There is no missing information that would prevent correct invocation.

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 baseline is 3. The description adds value by explaining how parameters relate to the tool's purpose (e.g., 'Filter by topic (free text), agency (Federal Register slug...), or document type') and by providing concrete examples for each parameter. However, it doesn't elaborate on the 'days' parameter beyond what the schema says, and the 'types' parameter example is clear but the description could further clarify how multiple types interact.

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 uses a specific verb-resource pair ('Check whether... is about to bind or about to close for comment') and clearly distinguishes the tool's unique value: it scores results by deadline proximity and returns only urgent items. This differentiates it from a generic regulation search tool and from siblings like 'check_package_risk' or 'check_stack_eol'.

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 explicitly states when to use the tool ('when asked whether a rule affects a business, what compliance deadlines are coming, or to monitor a regulatory topic on a schedule'). It also provides a clear exclusion: 'US federal only; the score ranks urgency, not whether a rule applies to your specific business.' This guides the agent away from inappropriate uses.

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?

With no annotations provided, the description carries full responsibility for behavioral disclosure. It explains the severity levels: 'critical (past EOL — no security patches), warning (past active support), and ok,' giving insight into what the output means. It also notes 'Operated by an autonomous AI agent (Krab Bot); the free tier is used here,' adding operational context. However, it does not explicitly state whether the tool makes external API calls, whether results are cached, or potential rate limits. Still, the provided details go beyond minimal expectations.

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 four sentences long and front-loads the core purpose in the first sentence, followed by usage example, return semantics, and usage context. It is efficient, but the final sentence about Krab Bot and the free tier is somewhat tangential and could be removed without losing essential functionality. Otherwise, no dead weight.

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-parameter tool with no output schema and no annotations, the description covers the essential aspects: input format (with example), output categories, usage scenarios, and operational context. It lacks explicit details on error handling (e.g., invalid product format or exceeding 25 components), but these are minor for a straightforward check tool. The inclusion of return semantics partially compensates for the absence of an output schema.

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 schema already describes the 'stack' parameter as 'Comma-separated components, each optionally product@version (max 25)' with 100% coverage. The description adds a concrete example ('node@16,python@3.8,postgresql@17'), which is helpful but does not introduce new semantics beyond the schema. With full schema coverage, the baseline is 3, and the example provides a small incremental benefit rather than a major enhancement.

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 clearly states the tool's purpose: 'Check whether components of a software stack are end-of-life, past active support, or affected by CVEs on CISA's Known Exploited Vulnerabilities catalog.' It uses a specific verb ('check'), identifies the resource ('software stack'), and defines the exact scope (EOL, active support, KEV CVEs). It also provides example input and output categories, effectively distinguishing it from sibling tools like check_package_risk, which likely focuses on individual packages.

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 explicit when-to-use guidance: 'Use before recommending or upgrading a runtime, or to audit a Dockerfile or CI config.' It tells users the appropriate automation contexts but does not explicitly mention when not to use it or compare with alternatives. Sibling tools (check_package_risk, find_open_source_bounties) are not referenced, so exclusions are absent. This places it between a clear context (4) and full when/when-not/alternatives guidance (5).

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?

With no annotations provided, the description carries full responsibility for behavioral transparency. It explains the scoring mechanism (0-100 based on stars, age, plausibility, payment-bot presence), the output sorting, and even the operator context (Krab Bot, free preview tier). This goes beyond a typical description, though it does not detail possible side effects or rate limits.

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 sentences, each earning its place: the first states the core purpose, the second explains the scoring and output, the third gives usage guidance and operational context. It is front-loaded with the key action and contains no fluff or repetition.

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?

Given no parameters, no annotations, and no output schema, the description is largely complete. It covers what the tool does, how it works, when to use it, and even operator limitations. The only minor gap is not specifying the exact shape of returned results (e.g., fields included), but 'top results sorted by that score' gives a reasonable expectation.

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 has zero parameters, so the baseline is 4. There is no parameter schema to supplement, and the description appropriately focuses on the tool's behavior rather than parameter specifics. The scoring criteria mentioned are not parameters but internal logic, so no additional meaning is needed.

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 clearly states the tool's purpose with a specific verb and resource: 'Find open-source bounties that are actually likely to pay out.' It also distinguishes from sibling tools (check_package_risk, check_stack_eol) by focusing on bounty discovery rather than risk assessment, and adds a unique value proposition with the credibility scoring.

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 provides explicit usage context: 'Use when looking for paid open-source work worth attempting.' This clearly indicates when to use the tool, though it does not mention alternatives or when not to use it. Since the sibling tools have clearly different purposes, the context is sufficient.

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