loom

knowledge_write

Destructive

Create or update a shared knowledge page by slug to store facts or artifacts with citations for other agents to read and revise.

Instructions

Upsert a knowledge page by slug. Two classes: world/ (default) — facts true independent of us. Domain = "music/gear", "software/loom", etc. ours/ — Art-created artifacts, revised-in-place (breakbrain density model, homelab design, wake-chain spec, script templates). Domain starts with "ours/", e.g. "ours/art-ops". On an existing slug: body REPLACES by default (mode: "append" adds to it instead), title/domain follow the write, citations always appended with exact-duplicate dedup — safe to re-send. Epistemic gate (§E1): • conversation-only citations → provisional (both classes). • ours/ domain + any repo citation → internal (ours/ class artifact; repo = git path / commit / live-system probe). • any web/repo citation on a non-ours/ domain → sourced (world/ default). NOTE: repo citations on world-class pages (domain not starting with "ours/") are treated as sourced, not internal. A citation to github.com/someone-else/project is a world source. World filing test: knowledge must be true independent of Jonathan. For our own artifacts use ours/. Shared surface, not a scratchpad: knowledge is readable by other identities (e.g. Mark) and by Jonathan, not just you. Write pages as finished synthesis for that audience — no raw inner-monologue reasoning, no private-to-you deliberation, nothing that assumes only you will ever read it. A personal reflection or working-out-loud note belongs in remember, not here.

Input Schema

Name	Required	Description
`body`	Yes	Synthesized markdown body for the entity or artifact page (max 64 KB)
`mode`	No	Body combine mode when the slug already exists: "replace" (default) overwrites the stored body; "append" adds this body after the existing one. Citations are appended (deduped) in both modes. Ignored when creating a new page.
`slug`	No	Entity key for upsert — stable URL-safe identifier. Derived from title if omitted.
`title`	Yes	Page title — the entity name (e.g. "Mutable Instruments Rings") or artifact name (e.g. "breakbrain density model")
`domain`	Yes	Domain tag. World class: "music/eurorack", "programming/typescript". Ours class: prefix with "ours/" — e.g. "ours/art-ops", "ours/breakbrain", "ours/homelab". Hierarchical string; sub-domains queryable via prefix filter.
`version`	No	ours/ class: artifact version or revision tag (e.g. "v2", "2026-08-31", "t-81"). Preserved across upserts when omitted.
`citations`	Yes	Support citations. At least one required. All-conversation → provisional. ours/ domain + repo → internal. Any web or repo on non-ours/ → sourced.
`created_by`	No	ours/ class: who created or last owned this artifact (e.g. "art", "jonathan"). Preserved across upserts when omitted; defaults to the calling identity for ours/ pages. On the knowledge-only service this must equal your own identity — you cannot attribute a write to a different identity than the one your bearer token resolved to.
`freshness_anchor`	No	The version/date the page's claims are valid as-of — e.g. "Syntakt OS 1.21" for a device, "as of 2026-05" for a topic, or "t-81 / 2026-08-31" for an ours/ artifact. Drives the verification engine: a page is re-verified when this anchor moves or the freshness SLA elapses.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv0.5.1Oct 22, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

changedInput schema / properties / citations / description

Previous value: -"Support citations. At least one required. All-conversation → provisional. Any repo → internal (ours/). Any web → sourced."New value: +"Support citations. At least one required. All-conversation → provisional. ours/ domain + repo → internal. Any web or repo on non-ours/ → sourced."

changedInput schema / properties / citations / items / properties / source_kind / description

Previous value: -"web = external URL; loom_memory = opaque memory ref; conversation = session distillation; repo = git repo path / commit / live-system probe (ours/ class)"New value: +"web = external URL; loom_memory = opaque memory ref; conversation = session distillation; repo = git repo path / commit / live-system probe (signals internal only when domain is ours/; on world-class pages, treated as sourced)"

changedInput schema / properties / created_by / description

Previous value: -"ours/ class: who created or last owned this artifact (e.g. \"art\", \"jonathan\"). Preserved across upserts when omitted."New value: +"ours/ class: who created or last owned this artifact (e.g. \"art\", \"jonathan\"). Preserved across upserts when omitted; defaults to the calling identity for ours/ pages. On the knowledge-only service this must equal your own identity — you cannot attribute a write to a different identity than the one your bearer token resolved to."

Changed11 schema fields changedv0.5.0Sep 4, 2026

changedInput schema / properties / body / description

Previous value: -"Synthesized markdown body for the entity page (max 64 KB)"New value: +"Synthesized markdown body for the entity or artifact page (max 64 KB)"

changedInput schema / properties / citations / description

