pkgtruth

Check one package

check_package

Read-onlyIdempotent

Verify an npm or PyPI package before installing it. Returns existence and flags slopsquatting, malware, install scripts, deprecation, and abandonment.

Instructions

Verify a single npm or PyPI package before installing, importing, or recommending it. Returns whether it actually exists, and flags slopsquatting (a low-adoption package impersonating a popular one), names npm removed for malware, install-time scripts, deprecation, and abandonment. Call this whenever you are about to introduce a dependency you have not verified in this session. Read-only; one or two requests to the public registry. A verdict of UNKNOWN means the registry did not answer — retry, never assume safe.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`name`	Yes	Exact package name as it would be installed, e.g. "express", "@scope/pkg", or for PyPI "requests". No version suffix.
`ecosystem`	No	Registry to check against. Default npm.

Output Schema

TableJSON Schema

Name	Required	Description
`name`	Yes
`score`	No	0–100 risk score behind the verdict; null when the registry was unreachable.
`exists`	No
`ageDays`	No	Days since first publish.
`signals`	Yes
`summary`	Yes	One-paragraph explanation with the suggested real package when there is one.
`verdict`	Yes	HALLUCINATED: no such package. DANGER: do not install as-is. CAUTION: review first. UNKNOWN: could not verify — never treat as safe. SAFE: nothing found.
`version`	No	Latest published version.
`complete`	No	false when a check could not run (rate limit, outage); such a result is UNKNOWN unless already DANGER.
`pointsTo`	No	The package this one's own deprecation notice tells users to install instead, if any.
`ecosystem`	Yes
`didYouMean`	No	For HALLUCINATED names: real packages with a similar name.
`repository`	No
`weeklyDownloads`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv0.2.2Sep 10, 2026

addedInput schema / properties / ecosystem

Added value: +{
+  "description": "Registry to check against. Default npm.",
+  "enum": [
+    "npm",
+    "pypi"
+  ],
+  "type": "string"
+}

changedInput schema / properties / name / description

Previous value: -"Exact npm package name, e.g. \"express\" or \"@scope/pkg\"."New value: +"Exact package name as it would be installed, e.g. \"express\", \"@scope/pkg\", or for PyPI \"requests\". No version suffix."

addedInput schema / properties / name / maxLength
```
Added value: +214
```
addedInput schema / properties / name / minLength
```
Added value: +1
```

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "ageDays": {
+      "description": "Days since first publish.",
+      "type": [
+        "number",
+        "null"
+      ]
+    },
+    "complete": {
+      "description": "false when a check could not run (rate limit, outage); such a result is UNKNOWN unless already DANGER.",
+      "type": "boolean"
+    },
+    "didYouMean": {
+      "description": "For HALLUCINATED names: real packages with a similar name.",
+      "items": {
+        "additionalProperties": {},
+        "properties": {
+          "name": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "name"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "ecosystem": {
+      "enum": [
+        "npm",
+        "pypi"
+      ],
+      "type": "string"
+    },
+    "exists": {
+      "type": [
+        "boolean",
+        "null"
+      ]
+    },
+    "name": {
+      "type": "string"
+    },
+    "pointsTo": {
+      "description": "The package this one's own deprecation notice tells users to install instead, if any.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "repository": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "score": {
+      "description": "0–100 risk score behind the verdict; null when the registry was unreachable.",
+      "type": [
+        "number",
+        "null"
+      ]
+    },
+    "signals": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "detail": {
+            "description": "One sentence of evidence, written for the agent to relay.",
+            "type": "string"
+          },
+          "id": {
+            "description": "Stable machine id, e.g. npm_security_placeholder, impersonates_popular_package, not_in_registry, incomplete_check.",
+            "type": "string"
+          },
+          "severity": {
+            "enum": [
+              "critical",
+              "high",
+              "medium",
+              "low",
+              "info"
+            ],
+            "type": "string"
+          }
+        },
+        "required": [
+          "id",
+          "severity",
+          "detail"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "summary": {
+      "description": "One-paragraph explanation with the suggested real package when there is one.",
+      "type": "string"
+    },
+    "verdict": {
+      "description": "HALLUCINATED: no such package. DANGER: do not install as-is. CAUTION: review first. UNKNOWN: could not verify — never treat as safe. SAFE: nothing found.",
+      "enum": [
+        "SAFE",
+        "CAUTION",
+        "DANGER",
+        "HALLUCINATED",
+        "UNKNOWN"
+      ],
+      "type": "string"
+    },
+    "version": {
+      "description": "Latest published version.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "weeklyDownloads": {
+      "type": [
+        "number",
+        "null"
+      ]
+    }
+  },
+  "required": [
+    "name",
+    "ecosystem",
+    "verdict",
+    "summary",
+    "signals"
+  ],
+  "type": "object"
+}

First observedv0.1.1Aug 31, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Beyond the readOnly/openWorld hints, it discloses concrete runtime behavior: it makes one or two requests to the public registryandar explains the UNKNOWN result semantics with a caution to retry and never assume safe. This is substantial behavioral information that is not encoded in the annotations and materially helps the agent handle edge cases.

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

Conciseness5/5

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

The description is compact, front-loaded with the action and result, and each sentence adds new information: what it verifies, what it detects, when to use it, network behavior, and UNKNOWN handling. No fluff or redundancy.

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

Completeness5/5

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

Combined with the rich input schema and annotations, the description covers the core need-to-know: purpose, trigger condition, output facets, edge-case handling, and safety guidance. The agent has enough context to decide when to select this tool and how to interpret its verdict, even without the output schema in view.

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?

The input schema already fully documents both parameters (name and ecosystem) with examples, defaults, and constraints. The description adds little beyond repeating 'single package' and 'npm or PyPI', so with high schema coverage the baseline of 3 is appropriate.

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

Purpose5/5

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

The description uses a specific verb ('Verify') with a clear resource ('a single npm or PyPI package') and enumerates the concrete checks performed (existence, slopsquatting, malware-removed names, install-time scripts, deprecation, abandonment). This clearly distinguishes it from the sibling check_install_command and tells the agent exactly what the tool accomplishes.

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

Usage Guidelines4/5

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

It gives an explicit trigger: 'Call this whenever you are about to introduce a dependency you have not verified in this session.' This clearly states when to use it and the preconditions (before installing, importing, or recommending). However, it does not explicitly name alternatives or when-not-to-use scenarios, so it falls short of a 5.

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

Deploy Server