markdown-vault-mcp

OKF: Seed log.md

okf_seed_log

Create a dated log.md from a folder's git history, one section per day, newest first. Covers the 100 most recent commits and never replaces an existing log.

Instructions

Create a folder's Open Knowledge Format log.md from the git history of the notes under it, one dated section per day, newest first.

It never replaces an existing log.md. It covers the 100 most recent commits. A vault without git history gets an empty log.

Input Schema

Name	Required	Description	Default
`folder`	No	Folder to write log.md in, whose history it covers, such as `"guides"`; omit for the bundle root and the whole vault's history.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv6.1.0Nov 2, 2026

changedInput schema / properties / folder / description

Previous value: -"Vault-relative folder to write log.md into and scope\nhistory to (e.g. \"guides\"). Omit for the bundle root\n(whole-vault history)."New value: +"Folder to write log.md in, whose history it covers, such as `\"guides\"`;\nomit for the bundle root and the whole vault's history."

Addedv4.0.0Aug 26, 2026

TDQS

A4.2/5.0

Behavior4/5

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

Annotations already mark this as a non-read-only, non-idempotent, non-destructive write. The description adds real value on top: a hard 100-commit cap, the guarantee that existing log.md files are untouched, and the edge case of a vault with no git history yielding an empty log. It does not clarify whether the call fails or silently no-ops when a log already exists.

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 short sentences, zero padding, with the core action and output shape front-loaded before the constraints. Every sentence carries distinct information (what it builds, what it won't overwrite, the commit limit, the empty-history case).

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?

With an output schema present and full parameter coverage, the description covers the limits and edge cases an agent needs before invoking. The remaining gap is failure semantics when log.md already exists and whether git availability is a precondition, which matters for a write tool.

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 single 'folder' parameter is fully documented in the schema, including the default-to-vault-root behavior. The description adds no meaning beyond that, so the baseline of 3 applies.

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 folder's Open Knowledge Format log.md') plus the source of content ('from the git history of the notes under it') and the resulting shape ('one dated section per day, newest first'). This clearly separates it from siblings like get_history, okf_validate, and okf_generate_index, which read or transform rather than seed a log file.

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 clear operating context and an implicit exclusion ('It never replaces an existing log.md'), which tells an agent not to call it expecting a refresh. It stops short of naming alternatives (e.g., get_history for raw commit data) or stating prerequisites such as needing a git-backed vault.

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