AgentAvow Trust

Scan a package

scan_package

Read-onlyIdempotent

Scan a published package (npm, PyPI, crates, Docker, or Hugging Face) with AgentAvow. Returns one of three answers with its reason (Safe to connect, Review before you connect, or Do not connect), a 0-100 trust score, an adoption score from real usage (downloads per week), findings with remediation, and a signed attestation. Also reports published advisories that affect the scanned version, the maintainer's deprecation notice, repo-vs-artifact drift (files shipped that aren't in the source), and AgentAvow's behavioral sandbox results when available. Scans the latest version unless version (or a pin in the name) names one. Read-only; calls agentavow.com.

Input Schema

Name	Required	Description
`name`	Yes	Package name, e.g. 'chalk' (or 'org/model' for hf).
`force`	No	Re-scan now instead of returning the cached verdict (results cache ~1h). Use after a new version ships.
`surface`	No	Alias for registry.
`version`	No	Exact version to scan, e.g. '5.3.0'. Optional: the latest version by default. A pin in the name ('chalk@5.3.0', 'requests==2.32.5') works too.
`registry`	No	Package registry: npm, pypi, crates, docker, or hf.
`ecosystem`	No	Alias for registry.

Output Schema

Name	Required	Description
`high`	No	High findings, static and sandbox.
`tier`	No	Trust tier for the score (detail, not the headline).
`cached`	No	Served from the ~1h cache.
`signed`	No	True when a signed (Ed25519/JWS) attestation backs this.
`target`	Yes	What was scanned, as given.
`install`	No	Install command, only when nothing blocks it.
`sandbox`	No	What the behavioral sandbox observed; null if it does not apply.
`verdict`	Yes	Binary form of the decision, kept for older clients.
`adoption`	No	The adoption score: real usage (downloads per week, stars or installs). Never changes the decision.
`critical`	No	Critical findings, static and sandbox.
`decision`	Yes	The answer to lead with: safe = Safe to connect, review = Review before you connect, do_not_connect = Do not connect.
`incident`	No	Known past compromise (context only, never scored).
`certified`	No	Matches the signed attestation's certified.eligible.
`subscores`	No	Per-category 0-100 scores behind the trust score.
`deprecated`	No	The maintainer's deprecation notice, or null.
`report_url`	Yes	Full report page.
`scanned_at`	No	When the scan ran (ISO 8601, UTC).
`verify_url`	No	How to verify offline.
`not_checked`	No	Plain-English notes for what the scan could not read or check (empty when it read everything). Say these alongside the answer.
`target_type`	Yes	github, npm, pypi, crates, docker, hf, or mcp.
`trust_score`	Yes	Trust score, 0-100. Evidence under the decision.
`published_at`	No	When that version was published.
`top_findings`	No	Up to five most important findings.
`coverage_gaps`	No	Machine form of not_checked: gap kinds (e.g. tool_list_paged, oversized_files) with a flag or count. Empty when nothing was skipped.
`certified_mark`	No	Certified and safe: show the Certified mark.
`decision_final`	Yes	False while the behavioral sandbox is still running; the decision can still change.
`findings_total`	No	All findings, every severity.
`rescan_pending`	No	A fresh scan was started; this is the previous result.
`verdict_reason`	No	Machine reason for the binary verdict, e.g. clean, clean_partial (clean, but not everything was read), blocking_findings, thin_coverage.
`decision_reason`	Yes	One sentence naming what decided it.
`package_version`	No	Package version scanned.
`report_json_url`	No	The full verdict as JSON.
`static_findings_total`	No	Findings from static analysis only.
`advisories_affecting_version`	No	Published advisories that affect this version.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedOct 29, 2026

addedOutput schema / properties / coverage_gaps

Added value: +{
+  "description": "Machine form of not_checked: gap kinds (e.g. tool_list_paged, oversized_files) with a flag or count. Empty when nothing was skipped.",
+  "type": "object"
+}

addedOutput schema / properties / not_checked

