okf_validateAudits how closely a Markdown vault conforms to the Open Knowledge Format, reporting example file paths per rule before the vault is declared a bundle.
Audit how far the vault conforms to the Open Knowledge Format, with example paths per rule; works on a vault not yet declared as a bundle.
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Changes observed during successful MCP inspections.
v4.0.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds two useful behavioral facts beyond that: the report is graded ('how far the vault conforms') rather than binary, and it includes example paths per rule, plus the undeclared-vault precondition. It stops short of describing scope of the audit, failure behavior, or cost, so it is solid but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the audit action and packs the output detail and precondition into trailing clauses. Nothing is wasted, though the semicolon joins two fairly distinct ideas (output content and vault precondition) into one slightly dense line.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description need not explain return values, and with zero parameters there is no input burden. It covers the essential precondition and characterizes the report, leaving only minor gaps such as whether it is read-only in effect on undeclared vaults or how large audits are handled.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly avoids inventing parameter talk and instead spends its words on scope and output content.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: auditing vault conformance to the Open Knowledge Format. The sibling tools okf_convert_links, okf_generate_index, and okf_seed_log are visibly different actions, so an agent can distinguish this audit tool from them without opening the schema, though the description never names them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The clause 'works on a vault not yet declared as a bundle' gives a real precondition that implies when this tool applies. However, there is no explicit when-not guidance and no mention of which sibling (e.g. okf_convert_links) to reach for if the vault is already a bundle or if the agent wants to fix rather than just audit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.