claude-faf-mcp

Overview Schema Source Related Servers Discussions Admin

Score .faf

faf_score

Read-onlyIdempotent

Scores a project's .faf with faf-cli to report 0–100%, tier, populated/active slots, and a faf-parity/v1 hash. Set details to list each slot's status; read-only.

Instructions

Score the project's .faf with faf-cli's scorer — the one score every faf tool reports: 0–100%, the tier, populated/active slots, and a faf-parity/v1 hash of the result. details: true lists every slot as populated, empty or slotignored. Reads only. Use faf_doctor for what to fix.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`path`	No	Project path. Sets session context for subsequent calls.
`details`	No	List every slot as populated, empty or slotignored, and the tools that fill the empty ones

Output Schema

TableJSON Schema

Name	Required	Description
`path`	No	Path that was scored
`tier`	Yes	Tier name for this score (e.g. BRONZE, TROPHY)
`empty`	No	Active slots still empty
`score`	Yes	AI-readiness score, 0-100 (-1 only together with unknown: true)
`slots`	No	Slot paths by state
`total`	No	Total slots
`active`	No	Slots active for this app_type
`hasFaf`	Yes	Whether a readable, valid project.faf was scored
`parity`	No	faf-parity/v1 — claude-faf-mcp's own spec (no other engine computes it yet): sha256 over a canonical projection of faf-cli's score for these exact bytes. Check it yourself: sha256(projection) === parityHash.
`ignored`	No	Slots marked slotignored (inactive for this app_type)
`unknown`	No	True when the score is not known: an About repo with no about.source_score. Shown as "unknown (—)", never as a number.
`nextTier`	No	Next tier above the current score, or null at top tier
`inherited`	No	True if the score is attested from a source repo (an about: block)
`populated`	No	Active slots that are filled

Schema Changelog

Changes observed during successful MCP inspections.

Changed11 schema fields changedv6.0.0Sep 13, 2026

changedInput schema / properties / details / description

Previous value: -"Include detailed breakdown and improvement suggestions"New value: +"List every slot as populated, empty or slotignored, and the tools that fill the empty ones"

changedOutput schema / properties / inherited / description

Previous value: -"True if the score is attested from a source repo (app_type: about)"New value: +"True if the score is attested from a source repo (an about: block)"

changedOutput schema / properties / parity / description

Previous value: -"Determinism parity receipt — an engine-agnostic hash any conformant scorer reproduces for this exact file. Third-party verifiable: sha256(projection) === parityHash."New value: +"faf-parity/v1 — claude-faf-mcp's own spec (no other engine computes it yet): sha256 over a canonical projection of faf-cli's score for these exact bytes. Check it yourself: sha256(projection) === parityHash."

changedOutput schema / properties / parity / properties / parityHash / description

Previous value: -"sha256(projection) — identical across any conformant engine"New value: +"sha256(projection)"

changedOutput schema / properties / parity / properties / producedBy / description

Previous value: -"Which wrapper emitted this receipt (metadata, not hashed)"New value: +"The server that emitted this receipt (metadata, not hashed)"

changedOutput schema / properties / parity / properties / scorer / description

Previous value: -"The single deterministic source the score comes from"New value: +"The single deterministic source the score comes from (faf-cli)"

changedOutput schema / properties / parity / properties / spec / description

Previous value: -"Parity spec id, e.g. faf-parity/v1"New value: +"Parity spec id: faf-parity/v1"

changedOutput schema / properties / score / description

Previous value: -"AI-readiness score, 0-100"New value: +"AI-readiness score, 0-100 (-1 only together with unknown: true)"

addedOutput schema / properties / slots

