Skip to main content
Glama

mFlow

by io.m-flow
OverviewDiscussionsAdmin

create_knowledge_doc

Create a knowledge/documentation entry for a project — a convention, workflow note, metric definition, reference guide, or ADR to persist across sessions and be surfaced back to you (or other agents) as context. Call list_knowledge_docs first to check a similar doc doesn't already exist: there is no update tool yet, so calling this again produces a duplicate, not an overwrite — delete_knowledge_doc the stale one first if you need to replace it. Cannot target "global" (read-only).

ADRs (type "adr") are Architecture Decision Records — one specific architectural decision, not a general note. content MUST include a "## Context", "## Decision", and "## Consequences" section (any other structure is rejected) — write Context as the problem/forces at play, Decision as specifically what was decided (concrete enough that a future agent can check compliance against it), and Consequences as what becomes easier/harder as a result. ADRs are never deleted once accepted — to reverse one, create a new ADR and set the old one's status to "superseded" (via update_knowledge_doc's adrStatus) with supersededBy pointing at the new one's id. An accepted ADR gets synced into a coding-agent repo automatically the next time a task runs there (see repoUrl below for which one), and is injected into every agent's context for that project going forward — so only record a decision here once it is actually decided, not while still exploring options (use adrStatus "proposed" for that, the default).

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
tagsNoOptional free-form tags to help filter/search this doc later
typeYesDoc category: "metric" (a KPI/number definition), "workflow" (how the team works — process, cadence, handoffs), "convention" (a rule/standard the team follows), "guide" (general reference material), or "adr" (a single architectural decision record — see this tool's own description for the required content shape).
titleYesShort, searchable title for this doc
contentYesThe doc's full body text. For type "adr", must contain ## Context, ## Decision, and ## Consequences sections.
repoUrlNoOnly meaningful for type "adr". A PROJECT can have several actual git repos behind it (a frontend, a backend, separate microservices...) — if this decision is about ONE specific repo, name it here ("owner/repo" or a full github.com URL) so it only ever syncs into that repo's docs/adr/ and only that repo's coding-agent tasks get checked against it. Omit for a decision that genuinely applies across every repo in the project (or if you're not sure yet) — that's the safe default, not a shortcut to avoid thinking about it.
adrStatusNoOnly meaningful for type "adr". "proposed" (default) while still under discussion, "accepted" once decided (this is what triggers repo-sync and context injection), or "superseded" if this record is being created already-replaced by another (rare — normally you accept first, then supersede later via update_knowledge_doc).
projectIdYesThe project this doc belongs to — any project id used elsewhere with mFlow (Jira, Trello, or standalone). Must already exist. Cannot be "__global__", which is read-only.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / repoUrl
      Added value: +{
+  "description": "Only meaningful for type \"adr\". A PROJECT can have several actual git repos behind it (a frontend, a backend, separate microservices...) — if this decision is about ONE specific repo, name it here (\"owner/repo\" or a full github.com URL) so it only ever syncs into that repo's docs/adr/ and only that repo's coding-agent tasks get checked against it. Omit for a decision that genuinely applies across every repo in the project (or if you're not sure yet) — that's the safe default, not a shortcut to avoid thinking about it.",
+  "type": "string"
+}
  2. Changed4 schema fields changed
    • addedInput schema / properties / adrStatus
      Added value: +{
+  "description": "Only meaningful for type \"adr\". \"proposed\" (default) while still under discussion, \"accepted\" once decided (this is what triggers repo-sync and context injection), or \"superseded\" if this record is being created already-replaced by another (rare — normally you accept first, then supersede later via update_knowledge_doc).",
+  "enum": [
+    "proposed",
+    "accepted",
+    "superseded"
+  ],
+  "type": "string"
+}
    • changedInput schema / properties / content / description
      Previous value: -"The doc's full body text"New value: +"The doc's full body text. For type \"adr\", must contain ## Context, ## Decision, and ## Consequences sections."
    • changedInput schema / properties / type / description
      Previous value: -"Doc category: \"metric\" (a KPI/number definition), \"workflow\" (how the team works — process, cadence, handoffs), \"convention\" (a rule/standard the team follows), or \"guide\" (general reference material)."New value: +"Doc category: \"metric\" (a KPI/number definition), \"workflow\" (how the team works — process, cadence, handoffs), \"convention\" (a rule/standard the team follows), \"guide\" (general reference material), or \"adr\" (a single architectural decision record — see this tool's own description for the required content shape)."
    • changedInput schema / properties / type / enum
      Previous value: -[
-  "metric",
-  "workflow",
-  "convention",
-  "guide"
-]New value: +[
+  "metric",
+  "workflow",
+  "convention",
+  "guide",
+  "adr"
+]
  3. Added

TDQS

A4.6/5.0
Behavior5/5

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

Goes well beyond the readOnlyHint=false / destructiveHint=false annotations: it discloses that repeat calls duplicate rather than overwrite, that "__global__" is rejected as read-only, that accepted ADRs are auto-synced into a repo and injected into every agent's context, that accepted ADRs are effectively immutable, and that malformed ADR content is rejected outright. These are exactly the behavioral traits an agent must know before invoking.

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 purpose and prerequisites, then a clearly delineated ADR paragraph — the ordering respects how an agent reads. It is dense and long, and the ADR lifecycle (supersede, sync, immutability) is somewhat repeated, but nearly every sentence carries operational information rather than filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-param write tool with no output schema and only title/readOnlyHint/destructiveHint annotations, the description supplies the missing context: failure/duplication behavior, the read-only project guard, subtype-specific content contracts, and post-creation side effects. Nothing an agent needs in order to call this correctly is absent.

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 real meaning on top: the required ## Context / ## Decision / ## Consequences shape for content, what "accepted" triggers for adrStatus, and the multi-repo semantics of repoUrl including the guidance to omit it as the safe default. It clarifies the constraints the enum values imply rather than restating them.

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 ("Create a knowledge/documentation entry for a project") and immediately enumerates the concrete artifact types (convention, workflow note, metric definition, reference guide, ADR). It distinguishes itself from list_knowledge_docs, delete_knowledge_doc, and update_knowledge_doc by name, so an agent can route without opening sibling schemas.

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?

Gives explicit preconditions ("Call list_knowledge_docs first"), the replacement path (delete_knowledge_doc the stale one), and per-subtype guidance for when to use adrStatus "proposed" vs "accepted". However, it asserts "there is no update tool yet" while later referencing "update_knowledge_doc's adrStatus" and "supersede later via update_knowledge_doc" — an internal contradiction that could steer an agent toward delete+recreate when an existing update tool would do.

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

All mFlow toolsInspect
Try in Browser
Pay for results, not tokens.Fund a bounty. Let AI agents compete and collaborate to solve your problems.agentbounties.appAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources