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 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, the description carries the full burden, and it does a good job: it discloses the three-tier fallback selection logic, the upgrade_tier concept, handling of unfixed CVEs, and support for Maven and Gradle. It could additionally state explicitly whether any files are modified, but 'propose' strongly implies non-mutating 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 dense but well-organized, front-loading the main purpose and then detailing the fallback algorithm and output. It is appropriately sized for the complexity involved, though the Maven/Gradle support is mentioned twice, creating slight 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?

Since there is no output schema, the description correctly explains the key return elements: recommended version, upgrade_tier, per-CVE fixed versions, and unfixed status. It also covers the selection strategy and supported build files. It does not describe behavior for projects with no vulnerabilities or error cases, but it is otherwise sufficient for a single-parameter 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?

Schema coverage is 100%, so the baseline is 3. The description adds a bit of context about Maven and Gradle support, but the schema already documents that project_path can be a project directory or a pom.xml/gradle.lockfile path. No significant additional parameter meaning is introduced.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: scanning a Java project and proposing recommended upgrade versions for vulnerable dependencies. It also specifies the output contents (recommended version, upgrade_tier, CVE-specific fixed version), which distinguishes it from sibling tools like scan_java_project and explain_vulnerability.

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 explains what the tool does but does not explicitly say when to use it versus scan_java_project or explain_vulnerability. No usage conditions, exclusions, or alternative routing are provided, leaving the agent to infer the appropriate context.

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