Skip to main content
Glama
dat999zx

knowl

by dat999zx
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

knowl_update

Destructive

Update existing knowledge items to replace stale or contradicted memory, revising metadata, status, or content. Optionally supersede outdated items by pointing them to the new version.

Instructions

Update the metadata, status, or content of an existing knowledge item. Use immediately when execution reveals stale or contradicted memory instead of adding duplicates. To retire an outdated item in favour of one you just stored, call this with id set to the NEW item and supersedeId set to the OUTDATED item.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
idYesThe unique ID of the knowledge item.
repoNoDo this as another repo in this workspace, named as the manifest names it. Use when you are finishing THAT repo's work from here: the call applies to its store exactly as if you had run it there, including retiring its knowledge, and what you write is stamped as its own. Omit it -- the normal case -- and everything applies here. Not for a drive-by correction of something you noticed in passing while working on this repo.
titleNoNew title.
sourceNoUpdated source label.
statusNoNew status.
contentNoNew content markdown.
categoryNoCorrected category, when an item was filed as the wrong kind of thing. Use it rather than re-storing the item: category is what garbage collection reads, so an item that is really a decision but filed as state is on the archive path, and re-storing to fix that discards the assertion history and access record that show it mattered.
freshnessNoOptional freshness override. Defaults to fresh when updating reviewed knowledge content or provenance.
reasoningNoUpdated reasoning.
supersedeIdNoId of a DIFFERENT active item to retire, pointing it at the item named by `id` as its replacement. This is not the item being updated. Checked before the update is written, so an unknown id changes nothing.
sourceCommitNoUpdated git commit for the reviewed knowledge.
affectedPathsNoUpdated repository-relative file paths tied to this knowledge.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv5.23.0

TDQS

A4.6/5.0
Behavior4/5

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

The annotations already carry destructiveHint=true and openWorldHint=false, so the description only needs to add context; it does so by explaining that updates can retire another item through supersedeId and by clarifying the NEW vs OUTDATED id relationship. It does not contradict the annotations and gives enough behavioral color to support safe invocation.

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

Conciseness5/5

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

Three sentences: one purpose statement, one usage trigger, one special-case recipe. It is front-loaded and contains no 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 destructive multi-parameter update tool with no output schema, the description plus rich per-parameter schema descriptions cover the main use and the tricky supersede case. It could add a note about what happens on success or permissions, but the agent has enough to call it correctly.

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 100%, so the baseline is 3, but the description adds extra meaning by mapping id to the NEW item and supersedeId to the OUTDATED item, which is the trickiest parameter relationship in this tool. Most other parameters remain adequately explained by the schema.

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?

The description opens with a specific verb and resource ('Update the metadata, status, or content of an existing knowledge item') and clearly differentiates itself from the duplicate-adding path by saying it should be used instead of adding duplicates. The retire/supersede explanation further defines a distinct responsibility.

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?

It gives an explicit trigger ('when execution reveals stale or contradicted memory'), an explicit when-not ('instead of adding duplicates'), and a concrete recipe for the retire case with correct id/supersedeId roles. This is actionable usage guidance beyond a generic intent statement.

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