projectpulse-mcp

get_health_score

Idempotent

Calculates a 0-100 health score and A-F grade for a GitHub repository. - Side effects: Writes a trend snapshot to local disk for history tracking. Read-only against GitHub API.

Instructions

Calculates a 0-100 health score and A-F grade for a GitHub repository.

Side effects: Writes a trend snapshot to local disk for history tracking. Read-only against GitHub API.
Data sources: GitHub REST API (repos, actions, dependabot) and OpenSSF Scorecard API.
Auth requirements: No authentication required for public repositories. Uses configured token if available.
Rate limits: Subject to standard GitHub API limits (heavy usage across multiple endpoints).
Return shape: Returns a JSON object with a grade (A-F), total score, detailed category breakdown (CI, freshness, security, community, maintenance), improvement suggestions, historical trend data, and an 'openssf' object containing official score, securityChecksAverage, and individual 'checks' (worst score first).
Usage guidelines: Use this tool ONLY for deep analytical grading and overall repository health assessment. DO NOT use this tool for quick metadata checks:
- For basic raw metadata (stars, language, etc.), use 'get_repo_health' instead.
- For raw CI workflow statuses, use 'check_ci_status' instead.
- For deep code vulnerability scanning, use 'analyze_code_scanning' instead.
- For DORA metrics, use 'get_dora_metrics' instead.

Input Schema

Name	Required	Description	Default
`repo`	Yes	GitHub repository name (e.g., 'sdk')
`owner`	Yes	GitHub repository owner (e.g., 'modelcontextprotocol')

Output Schema

Name	Required	Description	Default
`trend`	Yes
`report`	Yes
`openssf`	Yes
`badgeSnippet`	Yes
`recommendations`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.9.0Oct 14, 2026

addedOutput schema / properties / openssf

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": false,
+      "properties": {
+        "checks": {
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "documentation": {
+                "additionalProperties": false,
+                "properties": {
+                  "url": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "url"
+                ],
+                "type": "object"
+              },
+              "name": {
+                "type": "string"
+              },
+              "reason": {
+                "type": "string"
+              },
+              "score": {
+                "type": "number"
+              }
+            },
+            "required": [
+              "name",
+              "score",
+              "reason",
+              "documentation"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "checksTotal": {
+          "type": "number"
+        },
+        "checksUsed": {
+          "type": "number"
+        },
+        "details": {
+          "type": "string"
+        },
+        "score": {
+          "type": "number"
+        },
+        "securityChecksAverage": {
+          "type": "number"
+        }
+      },
+      "required": [
+        "score",
+        "securityChecksAverage",
+        "checksUsed",
+        "checksTotal",
+        "details",
+        "checks"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

changedOutput schema / required

Previous value: -[
-  "report",
-  "trend",
-  "recommendations",
-  "badgeSnippet"
-]New value: +[
+  "report",
+  "trend",
+  "recommendations",
+  "badgeSnippet",
+  "openssf"
+]

Changed3 schema fields changedv1.6.14Sep 8, 2026

addedOutput schema / properties / badgeSnippet
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / recommendations

Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "category": {
+        "type": "string"
+      },
+      "impact": {
+        "type": "string"
+      },
+      "message": {
+        "type": "string"
+      },
+      "priority": {
+        "enum": [
+          "high",
+          "medium",
+          "low"
+        ],
+        "type": "string"
+      }
+    },
+    "required": [
+      "category",
+      "priority",
+      "message",
+      "impact"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

changedOutput schema / required

Previous value: -[
-  "report",
-  "trend"
-]New value: +[
+  "report",
+  "trend",
+  "recommendations",
+  "badgeSnippet"
+]

Changed1 schema field changedv1.1.7Sep 5, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "report": {
+      "additionalProperties": false,
+      "properties": {
+        "breakdown": {
+          "additionalProperties": {
+            "additionalProperties": false,
+            "properties": {
+              "detail": {
+                "type": "string"
+              },
+              "score": {
+                "type": "number"
+              },
+              "weight": {
+                "type": "number"
+              }
+            },
+            "required": [
+              "score",
+              "weight",
+              "detail"
+            ],
+            "type": "object"
+          },
+          "propertyNames": {
+            "type": "string"
+          },
+          "type": "object"
+        },
+        "checkedAt": {
+          "type": "string"
+        },
+        "grade": {
+          "type": "string"
+        },
+        "gradeMeaning": {
+          "type": "string"
+        },
+        "repo": {
+          "type": "string"
+        },
+        "score": {
+          "type": "number"
+        },
+        "suggestions": {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "repo",
+        "score",
+        "grade",
+        "breakdown",
+        "suggestions",
+        "checkedAt",
+        "gradeMeaning"
+      ],
+      "type": "object"
+    },
+    "trend": {
+      "anyOf": [
+        {
+          "additionalProperties": false,
+          "properties": {
+            "direction": {
+              "type": "string"
+            },
+            "previousCheckedAt": {
+              "type": "string"
+            },
+            "previousGrade": {
+              "type": "string"
+            },
+            "previousScore": {
+              "type": "number"
+            },
+            "scoreDiff": {
+              "type": "number"
+            }
+          },
+          "required": [
+            "previousScore",
+            "previousGrade",
+            "previousCheckedAt",
+            "scoreDiff",
+            "direction"
+          ],
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "required": [
+    "report",
+    "trend"
+  ],
+  "type": "object"
+}

Changed2 schema fields changedv1.1.4Sep 5, 2026

changedInput schema / properties / owner / description

Previous value: -"GitHub repository owner"New value: +"GitHub repository owner (e.g., 'modelcontextprotocol')"

changedInput schema / properties / repo / description

Previous value: -"GitHub repository name"New value: +"GitHub repository name (e.g., 'sdk')"

First observedv1.1.3Aug 30, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Although the annotations already declare openWorldHint and non-destructive mutability, the description adds substantial context beyond them: it discloses a real side effect (writing a local trend snapshot), identifies the external data sources, states that no auth is required for public repos, and warns about GitHub rate limits. This is exactly the kind of behavioral detail annotations cannot carry.

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 one-line purpose is front-loaded, and the remaining bullets each carry distinct, non-overlapping information (side effects, data sources, auth, limits, return shape, routing). The return-shape bullet even adds ordering detail ('worst score first') that the output schema does not express.

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?

With an output schema present and annotations covering the safety profile, the description still fills every remaining gap an agent needs: side effects, auth, rate limits, and sibling routing. Nothing required to invoke or interpret this tool correctly is missing.

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% and both parameters (owner, repo) are documented in the schema with examples, so the schema already does the work. The description mentions nothing about the parameters or their formats, so it adds no meaning here — baseline 3 is correct.

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?

It states a specific verb (calculates) plus the concrete output (a 0-100 health score and A-F grade) for a clearly named resource (a GitHub repository). The usage-guidelines block explicitly separates it from siblings like get_repo_health, check_ci_status, analyze_code_scanning, and get_dora_metrics, so an agent can distinguish it without opening other schemas.

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 gives an explicit directive ('Use this tool ONLY for deep analytical grading') plus a 'DO NOT use ... for quick metadata checks' exclusion, and routes four named sibling tools to their correct use cases. This is when/when-not/alternatives in full.

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

Deploy Server