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 full burden and does well: it discloses the scan engine, the report shape (per-package vulnerability list with CVSS score, 5-level severity, fixed version, plus summary aggregates), and a critical non-obvious caveat that a transitivity warning invalidates a zero-finding result. It omits operational traits such as network dependency on the OSV API, credentials, or runtime expectations, which keeps it short of a 5.

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?

Four sentences, each load-bearing: purpose plus report format, report contents, supported build systems, and the safety caveat. The purpose is front-loaded and there is no filler 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?

There is no output schema, so the description must describe returns and it does so concretely (severity-ordered JSON, CVSS, severity level, fixed versions, summary aggregation). Combined with the transitive-dependency caveat, an agent has enough to call and interpret the tool, though environment prerequisites (network access, scan duration) are not addressed.

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 there is only one parameter (project_path), whose meaning is fully documented in the schema itself as a project directory or absolute path to pom.xml/gradle.lockfile. The description adds no syntax, path-form, or default detail beyond the schema, so the baseline 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 names a specific verb and resource (scanning a Java/Maven project with Google OSV-Scanner) and states exactly what is returned (known CVEs/GHSA in severity-ordered JSON). It narrows scope with supported build systems (pom.xml, gradle.lockfile), which implicitly separates it from scan_sbom and scan_java_artifact. However, it never names or contrasts a sibling explicitly, so an agent must infer the boundary against scan_project and scan_java_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?

There is no explicit when-to-use/when-not-to-use statement or named alternative. Usage is only implied by the supported inputs (Maven pom.xml, Gradle gradle.lockfile), and the closing caveat tells the agent not to conclude safety when dependency_resolution.warning is present. That is useful operational guidance but not sibling 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 full behavioral burden and does so well: it states that package managers/builds are NOT executed, explains the coverage block (manifests without lockfiles, unpinned requirement lines, excluded files), and defines dependency_relation as direct/transitive/unknown with which files yield which. It omits any note on permissions or runtime cost, keeping it from a 5.

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?

Front-loaded with the core purpose, then proceeds through supported files, behavioral caveats, and the coverage warning in a logical order. It is dense and somewhat long, but each clause adds operational detail rather than 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?

With no output schema, the description must explain the return shape, and it does specify the leading coverage object, its false case, and per-package dependency_relation. The picture is largely complete, though the exact findings format and suggest_fix linkage to the separate sibling are left implicit.

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% for the single project_path parameter, and the description adds no new semantics beyond what the schema already states (directory or absolute lockfile/manifest path). Baseline 3 is appropriate when the schema does the heavy lifting.

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?

States a specific verb+resource (detect lockfiles/manifests and scan dependencies for known CVE/GHSA vulnerabilities) and enumerates the supported ecosystems and exact filenames, which is unusually precise. However, it never distinguishes itself from overlapping siblings like scan_sbom and scan_java_project, which an agent must choose between, so it falls short of a 5.

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 implicitly defines when to use it by listing the ecosystems and file types it handles, and it gives a critical caution about coverage.complete=false. But it offers no explicit routing versus scan_sbom, scan_java_project, or scan_java_artifact, so the agent cannot tell when this tool is preferred over those.

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 to carry the load, the description discloses substantial behavior: the three-tier fallback selection (same_minor/major_internal/cross_major), candidate_check safety re-query against api.osv.dev, handling of prerelase and unfixed CVEs, coverage and dependency_resolution.warning caveats. This is exactly the kind of behavioral context an agent needs for a complex remediation 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?

Purpose is front-loaded in the first sentence and nearly every subsequent sentence conveys distinct behavioral detail, so little is wasted. However it is delivered as one dense unbroken paragraph with no structuring, which makes the rich detail harder to scan than it needs to be.

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 annotations and no output schema, the description covers the return semantics extensively (upgrade_tier, version_is_lower_bound, dependency_relation/update_hint, recommended_is_prerelease, candidate_check, unfixed, coverage). An agent has everything needed to interpret results and handle caveats 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% and there is a single parameter, so the schema already documents project_path fully; the description adds no extra meaning about the parameter. Baseline of 3 applies when the schema does the heavy lifting.

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?

States a specific verb and resource: it scans the project with the same detection as scan_project and proposes a recommended upgrade version per vulnerable dependency. It explicitly names the sibling scan_project and clarifies how it differs (same scan, plus fix recommendations), so an agent can distinguish it from the other scan_* 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?

Usage is implied through the reference to scan_project (same detection, but adds remediation) and post-call guidance to verify coverage, but there is no explicit when/when-not statement or alternative routing (e.g. when to prefer scan_project or explain_vulnerability). It is enough to infer intent but leaves the choice among siblings to the agent.

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