Skip to main content
Glama

deprecate_learning

Soft-retire a stale or incorrect lesson so it stops being recalled while retaining a reversible breadcrumb. Record why and optionally link the lesson that replaces it.

Instructions

Soft-retire a lesson: it stops being recalled, but is kept with a breadcrumb.

    The right tool when a lesson turned out to be wrong or went stale — reversible, and
    preferable to leaving it firing at a lower weight. ``reason`` records why; ``superseded_by``
    points at the lesson that replaces it (omit when nothing does). Retired lessons are visible
    again via ``lessons(..., include_retired=True)`` and revivable with ``restore_learning``.
    

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": {
      "learning_id": "<learning_id>"
    },
    "name": "deprecate_learning"
  }
}

Input Schema

NameRequiredDescriptionDefault
reasonNo
learning_idYes
superseded_byNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.0.0

TDQS

A4.5/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does well: it discloses that the operation is soft/reversible, that the record is retained rather than deleted, that it ceases to be recalled, and how to see it again (lessons(..., include_retired=True)). It stops short of stating any permission requirements or what happens if the lesson is already retired.

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 core effect is front-loaded in the first clause, followed by when-to-use and then parameter notes. It is slightly longer than strictly necessary (the breadcrumb/visibility detail could be tighter), but no sentence is 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?

For a three-parameter mutation with no annotations, the description covers effect, reversibility, recovery path, and parameter intent; an output schema exists so return values need not be explained. It lacks any note on permissions or error/edge conditions, which keeps it short of full completeness.

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 description coverage is 0%, so the description must compensate, and it does for the two non-obvious parameters: reason records why, and superseded_by points at the replacing lesson with explicit guidance to omit it when nothing replaces it. learning_id is only implicitly covered as the target lesson, which is the sole remaining gap.

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 ("Soft-retire a lesson") and immediately defines the resulting state: it stops being recalled but is kept with a breadcrumb. This is clearly distinguishable from siblings like restore_learning, update_learning, and add_learning.

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 an explicit triggering condition ("when a lesson turned out to be wrong or went stale"), an explicit preference against an alternative behavior ("preferable to leaving it firing at a lower weight"), and names the tool that reverses it (restore_learning). Nothing about when to reach for this versus a sibling is left to inference.

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