Added value: +{
+  "description": "Plain-English notes for what the scan could not read or check (empty when it read everything). Say these alongside the answer.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

changedOutput schema / properties / verdict_reason / description

Previous value: -"Machine reason for the binary verdict, e.g. clean, blocking_findings, thin_coverage."New value: +"Machine reason for the binary verdict, e.g. clean, clean_partial (clean, but not everything was read), blocking_findings, thin_coverage."

Changed2 schema fields changedOct 8, 2026

addedInput schema / properties / version

Added value: +{
+  "description": "Exact version to scan, e.g. '5.3.0'. Optional: the latest version by default. A pin in the name ('chalk@5.3.0', 'requests==2.32.5') works too.",
+  "maxLength": 64,
+  "type": "string"
+}

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "adoption": {
+      "description": "The adoption score: real usage (downloads per week, stars or installs). Never changes the decision.",
+      "properties": {
+        "count": {
+          "type": "integer"
+        },
+        "score_0_100": {
+          "type": "integer"
+        },
+        "unit": {
+          "type": "string"
+        }
+      },
+      "type": [
+        "object",
+        "null"
+      ]
+    },
+    "advisories_affecting_version": {
+      "description": "Published advisories that affect this version.",
+      "items": {
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "cached": {
+      "description": "Served from the ~1h cache.",
+      "type": "boolean"
+    },
+    "certified": {
+      "description": "Matches the signed attestation's certified.eligible.",
+      "type": "boolean"
+    },
+    "certified_mark": {
+      "description": "Certified and safe: show the Certified mark.",
+      "type": "boolean"
+    },
+    "critical": {
+      "description": "Critical findings, static and sandbox.",
+      "minimum": 0,
+      "type": "integer"
+    },
+    "decision": {
+      "description": "The answer to lead with: safe = Safe to connect, review = Review before you connect, do_not_connect = Do not connect.",
+      "enum": [
+        "safe",
+        "review",
+        "do_not_connect"
+      ],
+      "type": "string"
+    },
+    "decision_final": {
+      "description": "False while the behavioral sandbox is still running; the decision can still change.",
+      "type": "boolean"
+    },
+    "decision_reason": {
+      "description": "One sentence naming what decided it.",
+      "type": "string"
+    },
+    "deprecated": {
+      "description": "The maintainer's deprecation notice, or null.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "findings_total": {
+      "description": "All findings, every severity.",
+      "minimum": 0,
+      "type": "integer"
+    },
+    "high": {
+      "description": "High findings, static and sandbox.",
+      "minimum": 0,
+      "type": "integer"
+    },
+    "incident": {
+      "description": "Known past compromise (context only, never scored).",
+      "type": [
+        "object",
+        "null"
+      ]
+    },
+    "install": {
+      "description": "Install command, only when nothing blocks it.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "package_version": {
+      "description": "Package version scanned.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "published_at": {
+      "description": "When that version was published.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "report_json_url": {
+      "description": "The full verdict as JSON.",
+      "type": "string"
+    },
+    "report_url": {
+      "description": "Full report page.",
+      "type": "string"
+    },
+    "rescan_pending": {
+      "description": "A fresh scan was started; this is the previous result.",
+      "type": "boolean"
+    },
+    "sandbox": {
+      "description": "What the behavioral sandbox observed; null if it does not apply.",
+      "type": [
+        "object",
+        "null"
+      ]
+    },
+    "scanned_at": {
+      "description": "When the scan ran (ISO 8601, UTC).",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "signed": {
+      "description": "True when a signed (Ed25519/JWS) attestation backs this.",
+      "type": "boolean"
+    },
+    "static_findings_total": {
+      "description": "Findings from static analysis only.",
+      "minimum": 0,
+      "type": "integer"
+    },
+    "subscores": {
+      "additionalProperties": {
+        "type": [
+          "number",
+          "null"
+        ]
+      },
+      "description": "Per-category 0-100 scores behind the trust score.",
+      "type": "object"
+    },
+    "target": {
+      "description": "What was scanned, as given.",
+      "type": "string"
+    },
+    "target_type": {
+      "description": "github, npm, pypi, crates, docker, hf, or mcp.",
+      "type": "string"
+    },
+    "tier": {
+      "description": "Trust tier for the score (detail, not the headline).",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "top_findings": {
+      "description": "Up to five most important findings.",
+      "items": {
+        "properties": {
+          "count": {
+            "description": "How many times it occurs.",
+            "type": "integer"
+          },
+          "remediation": {
+            "description": "How to fix it.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "severity": {
+            "description": "critical, high, medium, or low.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "what": {
+            "description": "What was found.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "where": {
+            "description": "File and line, if file-based.",
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "trust_score": {
+      "description": "Trust score, 0-100. Evidence under the decision.",
+      "maximum": 100,
+      "minimum": 0,
+      "type": "integer"
+    },
+    "verdict": {
+      "description": "Binary form of the decision, kept for older clients.",
+      "enum": [
+        "safe",
+        "needs_review"
+      ],
+      "type": "string"
+    },
+    "verdict_reason": {
+      "description": "Machine reason for the binary verdict, e.g. clean, blocking_findings, thin_coverage.",
+      "type": "string"
+    },
+    "verify_url": {
+      "description": "How to verify offline.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "target",
+    "target_type",
+    "decision",
+    "decision_final",
+    "decision_reason",
+    "trust_score",
+    "verdict",
+    "report_url"
+  ],
+  "type": "object"
+}

First observedSep 18, 2026

TDQS

A4/5.0

Behavior5/5

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

Goes well past the annotations: discloses that it makes a network call to agentavow.com, that results are cached (~1h) with a force override, the shape of the verdict space (three named answers with reasons), trust/adoption scoring basis (downloads per week), and extras like advisories, deprecation notices, repo-vs-artifact drift, and sandbox results. Annotations already cover safety; the description adds real operational context.

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?

Front-loaded with the core action and ecosystems, then layered detail; every clause is on-topic. The return-value enumeration is somewhat long given an output schema already exists, but it functions as a quick expectation-set for the agent rather than pure repetition.

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?

Covers scope, external dependency, caching, and default version resolution, which is what an agent needs to invoke it correctly. Since an output schema exists, the described return fields are a bonus rather than a necessity, and the only real gap is sibling routing guidance.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3; the description earns an increment by explaining the default version behavior and that a pin can be embedded in the name ('chalk@5.3.0', 'requests==2.32.5'). It does not explain the registry/surface/ecosystem aliasing, which the schema carries on its own.

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?

States a specific verb and resource ("scan a published package") and enumerates the exact ecosystems covered (npm, PyPI, crates, Docker, Hugging Face), which implicitly separates it from scan_repo (source repos) and scan_mcp_server. It never names those siblings explicitly, so the boundary is inferred rather than stated.

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?

Usage is implied by the outcome language (connect/do-not-connect verdicts) and by "Scans the latest version unless `version` (or a pin in the name) names one," plus the cache note from the schema. There is no explicit when-to-use-this-vs-scan_repo-or-scan_mcp_server guidance, so the agent must infer which scan tool to pick.

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

All AgentAvow Trust tools Inspect

Try in Browser

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?