ZEN SecDB

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 the return structure (series with date, score, percentile, model), ordering by date, and handles the empty-series edge case. However, it does not explicitly state that the tool is read-only or describe any potential side effects, which is a minor gap for a retrieval 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 clear headers: purpose, when to use, inputs, outputs, and LLM guidelines. It is detailed but not verbose; each sentence serves a purpose, and the most critical information 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?

The tool has only one parameter, an output schema, and no annotations. The description covers everything needed: what the tool does, when to use it, input format, output structure, and edge-case behavior (no history). It also distinguishes from a sibling tool, making it contextually complete.

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 adds value by specifying the CVE format ('CVE-YYYY-NNNNN') and providing guidance on handling malformed IDs (asking the user to correct). This goes beyond the schema's minimal 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 opens with a specific verb and resource: 'Get the historical EPSS time series for a specific CVE.' It clearly identifies the tool's scope (historical time series) and differentiates from the sibling `vulnerability_score` by explicitly stating that tool covers current EPSS scores.

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?

Includes a dedicated 'When to use this tool' section listing concrete user intents (e.g., 'EPSS trend over time', 'whether EPSS spiked or dropped') and provides an explicit alternative: 'If the user only wants the current EPSS score, use `vulnerability_score` instead.' Also includes LLM-specific directives like never guessing values and handling malformed CVE IDs.

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 of behavioral transparency. It discloses the purpose, describes the output structure (summary and report), notes that 'limit' is only applied 'when supported by the selected report,' and specifies error handling: 'If the selected report does not exist, return a clear not-found error instead of guessing an alternative.' This goes beyond the schema in explaining 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?

The description is comprehensive yet efficiently structured with clear sections: 'What this tool does,' 'When to use this tool,' 'Inputs,' 'Outputs,' and 'LLM usage guidelines.' Each section serves a specific purpose, front-loads the core action, and avoids redundant 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?

The description fully equips an agent to decide when to use the tool, how to discover valid report IDs, what parameters are available, what output format to expect, and how to handle missing reports. The presence of an output schema is complemented by the description's explanation of summary vs. report structure, making the context complete for 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%, but the description adds critical usage semantics: it advises using 'feed_report_catalog' to discover supported input parameters, warns not to guess report IDs, and clarifies that the 'limit' parameter is conditional on report support. This adds practical value beyond the raw 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 immediately states 'Run a public ZEN SecDB feed report' and elaborates with 'Executes a predefined report on ZEN SecDB public feed data and returns structured results for analytics, trends, distributions, and top-N summaries.' It clearly distinguishes from siblings by explicitly saying 'Do not use this tool when the user asks for details about a single CVE, advisory, or exploit. Use the dedicated lookup tools instead.'

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 bullet points for appropriate use cases, and a 'Do not use' section pointing to alternatives. It also instructs to use 'feed_report_catalog' for discovering reports and parameters, and warns against guessing report IDs. This provides explicit when-to-use and 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?

No annotations are provided, so the description carries the full burden. It clearly indicates a read-only catalog operation ('List','Returns') and describes the output structure. It does not mention auth, rate limits, or side effects, but for a zero-input, non-destructive listing tool, this is sufficient 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 well-structured with clear markdown sections (What this tool does, When to use, Inputs, Outputs, LLM usage guidelines) and front-loaded purpose. Despite length, every sentence provides actionable guidance with no redundancy.

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 zero-parameter catalog tool, the description fully covers purpose, usage, inputs, outputs, and relationship to the sibling feed_report. The output section describes the report objects, and the guidance on not inventing IDs adds important safety context.

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 schema coverage is 100% and the baseline is 4. The description explicitly reinforces this with 'This tool does not require any input.' This adds clarity beyond the empty 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 opens with 'List available public ZEN SecDB feed reports' and explains it returns a catalog of report identifiers, descriptions, and input parameters. It explicitly distinguishes from the sibling tool feed_report by stating it enables discovery of reports executable through 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?

