Skip to main content
Glama
Sign In
Kiln

Kiln

by codeofaxel
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python

save_agent_note

Destructive

Stores persistent notes and preferences across sessions, helping agents remember printer quirks, calibration findings, material settings, and operational knowledge.

Instructions

Save a persistent note or preference that survives across sessions.

Use this to remember printer quirks, calibration findings, material
preferences, or any operational knowledge worth preserving.

Args:
    key: Name for this memory (e.g., ``"z_offset_adjustment"``, ``"pla_temp_notes"``).
    value: The information to store.
    scope: Namespace — ``"global"``, ``"fleet"``, or use *printer_name* for printer-specific.
    printer_name: If provided, scope is automatically set to ``"printer:<name>"``.
    ttl_seconds: Optional time-to-live in seconds.  The note will be
        automatically excluded from queries after this duration.  Pass
        ``None`` (default) for notes that should never expire.

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": {
      "key": "<key>",
      "value": "<value>"
    },
    "name": "save_agent_note"
  }
}

Input Schema

NameRequiredDescriptionDefault
keyYesName for this memory (e.g., ``"z_offset_adjustment"``, ``"pla_temp_notes"``).
scopeNoNamespace — ``"global"``, ``"fleet"``, or use *printer_name* for printer-specific. Default: "global".
valueYesThe information to store.
ttl_secondsNoOptional time-to-live in seconds. The note will be automatically excluded from queries after this duration. Pass ``None`` (default) for notes that should never expire.
printer_nameNoIf provided, scope is automatically set to ``"printer:<name>"``.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv1.5.1
    • addedInput schema / properties / key / description
      Added value: +"Name for this memory (e.g., ``\"z_offset_adjustment\"``, ``\"pla_temp_notes\"``)."
    • addedInput schema / properties / printer_name / description
      Added value: +"If provided, scope is automatically set to ``\"printer:<name>\"``."
    • changedInput schema / properties / scope / description
      Previous value: -"Default: \"global\"."New value: +"Namespace — ``\"global\"``, ``\"fleet\"``, or use *printer_name* for printer-specific. Default: \"global\"."
    • addedInput schema / properties / ttl_seconds / description
      Added value: +"Optional time-to-live in seconds.  The note will be automatically excluded from queries after this duration.  Pass ``None`` (default) for notes that should never expire."
    • addedInput schema / properties / value / description
      Added value: +"The information to store."
  2. Changed4 schema fields changedv1.5.0
    • removedInput schema / properties / printer_name / default
      Removed value: -null
    • removedInput schema / properties / scope / default
      Removed value: -"global"
    • addedInput schema / properties / scope / description
      Added value: +"Default: \"global\"."
    • removedInput schema / properties / ttl_seconds / default
      Removed value: -null
  3. First observedv0.1.0

TDQS

A3.6/5.0
Behavior3/5

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

The annotations flag destructiveHint=true, and the description never explains the destructive behavior — namely that re-saving an existing key presumably overwrites the prior note. That is the single most important behavioral fact for an agent to know before calling it. It does add genuine context beyond the annotations: TTL notes are 'automatically excluded from queries' after expiry, and printer_name silently rewrites scope, but the overwrite semantics remain undisclosed.

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-loaded purpose sentence followed by a usage sentence, with parameters in a clean Args block. The Args block duplicates the schema, which is mild waste, but nothing is padded or buried.

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 should say what a successful save returns (the key? the scope?) and whether duplicate keys overwrite or error. Neither is covered, and for a mutation tool flagged destructive those omissions matter more than the parameter detail, which the schema already handles.

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 description coverage is 100%, and the Args section is essentially a verbatim restatement of the schema property descriptions, so little meaning is added. The one piece of extra signal is the precedence relationship (printer_name automatically overrides scope), which the schema also states. Baseline 3 is appropriate.

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 opens with a specific verb and resource: 'Save a persistent note or preference that survives across sessions,' and the examples (printer quirks, calibration findings, material preferences) make the content domain concrete. It does not name or differentiate itself from the obvious siblings delete_agent_note, clean_agent_memory, or get_agent_context, so it stops short of 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?

'Use this to remember printer quirks, calibration findings, material preferences, or any operational knowledge worth preserving' gives clear when-to-use context with concrete example categories. There are no exclusions or pointers to alternatives — nothing tells the agent when to prefer record_proven_recipe, save_design_version, or a structured credential store over a free-text note.

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