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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states that the tool performs an external API lookup, returns specific data fields, and does not execute scanning, which are the key behavioral traits an agent needs. It does not mention potential network failures or rate limits, but for a read-only lookup tool, the disclosed behavior is sufficient.

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 concise sentences in Japanese, starting with the core action, then the returned fields, then usage context and a clear non-scan caveat. Every sentence earns its place with no fluff or duplication of schema details.

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 interface, the fully self-describing input schema, and the absence of an output schema, the description is complete enough. It explains the data source, the input, the output fields, the relationship to sibling tools, and the key behavioral constraint (no scanning), so an agent can invoke it correctly without additional information.

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 documents vulnerability_id with examples and length constraints (100% coverage). The description adds valuable semantic context by stating that IDs from scan_java_project or suggest_fix can be passed directly, which helps the agent understand the expected value and provenance of the parameter.

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 ('取得して返す' fetch and return), a specific resource (OSV database at api.osv.dev), and the input type (GHSA-ID or CVE-ID). It explicitly lists the returned contents (details, CVSS, affected packages, references), which clearly distinguishes this from the sibling scan_java_project and suggest_fix tools.

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 clearly indicates this tool is for retrieving vulnerability details from IDs obtained via scan_java_project or suggest_fix, and explicitly states that scanning is not performed. This gives an agent clear contextual guidance on when to invoke it, though it does not explicitly state 'when not to use' for all 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, the description carries the full burden. It transparently discloses that no build or code execution occurs, that identification is best-effort based on metadata, that completeness is always incomplete, and that zero findings do not guarantee safety. This is strong behavioral transparency, though it does not describe return format or pagination.

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 concise sentences, each adding value: the action, what it avoids, and critical result-interpretation caveats. The most important information is front-loaded, with 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 the single parameter and lack of output schema, the description explains key limitations (coverage, incompleteness, no guarantee) that an agent needs to correctly interpret results. It does not detail the output structure, but the caveats about coverage and unidentifiable files imply the output contains these, which is sufficient for safe usage.

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%, and the description does not add details beyond what the schema already states for artifact_path. It aligns with the schema's description of the parameter, but no extra semantics are provided.

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 scans entities inside JAR/WAR files or directories, explicitly distinguishing it from source-level scanning (scan_java_project) and noting it does not execute builds or Java code. The verb+resource combination is specific 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?

Usage is implied by the resource type (JAR/WAR vs. source code), but there is no explicit mention of when to use this over scan_sbom or scan_java_project. The description does provide guidance on interpreting results (check coverage, unidentifiable files) but lacks explicit alternative routing.

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 burden and does disclose key behavior: it uses OSV-Scanner, returns JSON, orders by severity, and specifies report contents including CVSS score, severity level, fixed version, and summary. It does not discuss side effects or network requirements, but scanning is reasonably implied as a read-only analysis.

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: the first covers the operation, tool, output format, and report contents; the second covers supported build tools. No filler, and the most important 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?

For a single-parameter tool with no output schema, the description sufficiently explains what the report contains and what input forms are accepted. It could mention edge cases like network access or empty vulnerability results, but nothing essential for selecting or invoking the tool is missing.

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 that both Maven and Gradle are supported, but the schema already documents that project_path can be a directory or an absolute path to pom.xml/gradle.lockfile, so no substantial new meaning is added.

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 specific verb ('スキャン'), a specific resource (Java/Maven project dependencies), and the output (JSON vulnerability report ordered by severity). It clearly distinguishes this from siblings like suggest_fix and explain_vulnerability by focusing on detection.

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 states what project types are supported (Maven pom.xml and Gradle gradle.lockfile) and what input is accepted (project directory or build file path), giving clear context for when to invoke it. It does not explicitly name alternatives or exclusions, but the siblings are clearly different downstream actions.

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 and does an excellent job: it discloses that only SBOM-identifiable dependencies are scanned, that builds/JARs are not executed, that SBOM comprehensiveness/freshness/artifact-match are unverified, and that zero detections do not guarantee safety. These limitations are highly useful for an agent deciding how to interpret results.

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 compact, front-loaded with the core scanning behavior and supported formats, and every sentence adds operational value. It states scope, exclusions, input constraints, and key limitations without redundancy or padding.

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 annotations and no output schema, the description is quite complete: input format, size, local-file requirement, non-execution behavior, and result caveats are all covered. The main gap is that it does not describe the return value or output structure of the scan, which would help an agent know what to expect after calling 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?

The input schema already defines sbom_path as an absolute path to a CycloneDX/SPDX JSON SBOM file, with 100% coverage. The description adds meaningful constraints beyond the schema: supported format versions, the 16MiB size limit, and that the input must be a local file, which helps the agent validate the parameter before calling the tool.

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 ('スキャンする') and resource ('CycloneDX 1.4/1.5/1.6またはSPDX 2.2/2.3のJSON SBOM'), and states what is scanned: dependencies identifiable from the SBOM. It is clearly distinguished from siblings like scan_java_project and scan_java_artifact by focusing on an SBOM file input rather than a project or artifact.

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 establishes clear usage context: this tool is for scanning a local JSON SBOM file, with a 16MiB size limit, and explicitly says it does not build or execute JARs. It does not explicitly name sibling alternatives or exclusion conditions, but the input constraints and non-execution note make the intended scenario reasonably clear.

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 and does so thoroughly: it reveals the three-stage fallback selection logic (same_minor → major_internal → cross_major), the policy to hold recommendations when information is insufficient, the separate 'unfixed' display, and support for both Maven and Gradle. It also implies a non-mutating scan by saying 'scans' and 'proposes'.

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 a single dense paragraph with no filler, front-loading the core purpose and then adding useful algorithmic detail. It is somewhat long, but each clause contributes meaningful behavioral or selection information that an agent would need.

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 what is returned (recommended version, upgrade_tier, per-CVE fixed versions, unfixed status, and the judgment at the recommended target), the selection algorithm, and supported project formats. It is nearly complete, though it does not specify the exact response shape or error 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?

The schema covers the only parameter (project_path) at 100%, including that it may be a directory or a pom.xml/gradle.lockfile path. The description reinforces this but adds no meaningful semantics beyond what the schema already provides, so the baseline score of 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 states a specific action ('scan' and 'propose'), a specific resource (vulnerable Java dependency packages), and the concrete outputs (recommended version, upgrade_tier, CVE-level fixed versions). This clearly differentiates it from siblings that merely scan artifacts, SBOMs, or projects, or that explain vulnerabilities.

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 makes it clear the tool is for generating upgrade recommendations for vulnerable Java dependencies and notes Maven/Gradle support. However, it never explicitly states when to prefer this over scan_java_project or scan_java_artifact, nor does it mention exclusions or prerequisite steps.

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