Includes a dedicated 'When to use this tool' section with concrete criteria (e.g., user asks what reports are available, need to discover report ID, inspect filters). LLM usage guidelines add explicit direction: 'Use this tool before feed_report whenever the correct report ID or supported parameters are not already known,' indicating when to use versus the alternative.

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 behavioral disclosure burden. It clearly states that 'audit results are based exclusively on the package list provided by the user,' setting expectations about scope and limitations. It also describes the two outputs (report and summary) and notes the summary is ready-to-show Markdown, which is valuable contextual information.

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 structured with clear headings, bullet points, and code blocks. It is longer than average, but every section earns its place: the one-line summary front-loads the purpose, and the subsequent sections provide necessary commands, usage context, and output details. No redundant or filler sentences exist.

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 covers input preparation (exact commands per distro), validation (call linux_os for valid values), normalization (one entry per line), output interpretation (report vs. summary), and behavioral caveats (exclusivity on provided packages). Combined with the output schema existence and high schema coverage, this tool is fully specified for an agent to invoke 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?

Although the schema already covers all three parameters, the description significantly enriches them. For 'packages' it provides per-distro commands and an example format; for 'os' and 'version' it points to linux_os to obtain authoritative values. This goes well beyond the schema descriptions, making the parameters actionable.

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 and resource: 'Perform a Linux package vulnerability audit using SecDB.' It clearly distinguishes this tool from sibling linux_os by explicitly instructing users to call linux_os for valid OS values. The scope (analyzing installed packages and returning vulnerability info plus a Markdown summary) is precise and 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?

A dedicated 'When to use this tool' section lists three concrete use cases (known vulnerabilities, affected hosts/VMs/containers/base images, patching needs). It explicitly directs users to first call linux_os when os/version values are unknown, and provides exact package-list generation commands for RPM-, DEB-, and Alpine-based systems. The LLM guidelines further clarify when to always use 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?

With no annotations provided, the description carries the full burden. It discloses that the tool requires no input, returns an array of objects, and shows the output format with an example. It also clarifies its non-destructive, informational nature and warns against guessing OS identifiers. It could explicitly state there are no side effects or that it is a static list, but the behavior is well understood from the description.

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 an example. It is longer than necessary but each section adds value: what it does, when to use, inputs, outputs, and LLM guidelines. It is front-loaded with the main 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?

The description is complete given the tool's simplicity. It fully explains the purpose, output format, and usage context, and the inclusion of an example provides concrete guidance. Since there is no input schema beyond '{}', there are no gaps, and the output is fully described.

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, and the description explicitly states 'This tool does not require any input.' This exceeds the baseline for 0-parameter tools by confirming there is nothing to provide, eliminating any ambiguity.

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 'List supported Linux operating systems and their corresponding versions for use with the linux_audit tool.' It specifies the exact resource (supported OS/version pairs) and distinguishes itself from sibling tools like linux_audit by noting it provides the valid inputs for that 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?

The description explicitly provides 'When to use this tool' with bullet points, states it 'should typically be called before linux_audit whenever parameters are uncertain,' and includes LLM usage guidelines that clarify when to use it for validation and correction. This is thorough alternative/context 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?

No annotations are provided, so the description carries the full burden. It discloses that results are based exclusively on the provided package list, that unsupported ecosystem PURLs will be ignored, and what outputs to expect (report and summary). This provides strong behavioral transparency beyond basic operation.

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 (What, When, Supported ecosystems, Inputs, Outputs, LLM guidelines). While lengthy, every section earns its place by providing essential details like examples and manifest file sources. It is informative without being redundant.

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 (one parameter but many ecosystem variations), the description is complete: it covers supported ecosystems, input generation, output format, and usage rules. With an output schema present, it doesn't need to detail return structure, but it still mentions the two outputs. This is exceptional contextual coverage.

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?

Although schema coverage is 100%, the description adds substantial meaning: it explains what PURLs are, gives examples for each supported ecosystem, and lists manifest files to generate them from. This goes far beyond the schema's bare 'List of Package URLs' and gives the agent concrete guidance for constructing valid 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?

The description clearly states the tool performs a vulnerability audit on a list of PURLs, returning vulnerability information and a Markdown summary. It uses specific verb+resource ('Perform a software package vulnerability audit') and distinguishes from sibling tools by focusing on PURL-based package audits.

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 says when to use this tool (e.g., when user wants to know if dependencies contain known vulnerabilities), and provides 'LLM usage guidelines' such as 'Never guess whether a package is vulnerable — always call this tool.' It also clarifies which ecosystems are supported, giving clear usage context.

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, the description fully discloses the tool's read-only character implicitly, enumerates the sources it covers, describes the output shape (array with cve_id, status, category, reference, details), and gives operational guidance about valid enum values. It doesn't mention rate limits or pagination, but otherwise provides rich behavioral context 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 long but tightly structured with headers (What, When, Inputs, Outputs, LLM usage guidelines) and front-loads the core purpose in the first sentence. No filler or repetition; every section contributes actionable detail, though it could be slightly trimmed 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?

For a search tool with four optional parameters and no output schema, the description covers purpose, use cases, parameter semantics, output structure, and usage heuristics. It even includes example queries and enum guidance, leaving little ambiguity for an agent about when and how to invoke it.

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?

Input schema already documents all four parameters at 100% coverage, and the description reinforces this by defining each parameter with examples (e.g., 'category' values like exploit, nasl, advisory, scanner, poc, social, misp) and providing heuristics for choosing between cve_id and query. The description adds contextual meaning beyond the schema descriptions.

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 clear verb+resource statement ('Search real-world vulnerability sightings in SecDB') and enumerates specific content types (Exploit-DB, Metasploit, scanner plugins, advisories, social media, MISP) that clearly distinguish it from sibling tools like vulnerability_info 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 'When to use this tool' section lists concrete user questions that should trigger this tool, and the LLM usage guidelines advise using cve_id for targeted queries and query for broad searches. It stops short of naming sibling alternatives or explicitly saying when not to use it, so not a full 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, the description carries the full burden. It discloses that the tool depends on user-provided context values, warns against guessing them, and explains the output includes a summary for interpretation. It doesn't cover potential errors, network behavior, or rate limits, but those are less critical for a calculation tool; the provided guidance is strong.

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 organized with clear headings (What, When, Inputs, Outputs, LLM usage guidelines) and is front-loaded with the main purpose. Each section is purposeful—no wasted words. Length is justified by the complexity of SSVC inputs and the need for LLM-specific instructions.

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 covers the full context: what the tool does, when to use it, all three required parameters with requirements, output fields (including summary), and usage guidance. It even suggests combinations with sibling tools. The presence of an output schema lowers the need to explain return types, but the description still furnishes them, making it complete.

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 mission_prevalence and public_well_being_impact already have exhaustive descriptions with allowed values. The tool description reinforces these with concise 'M/S/E' and 'M/A/I' notation and adds the critical semantic that these must be user-provided. This adds value beyond the schema by operationalizing the parameters.

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+resource: 'Compute CISA SSVC for a CVE.' It clearly states the decision outputs (Track, Track*, Attend, Act) and distinguishes this tool from siblings like epss_timeseries or vulnerability_score by focusing on the SSVC prioritization model.

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 'When to use this tool' section explicitly lists user intents (urgency of remediation, CISA SSVC priority, structured decision model). It also provides exclusions/prerequisites by insisting the user must supply mission_prevalence and public_well_being_impact, and names alternative/complementary tools (vulnerability_score, sightings_search).

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, the description fully carries the behavioral disclosure burden. It explains the tool retrieves a record, returns structured Markdown, notes conditional data (EPSS, exploit/patch 'if present'), and warns not to hallucinate details. This is transparent about what the tool does and 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 well-structured with clear sections (What, When, Inputs, Outputs, LLM guidance). Every section adds value and the length is appropriate for the complexity of the tool. No fluff or redundant 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 there is no output schema, the description thoroughly covers return values (Markdown fields, severity metrics, affected products, etc.). It also addresses multi-CVE usage and integration with sibling tools, making the description complete for an agent to select and invoke the 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%, and the description's input section simply restates the schema's CVE format (CVE-YYYY-NNNNN). It adds marginal value beyond the schema by noting the ID must be valid, but doesn't provide additional semantics or usage constraints beyond what's already in the structured definition.

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 'Get detailed information about a specific CVE', clearly identifying the verb (get/info), resource (specific CVE), and scope (detailed vulnerability record). It enumerates the exact data returned, distinguishing this from sibling tools like vulnerability_search and vulnerability_score.

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 this tool' section provides example user queries and states 'Always prefer this tool when the user needs factual information about a specific CVE.' It also gives guidance for multiple CVEs (call once per CVE) and suggests complementary tools, though it doesn't explicitly state when not to use 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?

