Review Software Supply Chain

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, and the description reinforces this with a concrete operational boundary: 'analyzes supplied artifacts only and does not call registries, CI systems, or clusters.' That closed-world, offline-analysis disclosure is genuinely useful context an agent cannot infer from annotations alone, though it adds little on error behavior or input 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?

Three front-loaded sentences: the capability, the trigger condition, and the limitation. Every sentence earns its place with no filler or repetition of schema content.

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 an output schema present and 100% schema coverage, the description need not explain return values, and annotations cover the safety profile. It adequately covers scope, trigger, and boundaries; only the absence of named alternatives for narrower sibling tools keeps it from being fully 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, but the description goes further by mapping evidence categories onto parameters: action pinning to workflowYaml, image immutability to kubernetesManifestYaml, signing to artifactSigned, provenance to hasProvenance. This explains what role each input plays in the correlation rather than just restating field names.

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 (correlate/assess) and resource (software-supply-chain risk) and enumerates the exact evidence dimensions it fuses: SBOM quality, CI action pinning, Kubernetes image immutability, artifact signing, and build provenance. This distinguishes it from single-domain siblings like review_cicd_pipeline, review_github_actions_workflow, and review_kubernetes_security.

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 gives an explicit precondition ('Use this when an SBOM is available and supply-chain evidence needs to be evaluated together'), which tells the agent this is the cross-domain aggregator. It stops short of naming which sibling tools to prefer for single-domain checks, so it is clear context rather than a full when/when-not routing rule.

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