dependency-trust

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description does not contradict them. It adds behavioral context beyond annotations by specifying the returned information (title, CVE aliases, CVSS v3 score/vector, osv.dev link), the lack of search capability, and the requirement of a pre-existing advisory key.

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 front-loaded with the core purpose, then gives return-value details, and finally addresses usage context and exclusions. Every sentence carries unique information: what it does, what it returns, when to use it, what it doesn't do, and which sibling to call instead. No filler or 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 single-parameter read-only tool with rich annotations and an output schema, the description is complete. It covers the operation, the return contents, the source of the required key, the no-search limitation, and the relationship to get_package_version. An agent can confidently select and invoke this tool without missing 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 input schema already fully documents advisoryKey with an example and the note about being taken from advisoryKeys, so the description doesn't need to add much. It does reinforce the source of the value and the example format ('GHSA id taken from a version's advisoryKeys'), which adds a small amount of context 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 and resource: 'Get a security advisory (vulnerability) by its key.' It further clarifies the scope by stating there is no search here and explicitly differentiates itself from get_package_version, which is about version-level vulnerability presence rather than deep-diving one advisory.

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 gives explicit when-to-use guidance: 'Use this only when you already have an advisory ID from get_package_version's advisoryKeys.' It also states a clear alternative: 'To find out whether a version has vulnerabilities at all, call get_package_version first.' This leaves no ambiguity about when to select this tool versus a sibling.

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?

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior. The description adds useful behavioral context by specifying that it returns the full resolved graph, each node's exact version, and the SELF / DIRECT / INDIRECT relation, which goes beyond the annotations and helps the agent understand the output shape.

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 concise and front-loaded with the core purpose, followed by return details and a use-case sentence. There is minor redundancy in repeating 'resolved dependency graph' in the first two sentences, but overall every sentence earns its place.

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 is well-specified given the rich annotations, complete parameter schemas, and presence of an output schema. The description covers scope, graph contents, relation semantics, and intended use, leaving no critical gap for an agent to invoke it 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%, so the parameters are already fully documented in the schema. The description does not need to restate them and adds no additional parameter-level detail, matching the baseline of 3.

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 and resource: 'Get the resolved dependency graph for one package version.' It clearly distinguishes itself from package metadata tools by focusing on the dependency graph and transitive relationships, and it names the exact output relation types (SELF / DIRECT / INDIRECT).

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 gives explicit guidance on when to use the tool: 'Use it to reason about transitive dependencies and supply chain.' It does not explicitly name alternatives or state when not to use it, but the use case is clear enough for an agent to select it appropriately.

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?

Annotations already cover the read-only, idempotent, non-destructive profile, so the description correctly focuses on additional behavior: it returns all published versions with publish date, the default-version flag, and deprecation status. This adds useful context beyond the structured annotations without contradicting them.

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 sentences with no filler. It front-loads the core behavior, then gives return details and practical usage guidance; every sentence earns its place.

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 simple read-only listing operation with a rich input schema and an output schema available, the description provides sufficient context to call the tool correctly and understand its result. The usage guidance adds workflow-level completeness that most tool descriptions lack.

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 has 100% description coverage, including a clear system enum and detailed package-name handling with examples. The main description does not add parameter-level meaning, but the schema already carries that burden, so baseline 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 opening sentence states a specific verb, resource, and scope: 'List every version of a package and whether each is deprecated.' This clearly separates it from the sibling get_package_version by emphasizing all versions rather than a single version.

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 gives explicit when-to-use guidance: find the latest version, check deprecation status, and call before recommending a package or version. It does not name sibling alternatives or state when not to use the tool, so it stops short of 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds meaningful behavioral context by naming the returned fields, including SPDX licenses, advisoryKeys, source links, publish date, and deprecation status, and it discloses that advisoryKeys represent known vulnerabilities.

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 and front-loaded with the tool's purpose. The first sentence states the outcome, the second adds concrete return-field details, and the final sentence gives a routing instruction. There is little redundancy, and each sentence earns its place.

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 an output schema exists and annotations cover the safety profile, the description is complete enough for an agent to select and call the tool correctly. It explains what metadata is returned, how to interpret advisoryKeys, and where to go next for vulnerability details. No critical usage context 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 does not add input parameter semantics beyond the schema; the schema already explains ecosystem, raw package names, and exact version formatting. The description adds value for output semantics, but not for the parameters themselves.

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 verb and resource: 'Get license, security advisories, and source links for one package version.' It further distinguishes itself by emphasizing 'single version' metadata, making it clear this tool is version-scoped rather than package-level. The follow-up pointer to get_advisory also clarifies its role in the workflow.

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 says to pass an advisoryKey to get_advisory for vulnerability details, giving an explicit next-step usage condition. It does not explicitly contrast with get_package or get_dependencies, but the 'single version' focus and detailed metadata list imply the appropriate scope of use.

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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond the annotations: the score range (0-10), the list of per-check results, and supplementary metadata like stars, forks, and license. It explains what the tool evaluates, which informs expected behavior even though it doesn't discuss rate limits or auth.

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 front-loaded with the core purpose and then expands into output details and usage guidance. The phrase 'THE trust check.' adds emphasis but is slightly stylistic, and the projectile list of checks is dense though relevant. Overall it's well-structured and each sentence adds value, with only minor flourish preventing a 5.

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 a rich output schema and safety annotations, the description covers everything an agent needs: what the tool returns, how to interpret the score, when to use it, how to obtain the required parameter, a concrete example, and the relationship to get_package_version. No critical guidance 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 schema already fully documents projectKey, its required format, supported hosts, and how to obtain it. The description repeats this guidance with the same example ('github.com/facebook/react') and the get_package_version dependency, adding no new semantic information beyond the schema. Baseline 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 ('Get'), resource ('a project's OpenSSF Scorecard security posture and maintenance signals'), and enumerates concrete outputs. It distinguishes this tool from CVE-only lookups ('not just whether it has a known CVE') and positions it as the canonical trust check, clearly differentiating it from siblings like get_advisory.

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 explicitly says to use it 'to judge whether a dependency is actively maintained and securely operated' and clarifies that it is not merely a CVE check, implicitly steering away from get_advisory. It also gives a procedural prerequisite: obtain projectKey from a version's SOURCE_REPO link by calling get_package_version first. It doesn't name alternative tools for each when-not case, but the guidance is clear enough.

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