Added value: +{
+  "description": "Slot paths by state",
+  "properties": {
+    "empty": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "ignored": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "populated": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "type": "object"
+}

changedOutput schema / properties / tier / description

Previous value: -"Tier name for this score (e.g. Bronze, Trophy)"New value: +"Tier name for this score (e.g. BRONZE, TROPHY)"

addedOutput schema / properties / unknown

Added value: +{
+  "description": "True when the score is not known: an About repo with no about.source_score. Shown as \"unknown (—)\", never as a number.",
+  "type": "boolean"
+}

Changed1 schema field changedv5.9.0Jun 12, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "description": "Structured AI-readiness score, single-sourced from faf-cli.",
+  "properties": {
+    "active": {
+      "description": "Slots active for this app_type",
+      "type": "number"
+    },
+    "empty": {
+      "description": "Active slots still empty",
+      "type": "number"
+    },
+    "hasFaf": {
+      "description": "Whether a readable, valid project.faf was scored",
+      "type": "boolean"
+    },
+    "ignored": {
+      "description": "Slots marked slotignored (inactive for this app_type)",
+      "type": "number"
+    },
+    "inherited": {
+      "description": "True if the score is attested from a source repo (app_type: about)",
+      "type": "boolean"
+    },
+    "nextTier": {
+      "description": "Next tier above the current score, or null at top tier",
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "threshold": {
+          "type": "number"
+        }
+      },
+      "type": [
+        "object",
+        "null"
+      ]
+    },
+    "parity": {
+      "description": "Determinism parity receipt — an engine-agnostic hash any conformant scorer reproduces for this exact file. Third-party verifiable: sha256(projection) === parityHash.",
+      "properties": {
+        "algo": {
+          "description": "Hash algorithm (sha256)",
+          "type": "string"
+        },
+        "parityHash": {
+          "description": "sha256(projection) — identical across any conformant engine",
+          "type": "string"
+        },
+        "producedBy": {
+          "description": "Which wrapper emitted this receipt (metadata, not hashed)",
+          "type": "string"
+        },
+        "projection": {
+          "description": "The exact canonical string that was hashed (for verification)",
+          "type": "string"
+        },
+        "scorer": {
+          "description": "The single deterministic source the score comes from",
+          "type": "string"
+        },
+        "sourceSha256": {
+          "description": "SHA-256 of the raw .faf bytes",
+          "type": "string"
+        },
+        "spec": {
+          "description": "Parity spec id, e.g. faf-parity/v1",
+          "type": "string"
+        }
+      },
+      "required": [
+        "spec",
+        "parityHash",
+        "sourceSha256",
+        "projection"
+      ],
+      "type": "object"
+    },
+    "path": {
+      "description": "Path that was scored",
+      "type": "string"
+    },
+    "populated": {
+      "description": "Active slots that are filled",
+      "type": "number"
+    },
+    "score": {
+      "description": "AI-readiness score, 0-100",
+      "type": "number"
+    },
+    "tier": {
+      "description": "Tier name for this score (e.g. Bronze, Trophy)",
+      "type": "string"
+    },
+    "total": {
+      "description": "Total slots",
+      "type": "number"
+    }
+  },
+  "required": [
+    "score",
+    "tier",
+    "hasFaf"
+  ],
+  "type": "object"
+}

First observedv4.0.0May 2, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Annotations already declare readOnly, idempotent and non-destructive, so the bar is lower; the description reinforces this with 'Reads only' and goes further by disclosing the exact output composition (score, tier, slot states, faf-parity/v1 hash). It does not mention failure modes or cost, but adds real context beyond the annotations.

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 core action and output are front-loaded and the total length is appropriate. The dash-heavy, list-like styling and the aside 'the one score every faf tool reports' add flavor but slightly dilute an otherwise tight definition.

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?

An output schema exists, so return values need not be explained, yet the description still summarizes them usefully. With only two optional parameters, full schema coverage, and clear safety annotations, an agent has everything needed to invoke this correctly.

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 both parameters are already documented in the schema, which establishes the baseline of 3. The description's note that details:true lists every slot as populated/empty/slotignored largely restates the schema, adding little new syntax or edge-case meaning.

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?

States a specific verb and resource ('Score the project's .faf with faf-cli's scorer') and enumerates exactly what the score contains (0–100%, tier, slots, parity hash). It also names faf_doctor as the sibling for remediation, so an agent can distinguish it from the other faf_* tools.

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 clear context ('Reads only') and routes the agent to faf_doctor 'for what to fix', which is an explicit alternative. It stops short of stating when scoring itself is the right call versus e.g. faf_bench or faf_trust.

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

Deploy Server