Open an Open Knowledge Format bundle and describe what is in it. Start here.

An OKF bundle is a directory of markdown files with YAML frontmatter, each describing one concept — a dataset, table, metric, API, playbook, policy, or attested computation.

Args:

• bundle_path (string): directory containing the bundle

• response_format ('markdown' | 'json'): default 'markdown'

Returns: { "name": string, // bundle directory name "concept_count": number, "types": { [type: string]: number }, // concept count per OKF type "groups": [{ "group": string, "count": number }], // top-level directories "health_summary": { "broken_links": number, "missing_descriptions": number, "untyped": number, "stale": number, "aging": number, "undated": number, "unverified": number, "deprecated": number, "orphans": number } }

Examples:

• Use when: "What's in the bundle at ./knowledge?" -> bundle_path="./knowledge"

• Use when: you need the type names before filtering okf_list_concepts

• Don't use when: you already know the concept id (use okf_get_concept)

Error Handling:

• Returns a message naming the path if the directory does not exist

• Returns a message explaining what a bundle is if the directory holds no concept docs

List concepts, optionally filtered by type, tag, or lifecycle status.

Returns summaries without bodies, so it is safe to call on a large bundle. Use okf_get_concept to read one in full.

Args:

• bundle_path (string): directory containing the bundle

• type (string, optional): exact OKF type, e.g. "Metric", "BigQuery Table", "Attested Computation"

• tag (string, optional): exact tag

• status ('draft' | 'stable' | 'deprecated', optional): lifecycle filter (spec §5.4)

• trust ('unverified' | 'machine-confirmed' | 'human-reviewed', optional): trust tier (spec §5.3)

• limit (number): 1-200, default 50

• offset (number): default 0

• response_format ('markdown' | 'json'): default 'markdown'

Returns: { "total": number, "count": number, "offset": number, "has_more": boolean, "next_offset": number, // present only when has_more "concepts": [{ "id": string, "title": string, "type": string, "description": string, "tags": string[], "resource": string, "status": "draft"|"stable"|"deprecated", "trust": "unverified"|"machine-confirmed"|"human-reviewed", "verified_by": string[], "verified_at": string, "updated_at": string, "stale_since": string }] }

Examples:

• Use when: "What metrics are defined?" -> type="Metric"

• Use when: "Which definitions has nobody verified?" -> trust="unverified"

• Use when: "Show me anything deprecated" -> status="deprecated"

Error Handling:

• An unmatched type or tag returns an empty list plus the values that do exist

Read a single concept in full: its frontmatter, trust and lifecycle signals, provenance, body, and links.

Args:

• bundle_path (string): directory containing the bundle

• id (string): concept id — the file path without .md, e.g. "metrics/revenue"

• include_body (boolean): default true; set false for metadata only

• response_format ('markdown' | 'json'): default 'markdown'

Returns: { "id": string, "title": string, "type": string, "description": string, "tags": string[], "resource": string, "status": ..., "trust": ..., "verified_by": string[], "verified_at": string, "updated_at": string, "stale_since": string, "generated": { "by": string, "at": string }, "sources": [{ "id": string, "resource": string, "title": string, "author": string, "lastModified": string, "usageCount": number }], "computation": { // present only for type "Attested Computation" "runtime": string, "parameters": [{ "name": string, "type": string, "required": boolean }], "path": string, "executor": { "resource": string, "receipt": string[] }, "attester": { "resource": string } }, "links_to": string[], "cited_by": string[], "body": string // omitted when include_body is false }

Trust and freshness are worth checking before relying on a definition: "trust" is derived from verified (§5.3) and "stale_since" from stale_after (§5.5). They are advisory signals, not access control.

For an Attested Computation, the caller may supply values for the declared parameters ONLY, and must never author or rewrite the computation itself — that boundary is the point of the type (§10).

Examples:

• Use when: "How is revenue defined?" -> id="metrics/revenue"

• Use when: you need a concept's sources to cite it

Error Handling:

• An unknown id returns near-miss suggestions from the bundle

Full-text search over a bundle's concepts — titles, ids, types, tags, descriptions, and bodies.

Args:

• bundle_path (string): directory containing the bundle

• query (string): search text, 1-200 characters

• limit (number): 1-50, default 10

• response_format ('markdown' | 'json'): default 'markdown'

Returns: { "query": string, "count": number, "results": [{ "id": string, "title": string, "type": string, "description": string, "tags": string[], "status": ..., "trust": ..., "updated_at": string, "stale_since": string }] }

Examples:

• Use when: "Where is churn defined?" -> query="churn"

• Use when: you do not know the concept id

• Don't use when: you have the exact id (use okf_get_concept, it is cheaper)

Error Handling:

• No matches returns the available types and tags to redirect the search

Analyze a bundle for documentation-health problems: broken links, missing descriptions, untyped concepts, staleness, unverified and deprecated content, and orphans.

Two distinct notions of "old" are reported separately, and conflating them is the mistake this guards against:

• "stale" means past the author's own stale_after date (spec §5.5) — an explicit expiry.

• "aging" means not updated in over a year — a heuristic, not part of the spec. A concept can be two years old and deliberately current, or a week old and expired.

Args:

• bundle_path (string): directory containing the bundle

• as_of (string, optional): ISO date (YYYY-MM-DD) to evaluate staleness against, instead of today

• response_format ('markdown' | 'json'): default 'markdown'

Returns: { "as_of": string, "broken_links": [{ "from": string, "target": string }], "missing_descriptions": string[], "untyped": string[], "stale": [{ "id": string, "stale_since": string }], "aging": [{ "id": string, "updated_at": string }], "undated": string[], "unverified": string[], "deprecated": string[], "orphans": string[] }

Examples:

• Use when: "Is anything in this catalog out of date?"

• Use when: "What still needs human review?" -> read "unverified"

• Use when: auditing before relying on a bundle

Error Handling:

• An invalid as_of returns a message naming the expected YYYY-MM-DD format

Check a bundle against the OKF v0.2 specification.

Errors are the three conformance rules of spec §11: every non-reserved .md file has a parseable YAML frontmatter block, every block has a non-empty type, and reserved files (index.md, log.md) follow their structure.

Warnings are soft guidance the spec says consumers MUST tolerate — broken links, missing optional fields, unknown types. A bundle with warnings is still conformant, and §11 explicitly forbids rejecting a bundle for them.

Args:

• bundle_path (string): directory containing the bundle

• response_format ('markdown' | 'json'): default 'markdown'

Returns: { "conformant": boolean, // true when there are zero errors "checked_version": string, // OKF version validated against "declared_version": string, // okf_version from the root index.md, when declared (§12) "concept_count": number, "error_count": number, "warning_count": number, "errors": string[], "warnings": string[] }

Examples:

• Use when: "Is this bundle valid OKF?"

• Use when: authoring a bundle and checking work before publishing

• Don't use when: you want quality signals rather than conformance (use okf_health_report)

Error Handling:

• A missing or non-directory path returns a message naming it

Drop the cached copy of a bundle so the next call re-reads it from disk.

Bundles are cached per path for speed. Call this after editing files, otherwise subsequent tools keep answering from the version loaded earlier.

Args:

• bundle_path (string, optional): bundle to drop; omit to drop every cached bundle

Returns: { "cleared": number } // how many cached bundles were dropped

Examples:

• Use when: you have just written to a bundle and want fresh results

• Don't use when: you have only been reading (the cache is already correct)