Skip to main content
Glama

cachly — Explain it once. Every AI knows it.

learn_from_attempts

Store a lesson AFTER any non-trivial task (deploy, debug, fix, decision); future sessions recall it. instance_id may be omitted; the configured instance is used — never guess one. If the topic already exists, the write is an UPDATE and REQUIRES grund (one line: WHY the previous version was wrong) — without it the update is rejected. A conflicting outcome triggers a contradiction warning. Example: learn_from_attempts(topic="deploy:api", outcome="success", what_worked="PORT 3095 SERVES WHISPER — nohup docker compose up -d", severity="critical")

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": {
      "topic": "<topic>",
      "outcome": "<outcome>",
      "what_worked": "<what_worked>"
    },
    "name": "learn_from_attempts"
  }
}

Input Schema

NameRequiredDescriptionDefault
tagsNoTopic tags for filtering (e.g. ["bash", "deploy", "env"])
groupNoOptional sub-team scope, e.g. "backend". Only that group and admins see it. Independent of visibility.
grundNoOne line: WHY the previous version was wrong, like a commit message. REQUIRED when the topic already exists; optional on first write.
topicYesShort slug, e.g. "deploy:web", "debug:redis-tls", "fix:generate-series"
authorNoWho is storing this lesson, e.g. "alice". Enables cross-author reuse tracking.
contextNoThe SYMPTOM in the words someone would search for, before they knew the fix ("deploy stuck, rollout not finishing"). Plus error messages and root cause. Optional but high-value: it is what closes the gap between the question and the answer.
ersetztNoTopic slug of an OLDER lesson this one refutes. The old one is suppressed in smart_recall and shows a "superseded" banner.
gilt_abNoISO date since when the FACT is true (vs. when written). Omit if unknown. A replacement sets gilt_bis on the old lesson (then shown as history). About the fact, NOT an age decay.
outcomeYesDid it work?
serviceNoService or system this lesson concerns, e.g. "prometheus", "auth-service".
commandsNoCommands that worked or failed (e.g. ["rsync -avz ...", "docker compose up -d"])
severityNoImpact severity: critical (blocks work/deploy), major (significant slowdown), minor (nice to know). Default: major.
gilt_fuerNoVersion scope of the FACT, package@range, all must hold: ["next@<15", "react@>=18 <19", "go@>=1.22", "python:fastapi@<0.110"]. Recall ranks a lesson that does not fit the project versions last, marked, never hidden; unknown = no change. Omit on update to keep, [] clears.
depends_onNoPrerequisites, e.g. ["node:>=20", "docker:running"]. A stale one flags dependent lessons for review.
file_pathsNoFiles involved in this lesson (e.g. ["infra/deploy.sh", ".env"])
visibilityNoWho can see it: "team" (default) = all members, "private" = only via exact recall_best_solution, "public" = same as team for now.
instance_idNoUUID of the cache instance.
what_failedNoWhat did NOT work (optional but valuable)
what_workedYesWhat solved it. LEAD WITH THE DECISIVE FACT (the number, address, command) in the first 100 characters — briefings truncate there.
service_kindNo"service" (default) for an application, "system" for infrastructure like prometheus or redis.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A3.8/5.0
Behavior3/5

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

With no annotations, the description carries the full burden. It discloses important behavior: updates require `grund`, missing `grund` causes rejection, conflicting outcomes trigger a warning, and `instance_id` should not be guessed. However, it does not cover permissions, visibility effects, or other write side effects.

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 description is front-loaded with the core action and timing, then proceeds to instance handling, update rules, contradiction warnings, and an example. It is fairly dense but each sentence contributes useful invocation guidance.

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?

For a 20-parameter write tool with no annotations or output schema, the description covers the most important operational constraints: when to write, how updates differ, the `grund` requirement, instance handling, and the contradiction warning. The remaining parameter details are well covered by the schema itself.

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 schema already documents all 20 parameters. The description adds workflow-level meaning for `instance_id` ('may be omitted; configured instance is used — never guess one') and reinforces the conditional `grund` requirement, plus a concrete example showing typical values.

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?

The description states a specific verb and resource: 'Store a lesson' after a task, with the future-recall benefit made explicit. It does not name or distinguish itself from siblings such as remember_context or team_learn, which keeps it from 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?

It gives clear timing ('AFTER any non-trivial task') and names task types such as deploy, debug, fix, and decision. It also gives the key update condition requiring `grund`, but it does not mention alternatives or when not to use this tool.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.