Skip to main content
Glama
Sign In

Fluid Recall

by com.fluidrecall
OverviewDiscussionsAdmin

Grade and next prompt

gradeAndNext

Write. recordReview, then the next due prompt. Requires cardId, rating, reviewedAt optional, and a new idempotencyKey. Schedule from dueAt. Prompts only. Includes deckNote and cardNote (null when unset). Coaching notes are instructions for how an agent should quiz and coach. They are not the answer, not graded content, and not the quiz prompt. A deck note applies to every card in that deck. A card note is optional and additive with the deck note. Retrieve responses (listDue, upcoming-new, inventory, getCard, reveal, and agent session start/next/grade) include deckNote and cardNote so one call carries coaching context. Scripture / dictation: The learner needs every word remembered correctly, but often answers via dictation where punctuation gets messy. They set a deck note instructing the agent to check every word exactly, but not fail on punctuation differences, and to include that reason when coaching. This is only an example — notes can be any coaching preference for how agents should quiz/coach for that deck (or a specific card).

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": {
      "cardId": "<cardId>",
      "rating": "<rating>",
      "idempotencyKey": "<idempotencyKey>"
    },
    "name": "gradeAndNext"
  }
}

Input Schema

NameRequiredDescriptionDefault
asOfNoQueue instant. Omit to use now.
limitNoPage size, not the daily new-card cap.
cardIdYes
deckIdNoOptional deck filter.
ratingYes
extraNewNoRequired when newCardMode is extra.
reviewedAtNoUTC ISO-8601 timestamp ending in Z
newCardModeNo
idempotencyKeyYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -{
-  "additionalProperties": false,
-  "properties": {
-    "asOf": {
-      "description": "UTC ISO-8601 timestamp ending in Z",
-      "type": "string"
-    },
-    "due": {
-      "items": {
-        "additionalProperties": false,
-        "properties": {
-          "answerIncluded": {
-            "enum": [
-              false
-            ],
-            "type": "boolean"
-          },
-          "cardId": {
-            "format": "uuid",
-            "type": "string"
-          },
-          "cardNote": {
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "deckId": {
-            "format": "uuid",
-            "type": "string"
-          },
-          "deckName": {
-            "type": "string"
-          },
-          "deckNote": {
-            "type": [
-              "string",
-              "null"
-            ]
-          },
-          "dueAt": {
-            "description": "UTC ISO-8601 timestamp ending in Z",
-            "type": "string"
-          },
-          "prompt": {
-            "description": "The quiz prompt. The answer is never in this response.",
-            "type": "string"
-          },
-          "queue": {
-            "enum": [
-              "learning",
-              "review",
-              "new"
-            ],
-            "type": "string"
-          }
-        },
-        "type": "object"
-      },
-      "type": "array"
-    },
-    "first": {
-      "anyOf": [
-        {
-          "additionalProperties": false,
-          "properties": {
-            "answerIncluded": {
-              "enum": [
-                false
-              ],
-              "type": "boolean"
-            },
-            "cardId": {
-              "format": "uuid",
-              "type": "string"
-            },
-            "cardNote": {
-              "type": [
-                "string",
-                "null"
-              ]
-            },
-            "deckId": {
-              "format": "uuid",
-              "type": "string"
-            },
-            "deckName": {
-              "type": "string"
-            },
-            "deckNote": {
-              "type": [
-                "string",
-                "null"
-              ]
-            },
-            "dueAt": {
-              "description": "UTC ISO-8601 timestamp ending in Z",
-              "type": "string"
-            },
-            "prompt": {
-              "description": "The quiz prompt. The answer is never in this response.",
-              "type": "string"
-            },
-            "queue": {
-              "enum": [
-                "learning",
-                "review",
-                "new"
-              ],
-              "type": "string"
-            }
-          },
-          "type": "object"
-        },
-        {
-          "type": "null"
-        }
-      ]
-    },
-    "newCards": {
-      "additionalProperties": false,
-      "properties": {
-        "dayStart": {
-          "description": "UTC ISO-8601 timestamp ending in Z",
-          "type": "string"
-        },
-        "nextDayStart": {
-          "description": "UTC ISO-8601 timestamp ending in Z",
-          "type": "string"
-        },
-        "remainingToday": {
-          "type": "integer"
-        },
-        "waiting": {
-          "type": "integer"
-        }
-      },
-      "type": "object"
-    },
-    "review": {
-      "additionalProperties": false,
-      "properties": {
-        "cardId": {
-          "format": "uuid",
-          "type": "string"
-        },
-        "dueAt": {
-          "description": "UTC ISO-8601 timestamp ending in Z",
-          "type": "string"
-        },
-        "idempotentReplay": {
-          "type": "boolean"
-        },
-        "intervalMinutes": {
-          "type": "number"
-        },
-        "lapses": {
-          "type": "integer"
-        },
-        "rating": {
-          "enum": [
-            "again",
-            "hard",
-            "good",
-            "easy"
-          ],
-          "type": "string"
-        },
-        "reps": {
-          "type": "integer"
-        },
-        "reviewId": {
-          "format": "uuid",
-          "type": "string"
-        },
-        "reviewedAt": {
-          "description": "UTC ISO-8601 timestamp ending in Z",
-          "type": "string"
-        }
-      },
-      "type": "object"
-    }
-  },
-  "type": "object"
-}New value: +null
  2. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "additionalProperties": false,
+  "properties": {
+    "asOf": {
+      "description": "UTC ISO-8601 timestamp ending in Z",
+      "type": "string"
+    },
+    "due": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "answerIncluded": {
+            "enum": [
+              false
+            ],
+            "type": "boolean"
+          },
+          "cardId": {
+            "format": "uuid",
+            "type": "string"
+          },
+          "cardNote": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "deckId": {
+            "format": "uuid",
+            "type": "string"
+          },
+          "deckName": {
+            "type": "string"
+          },
+          "deckNote": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "dueAt": {
+            "description": "UTC ISO-8601 timestamp ending in Z",
+            "type": "string"
+          },
+          "prompt": {
+            "description": "The quiz prompt. The answer is never in this response.",
+            "type": "string"
+          },
+          "queue": {
+            "enum": [
+              "learning",
+              "review",
+              "new"
+            ],
+            "type": "string"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "first": {
+      "anyOf": [
+        {
+          "additionalProperties": false,
+          "properties": {
+            "answerIncluded": {
+              "enum": [
+                false
+              ],
+              "type": "boolean"
+            },
+            "cardId": {
+              "format": "uuid",
+              "type": "string"
+            },
+            "cardNote": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "deckId": {
+              "format": "uuid",
+              "type": "string"
+            },
+            "deckName": {
+              "type": "string"
+            },
+            "deckNote": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "dueAt": {
+              "description": "UTC ISO-8601 timestamp ending in Z",
+              "type": "string"
+            },
+            "prompt": {
+              "description": "The quiz prompt. The answer is never in this response.",
+              "type": "string"
+            },
+            "queue": {
+              "enum": [
+                "learning",
+                "review",
+                "new"
+              ],
+              "type": "string"
+            }
+          },
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "newCards": {
+      "additionalProperties": false,
+      "properties": {
+        "dayStart": {
+          "description": "UTC ISO-8601 timestamp ending in Z",
+          "type": "string"
+        },
+        "nextDayStart": {
+          "description": "UTC ISO-8601 timestamp ending in Z",
+          "type": "string"
+        },
+        "remainingToday": {
+          "type": "integer"
+        },
+        "waiting": {
+          "type": "integer"
+        }
+      },
+      "type": "object"
+    },
+    "review": {
+      "additionalProperties": false,
+      "properties": {
+        "cardId": {
+          "format": "uuid",
+          "type": "string"
+        },
+        "dueAt": {
+          "description": "UTC ISO-8601 timestamp ending in Z",
+          "type": "string"
+        },
+        "idempotentReplay": {
+          "type": "boolean"
+        },
+        "intervalMinutes": {
+          "type": "number"
+        },
+        "lapses": {
+          "type": "integer"
+        },
+        "rating": {
+          "enum": [
+            "again",
+            "hard",
+            "good",
+            "easy"
+          ],
+          "type": "string"
+        },
+        "reps": {
+          "type": "integer"
+        },
+        "reviewId": {
+          "format": "uuid",
+          "type": "string"
+        },
+        "reviewedAt": {
+          "description": "UTC ISO-8601 timestamp ending in Z",
+          "type": "string"
+        }
+      },
+      "type": "object"
+    }
+  },
+  "type": "object"
+}
  3. First observed

TDQS

C2.9/5.0
Behavior4/5

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

Beyond the annotations (which only declare non-read-only, non-destructive, open-world), the description discloses real behavioral facts: it writes a review then returns the next prompt, the response carries deckNote/cardNote (null when unset), and a fresh idempotencyKey is required. It does not cover auth, rate limits, or what happens on key reuse, but it adds substantial context the annotations lack.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The opening is a broken fragment ('Write.') and the core behavior is buried under a long shared-concept essay on deckNote/cardNote plus a Scripture/dictation example. Much of the volume is boilerplate applicable to many sibling tools rather than this call, so the front-loading and size are poor.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description does carry return information (next due prompt plus deckNote/cardNote), which is valuable. But for a 9-parameter tool at 56% schema coverage it omits the shape/fields of the returned prompt and several parameters, leaving gaps an agent must guess at.

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?

With 56% schema coverage, the description adds genuine meaning for a few params: cardId/rating required, reviewedAt optional, and a 'new idempotencyKey' (freshness requirement absent from the schema). However it ignores limit, deckId, extraNew, and newCardMode, and 'Schedule from dueAt' references a field not present in the schema (the actual param is asOf), which is confusing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

After parsing the fragmented opener 'Write. recordReview, then the next due prompt,' the tool's job (record a graded review and return the next due prompt) is understandable, but the sentence is malformed and never states the verb+resource cleanly. It mentions the sibling recordReview only as an internal step, so it does not clearly distinguish itself from calling recordReview followed by nextDue.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Sibling names (listDue, getCard, reveal, session start/next/grade) appear only to say which responses carry deckNote/cardNote, not to route the agent between gradeAndNext and recordReview/nextDue. There is no explicit when-to-use, when-not, or prerequisite guidance; only the terse 'Prompts only' scope note hints at intended use.

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

All Fluid Recall toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources