ontology-atlas

Overview Schema Source Related Servers Discussions Admin

list_concepts

Read-only

List ontology nodes to grasp a codebase's mental model. Filter by kind, domain, or modification time; paginate through large vaults for incremental sync.

Instructions

List every ontology node in the vault (each .md file with a frontmatter kind:). Filter by kind, domain, and/or since (mtime-based incremental sync). Large vaults are resumable with offset + limit; always follow pagination.nextOffset while hasMore is true. AI agents call this first to grasp the codebase's mental model.

Input Schema

TableJSON Schema

Name	Required	Description
`kind`	No	Filter to one canonical ontology kind (project, domain, capability, element, document, vault-readme). Omit to return all. Invalid kind typos fail closed with nearest-value hints instead of returning an empty list.
`limit`	No	Positive integer max rows to return. Defaults to 100, max 500.
`since`	No	Non-negative mtime threshold. Filter to nodes with `mtime > since` (ms). Pair with the `mtime` returned in earlier `list_concepts` / `get_concept` responses for incremental sync — "what changed since I last looked". Strict greater-than (mtime === since is excluded) so re-passing the max from a previous response does not double-fetch.
`domain`	No	Filter to nodes whose frontmatter `domain:` matches this slug (e.g. "auth"). Combine with `kind` for "all capabilities under auth" in one call. Use the domain slug, not the title.
`offset`	No	Zero-based page offset applied after kind/domain/since filters. Resume at pagination.nextOffset until hasMore is false; ordering is deterministic by canonical slug.
`summary`	No	When true, each node row includes a `summary` (max 200 chars, prose-only — heading / table / code block / image / divider / list / quote are skipped and only the first paragraph is kept, same `extractSummaryExcerpt` helper as `get_concept` / `find_evidence`). Useful for "scan + overview" without N follow-up `get_concept` calls. Default false to keep payload small.

Output Schema

TableJSON Schema

Name	Required	Description
`nodes`	Yes
`total`	Yes	Total number of matching ontology nodes before the limit is applied.
`limited`	Yes	True when this page does not contain every matching row.
`returned`	Yes	Number of rows returned in this page.
`vaultRoot`	Yes	Resolved vault root path used for the listing.
`pagination`	Yes
`summaryHint`	No	Only present when at least one row carries a partial summary — names the follow-up call that returns the full bodies.
`vaultWarnings`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.13.0Sep 11, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral detail beyond annotations: pagination semantics ('always follow pagination.nextOffset while hasMore is true'), incremental sync via mtime, and resumability for large vaults. This gives the agent practical execution guidance without contradicting any annotation.

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?

The description is three sentences with zero filler. It front-loads the core purpose, then packs filter, pagination, and intended usage into compact, high-value clauses. Every sentence earns its place.

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?

Given the rich input schema, output schema, and annotations, the description covers everything an agent needs: what the tool returns, how to filter, how to paginate, and when to call it. The incremental sync and pagination protocol are both stated clearly, so no critical behavioral gap remains for this list-style read 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%, so the input schema already documents every parameter thoroughly, including enums, defaults, and filter behavior. The description adds a high-level summary of filtering ('Filter by kind, domain, and/or since') and pagination, but does not need to repeat schema details. Baseline 3 is appropriate because the schema carries the semantic load.

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?

The description names a specific verb and resource: 'List every ontology node in the vault', with a precise definition ('each .md file with a frontmatter kind:'). This clearly distinguishes it from sibling tools like list_kinds (which lists kinds) and get_concepts (which fetches specific concepts). The scope is unambiguous and immediately actionable.

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?

The description explicitly states a primary usage context: 'AI agents call this first to grasp the codebase's mental model.' It also explains when to use pagination and incremental sync. However, it does not explicitly say when to prefer alternatives such as list_kinds or get_concepts, so usage guidance is strong but not fully exclusionary.

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