With no annotations provided, the description carries the full behavioral burden. It discloses the exact fields returned, provides a natural-language example of the cvss_explain field, and explicitly warns the LLM never to guess CVSS/EPSS values. It does not mention rate limits or failure modes, but for a read-only lookup tool this is strong transparency.

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 section headers: tool purpose, what it does, when to use, inputs, outputs, and LLM usage guidelines. Every section serves a purpose, and the example explanation is illustrative without being redundant.

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 required parameter) and the presence of an output schema, the description is contextually complete. It covers use cases, alternative tools, combination strategies, and critical LLM guidance (never guess, call per CVE).

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 cve_id with 100% coverage, so the baseline is 3. The description adds only a 'valid' qualifier (CVE-YYYY-NNNNN) and a call-per-CVE guideline, but no substantive new parameter semantics 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 opens with a specific verb+resource statement: 'Get CVSS and current EPSS score for a specific CVE.' It clearly differentiates this tool from siblings like epss_timeseries (historical trends) and vulnerability_info/vulnerability_search by focusing on the risk snapshot for a single CVE.

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 'When to use this tool' section gives explicit example user queries, names an alternative tool for EPSS historical trends, and suggests combining with sightings_search or ssvc_calculator for fuller assessments. This goes well beyond implied usage.

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?

Since no annotations are provided, the description carries the full burden. It discloses that results are Markdown-formatted, includes a summary, and that the tool is a search (implying read-only). It provides useful behavioral context such as output format and usage, though it doesn't mention rate limits, pagination, or auth requirements, which are less critical for a search 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 clear subheadings (What this tool does, When to use, Inputs, Outputs, LLM usage guidelines). Every sentence contributes useful information—no fluff or redundancy. Despite its length, it is organized and front-loaded with a clear opening statement.

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 one simple parameter and an output schema present, the description is remarkably complete. It covers purpose, usage, inputs, outputs, and LLM guidelines, including how to combine with sibling tools. The description fully equips an agent to invoke the tool correctly and interpret its 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?

The schema already covers the 'query' parameter, but the description adds more semantic value by describing it as a 'free-text search term' and expanding examples to include product names, vendors, and keywords. This goes beyond the schema's brief enumeration, aiding the agent in understanding the parameter's flexibility.

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, explicitly listing what it searches across (CVE entries, advisories, exploit references, product/vendor data). This distinguishes it from sibling tools like vulnerability_info or vulnerability_score, which target specific aspects of vulnerability data.

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 example user queries and states to use it instead of assuming whether a CVE/advisory/exploit exists. It also mentions combining with other tools for deeper analysis, but it does not explicitly name when not to use this tool or directly contrast it with specific siblings like vulnerability_info.

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