Skip to main content
Glama

Plan or install external security engines

codeinspectus_setup
Idempotent

Plan or install CodeInspectus security engines and OSV vulnerability databases for a repository, showing exact download sizes and saving declined choices before any confirmed download.

Instructions

Inspect external-engine health and exact platform download sizes, save declined choices, or install selected Opengrep/Gitleaks/Trivy/OSV-Scanner components after explicit confirmation. Pass path (the repository to scan) to plan or install only the OSV vulnerability databases for the ecosystems its lockfiles use (and GitHub Actions advisories when it has workflows); each is listed with an estimated size (integrity: TLS + recorded SHA-256, OSV publishes no signature), and osv_ecosystems pins the exact list the user approved. Plan is offline. Install writes only to ~/.codeinspectus, verifies immutable pins/publisher provenance for engines, and never modifies the target repository.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "codeinspectus_setup"
  }
}

Input Schema

NameRequiredDescriptionDefault
pathNoAbsolute path to the repository the user wants to scan. Only the OSV vulnerability databases for ecosystems whose lockfiles are found there (read-only, by file name) are offered.
actionNoPlan is offline/read-only. Install downloads only after confirm_downloads=true. Decline saves the choice.plan
componentsNoComponents to install or decline. Default: all four external engines.
osv_ecosystemsNoExact OSV ecosystem databases the user approved, e.g. ["npm", "PyPI"]. Overrides the detection from path. Omitted or empty (an empty list is no list): the databases path needs (none without path), plus a refresh of any installed database that went stale. To download no OSV database, leave osv-scanner out of components.
confirm_downloadsNoMust be true for an install that needs network downloads.

Output Schema

NameRequiredDescriptionDefault
planYes
messageYes
outcomeYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed8 schema fields changedv4.0.0
    • changedInput schema / properties / components / description
      Previous value: -"Components to install or decline. Default: all three external engines."New value: +"Components to install or decline. Default: all four external engines."
    • changedInput schema / properties / components / items / enum
      Previous value: -[
      -  "opengrep",
      -  "gitleaks",
      -  "trivy"
      -]New value: +[
      +  "opengrep",
      +  "gitleaks",
      +  "trivy",
      +  "osv-scanner"
      +]
    • addedInput schema / properties / osv_ecosystems
      Added value: +{
      +  "description": "Exact OSV ecosystem databases the user approved, e.g. [\"npm\", \"PyPI\"]. Overrides the detection from path. Omitted or empty (an empty list is no list): the databases path needs (none without path), plus a refresh of any installed database that went stale. To download no OSV database, leave osv-scanner out of components.",
      +  "items": {
      +    "enum": [
      +      "npm",
      +      "PyPI",
      +      "Packagist",
      +      "Go",
      +      "crates.io",
      +      "RubyGems",
      +      "Maven",
      +      "NuGet",
      +      "Pub",
      +      "GitHub Actions"
      +    ],
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • addedInput schema / properties / path
      Added value: +{
      +  "description": "Absolute path to the repository the user wants to scan. Only the OSV vulnerability databases for ecosystems whose lockfiles are found there (read-only, by file name) are offered.",
      +  "minLength": 1,
      +  "type": "string"
      +}
    • changedOutput schema / properties / plan / properties / components / items / properties / id / enum
      Previous value: -[
      -  "opengrep",
      -  "gitleaks",
      -  "trivy"
      -]New value: +[
      +  "opengrep",
      +  "gitleaks",
      +  "trivy",
      +  "osv-scanner"
      +]
    • addedOutput schema / properties / plan / properties / estimated_osv_download_bytes
      Added value: +{
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • addedOutput schema / properties / plan / properties / osv_databases
      Added value: +{
      +  "items": {
      +    "additionalProperties": false,
      +    "properties": {
      +      "ecosystem": {
      +        "enum": [
      +          "npm",
      +          "PyPI",
      +          "Packagist",
      +          "Go",
      +          "crates.io",
      +          "RubyGems",
      +          "Maven",
      +          "NuGet",
      +          "Pub",
      +          "GitHub Actions"
      +        ],
      +        "type": "string"
      +      },
      +      "estimated_download_bytes": {
      +        "minimum": 0,
      +        "type": "integer"
      +      },
      +      "note": {
      +        "type": "string"
      +      },
      +      "selected": {
      +        "type": "boolean"
      +      },
      +      "state": {
      +        "enum": [
      +          "installed",
      +          "missing",
      +          "stale"
      +        ],
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "ecosystem",
      +      "state",
      +      "selected",
      +      "estimated_download_bytes"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
    • changedOutput schema / properties / plan / required
      Previous value: -[
      -  "schema_version",
      -  "platform",
      -  "native",
      -  "components",
      -  "verifier",
      -  "preference_state",
      -  "network_required",
      -  "confirmation_required",
      -  "exact_download_bytes",
      -  "estimated_database_disk_bytes",
      -  "warnings"
      -]New value: +[
      +  "schema_version",
      +  "platform",
      +  "native",
      +  "components",
      +  "verifier",
      +  "preference_state",
      +  "network_required",
      +  "confirmation_required",
      +  "exact_download_bytes",
      +  "osv_databases",
      +  "estimated_osv_download_bytes",
      +  "estimated_database_disk_bytes",
      +  "warnings"
      +]
  2. Addedv2.5.0

TDQS

A3.9/5.0
Behavior5/5

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

Annotations declare openWorldHint and non-readOnly but say nothing about scope or side effects. The description fills that gap precisely: install writes only to ~/.codeinspectus, verifies immutable pins and publisher provenance for engines, uses TLS plus recorded SHA-256 (noting OSV publishes no signature), and never modifies the target repository. That is exactly the behavioral disclosure a mutating, network-touching tool needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The main actions are front-loaded in the first clause, and every sentence carries substantive information. It is dense with parentheticals ('integrity: TLS + recorded SHA-256, OSV publishes no signature') that slow parsing but each earns its place by conveying security-relevant behavior.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, annotations, and full schema coverage, the description supplies the missing pieces an agent needs: offline vs. write side effects, confirmation gating, and install target location. Only the plan/install/decline sequencing could be slightly clearer for a fully complete picture.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already defines path, action, components, osv_ecosystems, and confirm_downloads. The description reinforces a few semantics (osv_ecosystems pins the user-approved list, path scopes ecosystem detection) but adds little beyond what the schema text states, so the baseline 3 applies.

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

Purpose4/5

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

The description opens with concrete verbs and resources: 'Inspect external-engine health and exact platform download sizes, save declined choices, or install selected Opengrep/Gitleaks/Trivy/OSV-Scanner components.' That clearly separates it from scanning/cleanup siblings without naming them, though it never explicitly contrasts with codeinspectus_scan or codeinspectus_apply_cleanup.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives real usage context: install happens 'after explicit confirmation,' 'Plan is offline,' and passing path scopes OSV database work to detected lockfiles. However, it never states when an agent should call this versus codeinspectus_scan or when NOT to call it, so the when-to-use routing is implied rather than explicit.

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