factreason

Official

Overview Schema Source Related Servers Discussions Admin

factreason_package_upgrade_advisory

Read-onlyIdempotent

Compare two published npm or PyPI versions to reveal registry metadata changes—including yanks, exports, module format, and licenses—so you can assess an upgrade before committing.

Instructions

Compare two exact published npm or PyPI versions and return publisher-declared registry metadata changes, including yanks, exports, module format, runtime floors, peers, and licences, with before/after evidence. Set responseFormat="compact" for tokenizer-measured context savings; the backward-compatible default is "full". This is a read-only metered lookup; misses are never billed and API keys receive a daily free allowance. Use it for package metadata; use factreason_api_breaking_changes for a third-party HTTP API, and consult changelogs for behavioural changes.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`to`	Yes	Exact target version, e.g. "5.0.0"
`from`	Yes	Exact currently installed version, e.g. "4.1.2"
`name`	Yes	Exact package name, e.g. "chalk" or "urllib3"
`registry`	Yes	Registry containing both package versions
`responseFormat`	No	Use compact to remove repeated prose and fields while retaining evidence; full preserves the legacy response contract	full

Output Schema

TableJSON Schema

Name	Required	Description	Default
`found`	No
`scope`	No
`billed`	No
`message`	No
`toVersion`	No
`advisories`	No
`fromVersion`	No
`packageName`	No
`tokenMetrics`	No
`advisoryCount`	No
`breakingCount`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv2.0.4Aug 16, 2026

addedInput schema / properties / responseFormat

Added value: +{
+  "default": "full",
+  "description": "Use compact to remove repeated prose and fields while retaining evidence; full preserves the legacy response contract",
+  "enum": [
+    "full",
+    "compact"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / advisoryCount
```
Added value: +{
+  "type": "number"
+}
```

addedOutput schema / properties / tokenMetrics

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "compactTokens": {
+      "type": "number"
+    },
+    "encoding": {
+      "const": "o200k_base",
+      "type": "string"
+    },
+    "fullTokens": {
+      "type": "number"
+    },
+    "reductionPct": {
+      "type": "number"
+    },
+    "savedTokens": {
+      "type": "number"
+    }
+  },
+  "type": "object"
+}

Changed9 schema fields changedv2.0.2Aug 14, 2026

addedInput schema / additionalProperties
```
Added value: +false
```

changedInput schema / properties / from / description

Previous value: -"Version currently installed, e.g. \"4.1.2\""New value: +"Exact currently installed version, e.g. \"4.1.2\""

addedInput schema / properties / from / minLength
```
Added value: +1
```

changedInput schema / properties / name / description

Previous value: -"Package name, e.g. \"chalk\", \"urllib3\""New value: +"Exact package name, e.g. \"chalk\" or \"urllib3\""

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

changedInput schema / properties / registry / description

Previous value: -"Which registry the package is published on"New value: +"Registry containing both package versions"

changedInput schema / properties / to / description

Previous value: -"Version you intend to upgrade to, e.g. \"5.0.0\""New value: +"Exact target version, e.g. \"5.0.0\""

addedInput schema / properties / to / minLength
```
Added value: +1
```

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "properties": {
+    "advisories": {
+      "items": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "billed": {
+      "type": "boolean"
+    },
+    "breakingCount": {
+      "type": "number"
+    },
+    "found": {
+      "type": "boolean"
+    },
+    "fromVersion": {
+      "type": "string"
+    },
+    "message": {
+      "type": "string"
+    },
+    "packageName": {
+      "type": "string"
+    },
+    "scope": {
+      "type": "string"
+    },
+    "toVersion": {
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

First observedv2.0.1Aug 14, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description does not need to restate safety. It adds valuable context beyond the annotations: "This is a read-only metered lookup; misses are never billed and API keys receive a daily free allowance." This informs the agent of billing implications and quota behavior, which is critical for cost-aware invocation. The description also notes responseFormat's backward compatibility, adding further behavioral nuance.

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, with the primary purpose stated in the first sentence and supporting guidance in two following short clauses. Every sentence earns its place: purpose, usage alternatives, metering note, and responseFormat hint. It is front-loaded and avoids repetitive or generic filler.

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?

Given the tool's moderate complexity (5 params, output schema present) and rich annotations, the description covers all necessary contextual aspects: what the tool does, when to use it versus siblings, billing/rate-limit behavior, and a parameter-specific recommendation. The output schema handles return structure details, so the description does not need to enumerate them. The only minor omission is explicit error handling, but the "misses are never billed" line already hints at failure behavior, making this sufficient.

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 description coverage is 100%, so the baseline is 3. The description adds meaningful extra context for responseFormat: "Set responseFormat="compact" for tokenizer-measured context savings; the backward-compatible default is "full"." This goes beyond the schema's basic enum description, explaining the why and the trade-off. It also implicitly ties registry,name,from,to to the purpose statement, reinforcing their role. No significant param semantics are left unexplained.

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 opens with a specific verb and resource: "Compare two exact published npm or PyPI versions and return publisher-declared registry metadata changes," and enumerates concrete fields (yanks, exports, module format, runtime floors, peers, licences). It also distinguishes from sibling tools by explicitly directing users to factreason_api_breaking_changes for third-party HTTP APIs and changelogs for behavioural changes, making the tool's unique scope unambiguous.

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

Usage Guidelines5/5

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

The description provides explicit usage context: "Use it for package metadata; use factreason_api_breaking_changes for a third-party HTTP API, and consult changelogs for behavioural changes." It also clarifies the optional responseFormat switch, including the backward-compatible default, which helps agents decide when to pass that parameter. This goes beyond basic context by naming alternatives and exclusions.

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

Deploy Server