Previous value: -"Support citations. At least one required. All-conversation support → page stored provisional."New value: +"Support citations. At least one required. All-conversation → provisional. Any repo → internal (ours/). Any web → sourced."

changedInput schema / properties / citations / items / properties / excerpt / description

Previous value: -"Inline supporting quote — link-rot insurance (max 4 KB)"New value: +"Inline supporting quote or repo excerpt — link-rot insurance (max 4 KB)"

changedInput schema / properties / citations / items / properties / source_kind / description

Previous value: -"web = external URL; loom_memory = opaque memory ref; conversation = session distillation"New value: +"web = external URL; loom_memory = opaque memory ref; conversation = session distillation; repo = git repo path / commit / live-system probe (ours/ class)"

changedInput schema / properties / citations / items / properties / source_kind / enum

Previous value: -[
-  "web",
-  "loom_memory",
-  "conversation"
-]New value: +[
+  "web",
+  "loom_memory",
+  "conversation",
+  "repo"
+]

changedInput schema / properties / citations / items / properties / source_locator / description

Previous value: -"URL, memory ref, or session ID"New value: +"URL, memory ref, session ID, or repo path + commit hash"

addedInput schema / properties / created_by

Added value: +{
+  "description": "ours/ class: who created or last owned this artifact (e.g. \"art\", \"jonathan\"). Preserved across upserts when omitted.",
+  "type": "string"
+}

changedInput schema / properties / domain / description

Previous value: -"Domain tag, e.g. \"music/eurorack\", \"programming/typescript\". Hierarchical string; sub-domains queryable via prefix filter."New value: +"Domain tag. World class: \"music/eurorack\", \"programming/typescript\". Ours class: prefix with \"ours/\" — e.g. \"ours/art-ops\", \"ours/breakbrain\", \"ours/homelab\". Hierarchical string; sub-domains queryable via prefix filter."

changedInput schema / properties / freshness_anchor / description

Previous value: -"The version/date the page's claims are valid as-of — e.g. \"Syntakt OS 1.21\" for a device, or \"as of 2026-05\" for a topic. Drives the verification engine: a page is re-verified when this anchor moves or the freshness SLA elapses."New value: +"The version/date the page's claims are valid as-of — e.g. \"Syntakt OS 1.21\" for a device, \"as of 2026-05\" for a topic, or \"t-81 / 2026-08-31\" for an ours/ artifact. Drives the verification engine: a page is re-verified when this anchor moves or the freshness SLA elapses."

changedInput schema / properties / title / description

Previous value: -"Page title — the entity name (e.g. \"Mutable Instruments Rings\")"New value: +"Page title — the entity name (e.g. \"Mutable Instruments Rings\") or artifact name (e.g. \"breakbrain density model\")"

addedInput schema / properties / version

Added value: +{
+  "description": "ours/ class: artifact version or revision tag (e.g. \"v2\", \"2026-08-31\", \"t-81\"). Preserved across upserts when omitted.",
+  "type": "string"
+}

First observedv0.4.1Jul 4, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations declare destructiveHint=true and idempotentHint=false; the description corroborates destruction ("body REPLACES by default") and adds non-annotation behavior: citation dedup, the epistemic gate, and the shared-readership constraint. The phrase "safe to re-send" sits in mild tension with idempotentHint=false, though in context it is scoped to citation dedup rather than the whole write, so this is a clarity wart rather than a contradiction.

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 with the core action and structured into class labels and a gated bullet list, so it scans well. It loses a point for redundancy: the repo-on-world-page rule is stated in the §E1 bullets, in the NOTE, and again in the citations/source_kind schema descriptions.

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 9-parameter, high-complexity mutation tool with no output schema, the description covers the class model, the epistemic gate, and audience expectations thoroughly. It is silent on what a successful upsert returns and on any auth/attribution failure modes (beyond the created_by note), which is the main remaining gap.

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 baseline is 3, but the description contributes real semantics beyond the schema: the relationship between domain class and citation classification (the §E1 gate), the world-filing test for `domain`, and the intended audience for `body`. Only `version`, `created_by`, and `freshness_anchor` get no additional description-level treatment.

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?

Opens with a specific verb+resource ("Upsert a knowledge page by slug") and immediately splits the resource into its two classes with concrete domain examples. An agent can distinguish this from knowledge_supersede, knowledge_move, knowledge_merge, and remember without opening any schema.

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 explicit routing rules: world/ vs ours/ with a stated filing test ("knowledge must be true independent of Jonathan"), plus a named alternative for a whole class of inputs ("A personal reflection or working-out-loud note belongs in `remember`, not here"). That is when-to-use, when-not, and the alternative, all spelled out.

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

knowledge_write

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools