ZEN SecDB

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

Discloses the output structure (date, score, percentile, model) and behavior when no data (empty series). No annotations are provided, so the description carries full burden; it is clear and honest, though it could mention any potential side effects or 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?

Well-structured with clear sections (what, when, inputs, outputs, LLM guidelines). Front-loaded with purpose. Each sentence adds value, though some sections could be slightly more compact.

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 the tool's simplicity (one parameter, list output) and the presence of an output schema, the description fully explains the return structure and edge cases (no data). No additional context is needed.

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 parameter description in the schema is nearly identical to the tool description. The description adds a guideline for handling malformed IDs, but does not significantly augment the meaning of the parameter itself.

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 specific verb 'Get' and resource 'historical EPSS time series' for a CVE, and distinguishes from sibling tool 'vulnerability_score' which provides only current score. Clearly states the tool's function and scope.

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 states when to use (trend analysis, historical comparison) and when not (current score → use vulnerability_score). Also provides guidance for multiple CVEs and malformed inputs.

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?

No annotations are provided, so the description must carry the full burden. It explains that executing a report returns structured results with a summary and data, and notes that it covers public datasets. It also gives error-handling instructions (return not-found error for invalid report IDs). However, it does not explicitly state that the tool is read-only or that it has no side effects, which would be beneficial. The description is still strong, hence a 4.

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 well-organized into clear sections ('What this tool does', 'When to use', 'Inputs', 'Outputs', 'LLM usage guidelines') and is front-loaded with the main purpose. It is concise enough for the complexity, though could be slightly trimmed. Every sentence adds value, earning a 4.

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 the tool's complexity (executing reports with filters, limit, and structured output), the description covers purpose, usage, inputs, outputs, and error handling. It references 'feed_report_catalog' for discovery and provides clear output structure. The presence of an output schema means detailed return values need not be explained, but the overview is sufficient. The description is complete for an agent to use 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 description coverage is 100% (all three parameters have descriptions in the schema). The description's 'Inputs' section repeats those descriptions without adding new meaning. According to the rubric, when coverage is high, the baseline is 3, and no extra value is added here.

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 tool name 'feed_report' is clearly explained: it runs a public ZEN SecDB feed report. The description lists supported datasets (CVEs, advisories, etc.) and explicitly distinguishes from sibling tools by directing users to 'feed_report_catalog' for discovery and to dedicated lookup tools for single CVE/advisory details. The purpose is specific, with a clear verb-resource relationship.

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 when-to-use scenarios (distributions, trends, top-N, aggregated views) and when-not-to-use (single CVE/advisory details, with alternatives). It also instructs to use 'feed_report_catalog' to discover available reports and to not guess report IDs. This gives clear guidance for tool selection.

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?

While no annotations exist, the description covers output format, zero input requirement, and LLM usage guidelines. It is a read‑only catalog operation, though rate limits or idempotency are not mentioned – not critical here.

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?

Structured with headings and clear sections; every sentence adds value. Slightly verbose but still efficient for the level of detail provided.

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 zero parameters and no annotations, the description fully covers purpose, usage, output schema, and LLM guidelines – no gaps remain.

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?

No parameters exist; description confirms no input needed and elaborates on output fields, exceeding the baseline of 4 for zero‑parameter tools.

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 lists available public ZEN SecDB feed reports, using specific verb-resource (list catalog) and distinguishes from sibling feed_report.

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?

Explicit when-to-use (discover report IDs, inspect filters, unsure which report) and when-not (do not invent IDs), with direct reference to sibling feed_report.

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?

No annotations provided, so the description carries full burden. It clearly states that results are based exclusively on the provided package list (not scanning the system). It describes the two outputs (report and summary). It does not mention auth, rate limits, or error scenarios, but for this tool, the key behavioral trait is that it's a static analysis of a user-provided list, which is well communicated.

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 well-structured with clear sections (What this tool does, When to use, Inputs, Outputs, LLM usage guidelines). It is somewhat lengthy but includes necessary details like package listing commands. Every section earns its place, though minor redundancy exists (e.g., the input section repeats the commands). Front-loaded with purpose.

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 the complexity of the tool with 3 parameters, a clear input format requirement, and output schemas (not shown but indicated), the description covers all necessary aspects: purpose, usage, input details with examples, output types, and LLM guidelines. It does not need to explain return values in detail since there is an output schema. 'Contextual Completeness' is fully satisfied.

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 baseline is 3. The description adds significant value: for 'os', it explains to use linux_os to get valid values; for 'packages', it provides exact shell commands for RPM-based, DEB-based, and Alpine distributions, and shows an example of the expected format. This goes well beyond the schema definitions.

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 starts with a clear verb+resource: 'Perform a Linux package vulnerability audit using SecDB.' It specifies analyzing installed packages and returning vulnerability info and a Markdown summary. It distinguishes from siblings like purl_audit (which likely uses PURLs) and linux_os (which provides OS values).

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 includes a 'When to use this tool' section that lists specific use cases. It also provides 'LLM usage guidelines' with explicit instructions: never guess vulnerabilities, call linux_os if os/version unknown, normalize package list, and use report for deeper analysis. It tells when to call a sibling tool (linux_os) to get valid inputs.

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?

Describes that the tool returns an array of OS/version objects with no side effects. Despite no annotations, it fully discloses behavior: it is a read-only retrieval tool. No contradictions noted.

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?

Well-structured with clear sections (what, when, inputs, outputs, LLM guidelines). Every sentence adds value, no redundancy, front-loaded with purpose.

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 the simplicity (no params, no nested objects) and presence of an output schema, the description fully covers all necessary information for correct invocation and understanding of results.

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?

No parameters required, so baseline is 4. The description adds value by explaining the output format in detail, which compensates for the lack of params.

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 that the tool lists supported Linux OS versions for use with linux_audit. It uses specific verb 'list' and resource 'supported Linux OS versions', and distinguishes itself from siblings by being a prerequisite for linux_audit.

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?

Provides explicit guidance on when to use (user doesn't know OS names/versions, unclear info, need validation) and when to call (before linux_audit). It also advises not to guess and to confirm correctness using this tool.

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?

No annotations are provided, so the description carries the full burden. It describes inputs (list of PURLs), outputs (report JSON, markdown summary), and supported ecosystems, but does not explicitly mention non-obvious aspects like idempotency or rate limits. However, it is sufficiently transparent for a read-only audit 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?

The description is well-structured with sections and bullet points, making it easy to scan. It is relatively long but every section serves a purpose; it could be slightly more concise without losing 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?

Given the complexity (multiple ecosystems, input generation, output usage), the description is complete. It covers all needed context: when to use, how to prepare inputs, what outputs to expect, and how to interpret them. The presence of an output schema is noted but the description already explains outputs adequately.

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% for the single parameter 'purls'. The description adds extensive context: PURL format per ecosystem, how to generate them from manifest files, and the requirement to only submit supported ecosystems, far exceeding the schema's brief 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 clearly specifies the tool's action: 'Perform a software package vulnerability audit using SecDB.' It names the resource (software packages by PURL) and distinguishes from siblings like linux_audit or vulnerability_info by focusing on PURL-based auditing.

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 provides explicit guidance on when to use the tool (determining vulnerabilities, advisories, patching needs) and includes detailed input generation instructions per ecosystem. It also advises against guessing and clarifies when to use report vs summary.

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?

No annotations are provided, so the description carries the full burden. It describes the search behavior and output structure, and implies read-only access. While it does not explicitly state 'read-only' or non-destructive nature, the context suggests it is a safe query tool. No contradictions.

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 well-structured with clear sections (What, When, Inputs, Outputs, Guidelines). It is slightly verbose but every section adds value. It could be trimmed slightly without losing meaning.

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 the tool has 4 parameters, no required params, and no output schema, the description is exceptionally complete. It explains all inputs, typical outputs, and provides usage guidance. It covers both what the tool does and how to use it effectively.

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% with descriptions for all 4 parameters. The description adds meaning by explaining the purpose of each parameter, giving real-world examples (e.g., category values like 'exploit', 'nasl') and recommending when to use cve_id vs query. This added context goes beyond the schema.

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 searches for real-world vulnerability sightings, listing specific types (exploit-db, metasploit, Nessus, etc.). It distinguishes itself from siblings like vulnerability_search (which likely focuses on vulnerability metadata) and epss_timeseries (threat 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 'When to use this tool' section with example questions and LLM usage guidelines. It advises when to use cve_id vs query. However, it does not explicitly state when not to use the tool or mention alternatives among siblings.

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?

No annotations are provided, so the description carries the full burden. It comprehensively explains the tool's behavior: what it calculates (decision using four factors), which inputs are user-provided vs automatically looked up, the output fields including a Markdown summary, and the need for user-provided context. No behavioral details are omitted or contradicted.

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 well-structured with clear sections (What, When, Inputs, Outputs, LLM guidelines). It is appropriately sized for the complexity, with every sentence contributing useful information. The most critical information (purpose and when to use) is front-loaded.

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 the tool's complexity (SSVC decision model with multiple inputs and outputs), the description is remarkably complete. It covers the decision logic, all input constraints, output fields, and usage best practices. Since an output schema exists (true), the explanation of return values is sufficient without deep schema details.

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%, with detailed descriptions and LLM instructions already in the schema. The tool description's 'Inputs' section restates parameter names and notes they must be user-provided, which adds minimal semantic value beyond the schema. A score of 3 is appropriate for baseline when schema covers parameters thoroughly.

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 that the tool computes CISA SSVC for a CVE, specifying the exact verb ('Compute') and resource ('CISA SSVC'). It distinguishes from sibling tools by focusing on SSVC prioritization, which is unique among tools like vulnerability_score or vulnerability_search.

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 includes a dedicated 'When to use this tool' section with specific query triggers. It provides explicit instructions for the AI: always ask the user for mission_prevalence and public_well_being_impact, never guess these values, and consider combining with other tools. This provides clear guidance on when and how to use the tool versus alternatives.

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?

No annotations are provided, so the description carries the full burden. It describes the output format (Markdown) and lists fields returned, adequately conveying that it is a read-only retrieval without side effects.

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 well-structured with clear sections and bullet points, front-loading the core purpose. It is slightly verbose but all sentences serve a purpose, making it easy to scan.

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?

Despite having no output schema and no annotations, the description thoroughly explains inputs, outputs, usage scenarios, and integration with sibling tools, fully covering what an agent needs to correctly invoke the 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?

The input schema already describes the single parameter fully (100% coverage). The description adds only the word 'valid' for the CVE identifier, which is minimal extra value beyond the schema.

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 retrieves detailed information about a specific CVE, listing specific data fields. It distinguishes from sibling tools by emphasizing deep inspection of a single vulnerability and suggesting combinations with other tools like vulnerability_score and sightings_search.

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 when-to-use scenarios with example user queries, instructions to call once per CVE, and suggestions for combining with sibling tools. It lacks explicit when-not-to-use statements but implies limitations for bulk queries.

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?

No annotations provided, so description carries full burden. It fully explains the output fields and includes example usage. However, it does not mention authentication, rate limits, or any side effects, though given the tool's nature, these are likely minimal.

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?

Well-structured with separate sections for description, usage guidelines, inputs, outputs, and LLM usage guidelines. Includes clear examples and bullet points; no extraneous content.

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 the simple one-parameter tool with a detailed output schema, the description is fully complete. It covers when to use, input format, output details, and example usage, leaving no 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?

The schema already covers the single parameter `cve_id` with 100% coverage. The description adds format specification (CVE-YYYY-NNNNN) and usage context, providing marginal extra value over the schema.

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 retrieves CVSS and EPSS scores for a specific CVE, with strong differentiation from siblings like `epss_timeseries` and `vulnerability_info`.

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 lists when to use (e.g., 'What is the CVSS/EPSS of this CVE?') and when not to (e.g., for EPSS historical trends, use `epss_timeseries`). Also provides LLM usage guidelines and tool combination suggestions.

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 the full burden. It discloses that results are Markdown-formatted, includes a summary, and searches full-text across multiple data sources. However, it does not mention result limits, pagination, authentication requirements, or whether the tool is read-only, leaving some behavioral 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?

The description is well-structured with clear headings, bullet points, and sections (What, When, Inputs, Outputs, LLM guidelines). It is appropriately detailed without being verbose, though slightly longer than minimal.

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 the tool's complexity (search across multiple vulnerability-related resources) and the presence of an output schema (expected but not shown), the description covers inputs, outputs, and usage context. It mentions combining with other tools, making it complete for most use cases.

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% with one parameter (query) described. The description adds value by explaining it is a free-text search term and listing examples (CVE ID, advisory ID, product name, etc.), which goes beyond the schema 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 clearly states the tool performs a full-text vulnerability search in SecDB and lists specific resources searched (CVE, advisories, exploits, product/vendor data). It effectively distinguishes from sibling tools like vulnerability_info, vulnerability_score, epss_timeseries, and sightings_search through usage guidelines.

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 provides 'When to use this tool' with concrete examples (look up CVE, advisory, exploit, product; search for advisories; exploratory discovery). It also advises combining with other tools for deeper analysis. It lacks explicit 'when not to use' statements, but the guidance is clear.

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