Skip to main content
Glama
Sign In
yof

yof

Official
by yof-dev
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Lessons from merged fixes

yof_lessons
Read-onlyIdempotent

Lists lessons from merged Patch fixes to show what was fixed, which pull request confirmed it, and how to avoid repeating the problem in similar code.

Instructions

List short lessons from Patch fixes merged in your projects: what was fixed, in which pull request, whether yof's next check confirmed it, and how to avoid it next time. Use it before writing similar code so the same problem does not come back; use yof_patch_status for pull requests still open. Needs YOF_API_KEY; sends only app_id to yof.io, which answers from stored data (up to 50 merged pull requests, most recently opened first). Returns lessons (repository, pull_request, merged, rule, note, avoid_next_time); an empty list means no Patch fix has been merged yet.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "yof_lessons"
  }
}

Input Schema

NameRequiredDescriptionDefault
app_idNoOne app's id, to list only that app's lessons. Default: every app in the account.

Output Schema

NameRequiredDescriptionDefault
lessonsYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.3.2
    • changedInput schema / properties / app_id / description
      Previous value: -"One app's id (default: all)."New value: +"One app's id, to list only that app's lessons. Default: every app in the account."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "properties": {
+    "lessons": {
+      "items": {
+        "properties": {
+          "avoid_next_time": {
+            "description": "One sentence on avoiding it.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "merged": {
+            "description": "ISO time.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "note": {
+            "description": "What was fixed and whether the next check confirmed it.",
+            "type": "string"
+          },
+          "pull_request": {
+            "description": "Pull request number.",
+            "type": "integer"
+          },
+          "repository": {
+            "description": "owner/name on GitHub.",
+            "type": "string"
+          },
+          "rule": {
+            "description": "Rule id.",
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "lessons"
+  ],
+  "type": "object"
+}
  2. First observedv0.3.1

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description still adds meaningful context: the YOF_API_KEY requirement, the exact data egress boundary ("sends only app_id to yof.io"), that it answers from stored data, and the 50-merged-PR cap ordered most-recently-opened first. That cap and the record shape are exactly the kind of operational detail annotations cannot carry; only the empty-list semantics of the output are covered by the output schema, so this is slightly redundant but the truncation limit is genuinely new.

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?

Three front-loaded sentences with no filler: purpose and content first, routing second, operational constraints and return shape last. The parenthetical field list (repository, pull_request, merged, rule, note, avoid_next_time) overlaps with the output schema, so it costs a few words that don't fully earn their place.

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?

Covers everything an agent needs for a zero-required-parameter read tool: auth requirement, data boundary, result cap and ordering, the meaning of an empty result, and the fields returned. With an output schema present, the description still supplies the empty-list interpretation that makes results actionable.

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 coverage is 100%, so the single app_id parameter, its UUID pattern, and its default are already fully documented. The description only reinforces this by saying app_id is the sole field transmitted to yof.io, which adds privacy context but no new invocation syntax. Baseline 3 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 ("List short lessons") and enumerates the content of each lesson: what was fixed, the pull request, whether the next check confirmed it, and how to avoid it. It explicitly separates itself from yof_patch_status (open pull requests), so an agent can route correctly 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?

Gives a concrete when-to-use rule ("before writing similar code so the same problem does not come back") and names the alternative with the condition that selects it ("use yof_patch_status for pull requests still open"). Both the positive and negative cases are covered.

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