Skip to main content
Glama
Sign In
yof

yof

Official
by yof-dev
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Explain a finding

yof_explain
Read-onlyIdempotent

Explains a yof rule in plain words: what it means, why it matters, its severity, and the safe fix. Use it to understand a finding from yof_check, yof_check_diff, or yof_findings.

Instructions

Explain one yof rule in plain words: what it means, why it matters, how urgent it is and the safe fix. Use it to understand a finding from yof_check, yof_check_diff or yof_findings; use yof_fix_prompt instead for step-by-step instructions for one specific finding. Key rules (secret.) and package rules (package.) are answered on this computer without reading project files; any other rule id is asked of yof.io only when YOF_API_KEY is set, and is an error otherwise. Returns rule, name (or title from yof.io), severity, why and safe_fix.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "rule_id": "<rule_id>"
    },
    "name": "yof_explain"
  }
}

Input Schema

NameRequiredDescriptionDefault
rule_idYesThe rule id exactly as a finding shows it, for example secret.stripe_live or package.made_up.

Output Schema

NameRequiredDescriptionDefault
whyYesWhy it matters.
nameNoReadable rule name (rules answered on this computer).
ruleYesThe rule id.
titleNoReadable rule name (rules answered by yof.io).
safe_fixYesThe safe way to fix it.
severityYesfix_now, fix_week, nice or info.
standardsNoCWE and OWASP references (rules answered by yof.io).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.3.2
    • changedInput schema / properties / rule_id / description
      Previous value: -"The rule id of a finding."New value: +"The rule id exactly as a finding shows it, for example secret.stripe_live or package.made_up."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "properties": {
+    "name": {
+      "description": "Readable rule name (rules answered on this computer).",
+      "type": "string"
+    },
+    "rule": {
+      "description": "The rule id.",
+      "type": "string"
+    },
+    "safe_fix": {
+      "description": "The safe way to fix it.",
+      "type": "string"
+    },
+    "severity": {
+      "description": "fix_now, fix_week, nice or info.",
+      "type": "string"
+    },
+    "standards": {
+      "description": "CWE and OWASP references (rules answered by yof.io).",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "title": {
+      "description": "Readable rule name (rules answered by yof.io).",
+      "type": "string"
+    },
+    "why": {
+      "description": "Why it matters.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "rule",
+    "severity",
+    "why",
+    "safe_fix"
+  ],
+  "type": "object"
+}
  2. First observedv0.3.1

TDQS

A4.8/5.0
Behavior5/5

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

Goes well beyond the annotations by disclosing resolution behavior: secret.* and package.* rules are answered locally without reading project files, while any other rule id is fetched from yof.io only when YOF_API_KEY is set and errors otherwise. That auth dependency and the error condition are exactly the operational context an agent needs before calling, and it also names the returned fields.

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-loads purpose, then usage, then the conditional resolution behavior, then return values — a sensible ordering with no filler. It is a dense three-sentence block; the local-vs-remote clause is necessarily long but could be tightened slightly.

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, yet the description still summarizes the returned fields, and it covers the one real failure mode (missing YOF_API_KEY for non-local rules). For a single-parameter lookup tool with full annotation coverage, nothing an agent needs to call it correctly is missing.

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 pattern, length bound, and example rule id are already documented. The description still adds meaning by grouping rule ids into families (secret.*, package.*, other) that behave differently, which the schema does not convey. It stops short of restating the format rules, which is appropriate.

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 ('Explain one yof rule') and enumerates the content returned: meaning, why it matters, urgency, and safe fix. It explicitly distinguishes itself from yof_fix_prompt, so an agent can choose between them without opening either schema.

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?

Names the exact upstream tools whose output it consumes (yof_check, yof_check_diff, yof_findings) and names the alternative, yof_fix_prompt, with the condition that selects it (step-by-step instructions for one specific finding). When-to-use and when-not-to-use are both explicit.

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

Deploy Server

Other Tools