claude-faf-mcp

Overview Schema Source Related Servers Discussions Admin

Diagnose .faf

faf_doctor

Read-onlyIdempotent

Diagnose a project's .faf when faf_score is below 100%: check validation errors, empty score slots, CLAUDE.md presence, and detected formats, returning a read-only checklist with fixes.

Instructions

Diagnose the project's .faf: faf-cli's validateFaf errors, faf-cli's score with every empty slot and the tool that fills it (faf_auto from the repo, faf_go for the 6Ws), whether CLAUDE.md is there, and the formats faf-cli finds in the folder. Returns a checklist of findings, each with its fix. Reads only. Use it when faf_score is below 100%.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`path`	No	Project path. Sets session context for subsequent calls.

Output Schema

TableJSON Schema

Name	Required	Description
`score`	No	faf-cli's score (-1 only with unknown: true), or null when not scored
`valid`	No	faf-cli's validateFaf verdict, or null when no .faf could be read
`checks`	Yes	Number of checks run
`errors`	No	Count of error-level findings
`health`	Yes	Overall verdict: ok \| warning \| error
`unknown`	No	True when the score is not known (an About repo with no about.source_score)
`warnings`	No	Count of warning-level findings
`diagnostics`	Yes	Per-check results

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv6.0.0Sep 13, 2026

addedOutput schema / properties / score

Added value: +{
+  "description": "faf-cli's score (-1 only with unknown: true), or null when not scored",
+  "type": [
+    "number",
+    "null"
+  ]
+}

addedOutput schema / properties / unknown

Added value: +{
+  "description": "True when the score is not known (an About repo with no about.source_score)",
+  "type": "boolean"
+}

addedOutput schema / properties / valid

Added value: +{
+  "description": "faf-cli's validateFaf verdict, or null when no .faf could be read",
+  "type": [
+    "boolean",
+    "null"
+  ]
+}

Changed1 schema field changedv5.9.0Jun 12, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "description": "Health check: an overall verdict plus per-check diagnostics with fixes.",
+  "properties": {
+    "checks": {
+      "description": "Number of checks run",
+      "type": "number"
+    },
+    "diagnostics": {
+      "description": "Per-check results",
+      "items": {
+        "properties": {
+          "fix": {
+            "description": "Suggested fix, if any",
+            "type": "string"
+          },
+          "message": {
+            "type": "string"
+          },
+          "status": {
+            "description": "ok | warning | error",
+            "type": "string"
+          }
+        },
+        "required": [
+          "status",
+          "message"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "errors": {
+      "description": "Count of error-level findings",
+      "type": "number"
+    },
+    "health": {
+      "description": "Overall verdict: ok | warning | error",
+      "type": "string"
+    },
+    "warnings": {
+      "description": "Count of warning-level findings",
+      "type": "number"
+    }
+  },
+  "required": [
+    "health",
+    "checks",
+    "diagnostics"
+  ],
+  "type": "object"
+}

First observedv4.0.0May 2, 2026

TDQS

A3.6/5.0

Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description's 'Reads only' merely restates that. It does add that the output is a checklist of findings each paired with a fix, which is mild extra context. With an output schema present and safety already covered, no deeper disclosure is required, but little is added beyond structured data.

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 verb+resource, and the closing usage rule is short and actionable. The first sentence is a run-on packing several checks and two sibling names into one breath, which costs a little readability but there is no filler.

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 what is diagnosed, the read-only nature, and the trigger condition, and an output schema exists so return values need not be described. For a single-optional-parameter diagnostic tool this is close to complete, missing only explicit exclusions or a follow-up path.

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?

There is a single optional parameter whose schema description is 100% covered ('Project path. Sets session context for subsequent calls.'). The description adds no further meaning about the path argument, so the schema carries the load and baseline 3 applies.

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 ('Diagnose the project's .faf') and enumerates the checks performed: validateFaf errors, score/empty slots, CLAUDE.md presence, formats found. It also names the siblings that supply fixes (faf_auto, faf_go), so it is distinguishable. The dense parenthetical phrasing keeps it just short of a 5.

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?

Gives an explicit trigger condition: 'Use it when faf_score is below 100%', which routes the agent from a sibling tool to this one. It does not state when not to use it or what to do after diagnosis, but the primary selection condition is unambiguous.

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

Deploy Server