vulnforge_audit_cicd

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

With no annotations, the description carries the full burden. It usefully discloses the detection scope (pull_request_target with untrusted checkout, write-all permissions, hardcoded secrets, unpinned actions, expression injection, insecure OIDC), which is real behavioral detail. However, it never says whether this is a read-only static analysis, whether filePath causes the file to be read from disk or is merely a label, and with no output schema it gives no hint of result shape or severity grading.

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?

A single front-loaded sentence led by the verb and the target artifacts, with the check list following. The enumeration is dense but every item is a distinct, actionable detection category, so little is wasted; only the length of the trailing list slightly taxes scanning.

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 three-parameter static-analysis tool with no annotations and no output schema, the description covers what is analyzed and what is looked for, which is the core need. It still leaves the agent guessing about output structure, severity reporting, and whether input is read from disk, which matters for correct invocation.

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 both the workflowType enum and the workflowContent/filePath semantics are already documented in the schema. The description adds no parameter-level guidance beyond that — notably it does not clarify the filePath-versus-workflowContent relationship or the auto-detection behavior. Baseline 3 applies.

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 (audits) against a specific resource pair (GitHub Actions .github/workflows/*.yml and GitLab CI .gitlab-ci.yml), then enumerates the exact vulnerability classes checked. The CI/CD domain cleanly separates it from sibling audits like vulnforge_audit_iam, vulnforge_audit_container, or vulnforge_audit_sbom without ambiguity.

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 only implied: it targets workflow YAML, so an agent infers it should be called when such content is in hand. There is no explicit when-to-use statement, no when-not condition, and no routing to alternatives such as vulnforge_full_scan or the other domain-specific audits when the artifact is not a CI/CD file.

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