The montology server provides ontology and code analysis tools to manage vocabulary, scan codebases, and enforce naming conventions, helping to prevent design drift.
ontology_check: Check if a name is free, defined, or ruled on (e.g., renamed/retired). Should be run before naming anything in the codebase.
ontology_words: Retrieve the vocabulary as rows, optionally filtered by kind (core, inner, adopted, custom, or all).
ontology_add: Author a new word with a name, definition, and optional code, kind, test, and owner. Enforces check-first (refuses if name is taken) and re-renders the words skill on success.
scan_surface: Scan what the codebase declares, returning counts by language and noting skipped items.
scan_candidates: Identify recurring declared names that have no ontology word yet, returning top N candidates.
ontology_lint: Run the ontology gate to detect collisions, code resolution issues, and drift, with each failure accompanied by its suggested repair.
structural_search: Perform AST-aware search using ast-grep patterns (e.g., def $F($$$) with lang=python), going beyond plain text search, optionally filtering by language.
Provides optional integration with Ollama to run a local gemma3:270m model for drafting one-line vocabulary definitions when no host agent is available.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@montology check if 'thread' is free in our ontology"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Your codebase's vocabulary, enforced — and your agents can't drift it. Words and rulings live in a database; a tree-sitter scan checks every named thing your code declares against them — classes, structs, functions, types, modules, protocols — across twelve languages; a pre-write hook corrects your coding agent before drift ever lands.
montology reads what your code already declares — every named thing in Python, TypeScript, Go, Rust, Swift, Java, Ruby, Elixir, C and C++ (and, where there is a UI, the Tailwind theme and the CSS) — and turns it into an ontology with a gate: drift fails CI with the file, the line, and the repair. It is a vocabulary layer for all of your code, not a styling tool; a repo with no UI in it uses every part of this except the last.
# the CLI
uvx --from "git+https://github.com/shinyobjectz/montology#subdirectory=.monty/cli" monty init
# the agent skill (Claude Code, Cursor, and friends)
npx skills add shinyobjectz/montology
# npm (the launcher)
npm install -g montology
cd your-repo
monty init # .monty/, agent wiring, the pre-write guard hook
monty explain # the X-ray: what this repo is, in one pass
monty scan --candidates # the words your code is already asking for
monty lint # the gate — every finding carries its repair
monty config # what the gate enforces, and how to change it
monty intake ask … # no words yet? the agent's `intake` skill asks the team
# in a form, round by round, and ends in a glossaryFAIL collision: struct 'Harness' at Sources/Runner.swift:14 is the word
'harness' — "the thing that runs a scenario end to end". Rename it,
or record the exception: monty onto except harness --where … --why …
FAIL divergence: type 'RowID' is declared as String (db/rows.ts:8) and as
Int (api/rows.ts:12) — one noun, two things
warn retired: 'pointer' was RENAMED to 'cursor' (the word moved when the
UI stopped owning it). Name it 'cursor' — the old name stays retired.
note design: rogue color #121212 ×2 (first at css/app.scss:37)
— nearest token: ink #1b1b1f (Δ31)Every finding names the file, the line and the repair. The first three are about the CODE — a struct wearing a word that means something else, a type declared as two different things, a name a ruling retired — and the last is the same contract applied to a hex code, which is a word that means one thing. If your repo has no UI you will never see that line.
Where there IS a UI, the same machinery goes further: monty design recipes mines the class strings your markup repeats (flex flex-wrap gap-2 items-center ×102 — on shadcn/ui's own repo) so they can become
named things.
Related MCP server: engineering-standards
Everything above is post-hoc. The guard runs before the write:
monty init installs a pre-write hook in every harness it wires
(merge-safe — .claude/settings.json and .cursor/hooks.json), and the
plugin ships its own, so a plugin install is guarded without an init. It
lints every proposed Write/Edit/NotebookEdit against the ontology in
milliseconds — a declaration named after a retired word
(renames are rulings; always blocks), a collision with an enforced word,
a rogue hex when tokens exist. Deny is exit 2 with the repair on stderr:
the harness feeds it straight back to the model, which corrects and
retries. The agent physically cannot introduce a second gray or resurrect
a renamed concept — it gets the token or the current word handed to it
mid-edit. The guard fails open (malformed payload, no workspace, any
internal error → allow silently) so it can never break an editor; humans
in vim never meet it. monty doctor says, per harness, whether it is
actually wired; monty config guard.names block|warn|off tunes it.
monty explain — the one-shot conceptual X-ray
Point montology at any repo cold: one command composes the declared surface, the vocabulary it has, the vocabulary it is asking for (with definitions drafted on the atomic tier when one serves — law-checked, refused over wrong), where meanings actually gather (semantic clusters vs the directory tree's claimed architecture: cross-cutting concepts, grab-bag directories), the design system as measured, and every place the repo contradicts itself — straight to the terminal, because an instrument prints findings, it does not decorate them.
A repo's concepts drift exactly like its colors. montology's vocabulary is a database, not a doc — one word, one meaning, a one-line test, an optional dotted code — rendered into a generated agent skill and enforced against every declaration tree-sitter can parse (python, ts/tsx, js, go, rust, swift, elixir, ruby, java, c, c++):
monty onto check thread # FREE / TAKEN / RULED — before naming ANYTHING
monty scan --candidates # the words your codebase is asking for
monty onto add thread "a stateful user↔agent session" --code atl.thread --pos noun
monty onto amend thread --definition "…" --why "a later ruling narrowed it"
monty lint # collisions (advisory by default), code-tree
# integrity, stale prose — each with its repairNot every symbol sharing a word's name is drift, and treating them alike
produces a list nobody reads. A word carries what it names — verb,
noun, or value type — and the judgment follows from it: Store.open is
English doing ordinary work below the surface, while a noun answering for
a second thing is the failure a vocabulary exists to prevent. A collision
you keep is a recorded decision, in the database with the rest of the
vocabulary:
monty onto except open --where "lib/**" --why "ordinary work below the surface"
monty onto except --drafts # what an old [scan] allow list would becomeWhat an exception can never do is silence a divergence — one
value-typed word declared as two different values (@type name :: term()
in one module, @type name :: %{…} in another). That is a separate law
with a separate line: an exception says a symbol may share the name, not
that the name may mean two things.
Rulings end arguments permanently: overloads ("say cell, not
sandbox"), collisions with frameworks (whose word it is, who moved),
and renames — the old name retires, old material stays readable, and
monty migrate old new --apply propagates the rename through the code
by token (tree-sitter positions, strings and comments untouched,
losslessly round-trippable — proven on eight real repos).
When a ruling narrows a word you already authored, monty onto amend
corrects the record in place: the name and its history stay, every field
that changes is ledgered with the text it replaced, and an unknown name or
a no-op is refused. Editing the database around the authoring path is the
same drift the gate exists to catch.
Three instruments make a repo's meaning a tracked quantity:
monty vitals — the pulse: gate state, vocabulary state, design
state, guard compliance → one verdict (TENDED / DRIFTING /
UNTENDED) with every reason carrying its repair — plus whether the
firewall is wired and the org upstream it inherits. --json is the
dashboard shape; --strict exits 1 unless TENDED, so a repo can gate
on its own tending. Track it per repo the way you track CI.
monty drift — the telescope: the git history sampled into
lexicon, palette and convergence curves (--csv for the research
lane). On excalidraw's full history the palette fragmented ~10× in two
years (4→11→27→42 distinct colors) while declarations merely doubled.
Flask's concept lexicon: 49 concepts in 15 years, flat since 2019.
monty guard --stats — repair-following, measured: every hook
denial followed by a clean edit within 30 minutes is a complied
denial.
The string laws enforce one word, one meaning. The [semantics] extra
hears the dual — one meaning, one word — with POTION static embeddings
(~30 MB, numpy-only; no torch, no runtime): monty onto audit flags two
words defined into the same idea, local words that duplicate inherited
org words under different names, candidates that are secretly existing
words, and owner groupings that don't match where meanings cluster.
Advisory permanently — a cosine score proposes, only a ruling decides.
The org's vocabulary is authored once — any montology workspace's
.monty/ontology.db is the artifact — and inherited everywhere:
monty init --from git@github.com:acme/ontology.git # or a path, or a .db URL
monty onto pull # refresh from the pinUpstream rows refresh on every pull; local words always survive; a name
defined in both places is a loud conflict (local wins — reconcile
deliberately). When the org renames a word, every repo's next pull
prints the exact monty migrate command: that is how a rename crosses
the fleet.
montology is deliberately near-modelless — the deterministic laws do the enforcing — but it carries exactly two, each chosen for a measured floor:
model | size | lane | what it does | what it refuses |
POTION ( | ~30 MB, numpy-only |
| static embeddings over definitions: | deciding anything. A cosine score proposes; only a ruling makes vocabulary. |
gemma3:270m (via Ollama, optional) | 292 MB, user-installed |
| drafts ONE-LINE definitions under the word laws (refused over written wrong) when no host agent is present — the autonomous lane. | bodies and prose. The 270M capability floor is atomic one-liners; everything longer is the host agent's work or a served endpoint ( |
Nothing heavier ships, ever: no torch, no onnxruntime, no bundled weights. The host agent (Claude, Cursor, Codex) is always the best drafter available, and the gate never needs a model at all.
monty init wires the repo for Claude Code, Cursor, and Codex
(merge-safe: sections are appended, JSON keys merged, global config never
touched) — MCP server, the instructions section, and the pre-write guard
hook in each harness's own dialect. monty doctor reports which of those
actually landed.
Two skills ship: montology routes the work (new repo → set up,
empty vocabulary → build one, working repo → the check-first contract),
and intake runs the guided walkthrough for a codebase whose words
were never written down. The generated words skill carries the whole
vocabulary — words, tokens, recipes, rulings, doctrine — tiering into
reference pages rather than truncating when it outgrows its budget.
The MCP server exposes ontology_check, ontology_add, ontology_amend,
ontology_rule, ontology_similar, ontology_words, ontology_lint,
scan_surface, scan_candidates, structural_search, repo_explain,
repo_vitals and workspace_config. Prose is rendered from the database,
never authored; a stale render fails the build.
tree-sitter (via tree-sitter-language-pack) measures declarations and
CSS structurally; ast-grep (invoked, one static binary) powers
structural pattern search; SQLite holds the vocabulary. The stress
battery (stress/run.py, weekly in CI) proves four properties on eight
real repos — flask, excalidraw, gin, ripgrep, phoenix, sinatra,
spring-petclinic, redis: merge-safe idempotent init, zero-error parsing,
truthful collision reporting, and lossless migrate round-trips.
62 public ontologies and taxonomies, licence-verified, grouped by domain.
Browse with monty onto sources [group].
ontology | licence | commercial | source |
BFO — Basic Formal Ontology | CC BY 4.0 | yes — attribution | |
DCMI Metadata Terms (Dublin Core) | CC BY 4.0 | yes — attribution | |
NAICS (North American Industry Classification System) | US federal work — public domain (17 U.S.C. §105) | public domain | |
PROV-O — the Provenance Ontology (W3C) | W3C Software and Document Licence | yes | |
QUDT — Quantities, Units, Dimensions and Types | CC BY 4.0 | yes — attribution | |
RO — the Relation Ontology | CC0 1.0 | public domain | |
Schema.org vocabulary (types + properties) | CC BY-SA 3.0 | yes — share-alike | |
SIC codes | US federal work — public domain (17 U.S.C. §105) | public domain | |
SKOS — Simple Knowledge Organization System (W3C) | W3C Software and Document Licence | yes |
ontology | licence | commercial | source |
ChEBI — Chemical Entities of Biological Interest | CC BY 4.0 | yes — attribution | |
Human Disease Ontology | CC0 1.0 | public domain | |
Gene Ontology | CC BY 4.0 | yes — attribution | |
Mondo Disease Ontology | CC BY 4.0 | yes — attribution | |
NCI Thesaurus (OBO edition) | CC BY 4.0 | yes — attribution | |
Uberon multi-species anatomy ontology | CC BY 3.0 | yes — attribution |
ontology | licence | commercial | source |
FIBO — Financial Industry Business Ontology | MIT | yes |
ontology | licence | commercial | source |
Google Product Taxonomy | none — a bare .txt on www.google.com, no licence, no terms page, and developers.google.com's CC BY 4.0 site policy does not reach it | no — unlicensed | |
Shopify Product Taxonomy | MIT | yes |
ontology | licence | commercial | source |
AdCOM — Advertising Common Object Model (IAB Tech Lab) | CC BY 3.0 (stated in the repo README, no LICENSE file) | yes — attribution | |
Google NLP Content Categories | CC BY 4.0 (Google Cloud docs) | yes — attribution | |
Google Topics API Taxonomy | W3C Software and Document Licence | yes | |
IAB Ad Product Taxonomy 2.0 | CC BY 3.0 (as above) | yes — attribution | |
IAB Audience Taxonomy 1.1 | CC BY 3.0 (as above) | yes — attribution | |
IAB Content Taxonomy 3.1 | CC BY 3.0 (stated in the repo README, no LICENSE file — so every automated scan calls it unlicensed) | yes — attribution | |
The Open Graph protocol | Open Web Foundation Agreement 0.9 | yes | |
OpenOOH Venue Taxonomy | Apache-2.0 | yes | |
OpenRTB (IAB Tech Lab) | CC BY 3.0 (stated in the repo README, no LICENSE file) | yes — attribution | |
Curlie (the DMOZ successor) web directory | CC BY 3.0 Unported | yes — attribution | |
IABTechLab/iab-mapper (2.x → 3.0 mappings) | BSD-2-Clause | yes | |
IPTC Media Topics | CC BY 4.0 — IPTC states it for all NewsCodes | yes — attribution | |
IAB taxonomies as JSON (iPullRank) | MIT | yes |
ontology | licence | commercial | source |
AGRO — the Agronomy Ontology | CC BY 4.0 | yes — attribution | |
FoodOn — the Food Ontology | CC BY 4.0 | yes — attribution |
ontology | licence | commercial | source |
ENVO — the Environment Ontology | CC0 1.0 | public domain |
ontology | licence | commercial | source |
AsyncAPI Specification | Apache-2.0 | yes | |
CDEvents (Continuous Delivery Foundation) | Apache-2.0 | yes | |
Conventional Commits | MIT | yes | |
OWASP CycloneDX | Apache-2.0 | yes | |
JSON Schema | BSD-style (JSON Schema Specification Authors) | yes | |
OpenAPI Specification | Apache-2.0 | yes | |
OpenTelemetry Semantic Conventions | Apache-2.0 | yes | |
purl — Package URL specification | MIT | yes | |
Semantic Versioning | CC BY 3.0 | yes — attribution | |
SPDX — specification and licence list | Community Specification Licence 1.0; pre-existing portions CC BY 3.0 | yes — attribution | |
SWO — the Software Ontology | CC BY 4.0 | yes — attribution | |
DOAP — Description of a Project | Apache-2.0 | yes | |
OASIS TOSCA (Topology and Orchestration Specification) | Apache-2.0 | yes |
ontology | licence | commercial | source |
CVE — Common Vulnerabilities and Exposures | CC0 1.0 | public domain | |
CWE — Common Weakness Enumeration | MITRE royalty-free licence (research, development AND commercial; reproduce the copyright designation) | yes — attribution | |
MITRE D3FEND — defensive countermeasures | MIT | yes | |
MITRE ATT&CK | MITRE royalty-free licence (research, development AND commercial; reproduce the copyright designation) | yes — attribution |
ontology | licence | commercial | source |
Croissant — ML dataset metadata (MLCommons) | Apache-2.0 | yes | |
EDAM — data, operations, formats and identifiers | CC BY-SA 4.0 | yes — share-alike | |
MITRE ATLAS — adversarial threats to AI systems | Apache-2.0 | yes | |
OpenTelemetry GenAI Semantic Conventions | Apache-2.0 | yes | |
OWASP Top 10 for LLM Applications | CC BY-SA 4.0 | yes — share-alike | |
STATO — the Statistical Methods Ontology | CC BY 3.0 | yes — attribution |
ontology | licence | commercial | source |
GeoNames ontology + gazetteer | CC BY 4.0 | yes — attribution |
ontology | licence | commercial | source |
Harvard Growth Lab classifications (ISIC/HS/SITC/O*NET) | BSD-3-Clause | yes |
ontology | licence | commercial | source |
DCAT — Data Catalog Vocabulary (W3C) | W3C Software and Document Licence | yes | |
IAO — Information Artifact Ontology | CC BY 4.0 | yes — attribution |
ontology | licence | commercial | source |
wikidata-taxonomy (extraction CLI) | MIT (the tool; Wikidata's own data is CC0) | yes |
git clone https://github.com/shinyobjectz/montology && cd montology
uv sync && just # the action surface
just check # the gate (montology lints itself, strictly:
# its own toml sets collisions = "enforce")Author a word — check-first: a taken name is refused with findings. Re-renders the words skill on success.
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | ||
| kind | No | custom | |
| name | Yes | ||
| test | No | ||
| owner | No | ||
| definition | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description carries the full burden. It discloses key side effects—check-first refusal and re-rendering the words skill on success—which is good. Yet it stops short of explaining what 'findings' contain, how failures are returned, or any permission or idempotency details, leaving gaps.
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?
The description is a single sentence broken by a dash, with a second short sentence. It is front-loaded with the main action and includes only high-signal details, with no wasted words.
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?
For a tool with 6 parameters and no annotations, the description is too brief to be fully actionable. It covers the primary behavior and side effect but does not explain required inputs, optional parameters, or the structure of 'findings,' despite an output schema existing. The low schema coverage makes this a significant shortfall.
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?
With 0% schema description coverage, the description was expected to compensate by explaining parameters. It only mentions 'word' and 'taken name,' which vaguely maps to 'name' and 'definition' but leaves 'code', 'kind', 'test', and 'owner' entirely undocumented. This adds no meaningful parameter semantics beyond the property names themselves.
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?
The description uses the verb 'author' with the resource 'word' and explicitly states the check-first behavior ('a taken name is refused with findings'), making its primary action clear. It distinguishes itself from siblings like ontology_check and ontology_words by focusing on creation with a built-in existence check.
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 description implies the tool is for adding new words ('Author a word') and that it performs a check first, which suggests it should be used instead of calling ontology_check separately. However, it does not explicitly contrast with alternatives or state when not to use it, leaving the guidance at the implied level.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Is this name free, defined, or ruled on? Run BEFORE naming anything.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the transparency burden. It implies a read-only status check without side effects, but does not explicitly state safety, define the outcomes (free/defined/ruled on), or mention error conditions. It provides basic behavioral context but not rich detail.
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?
The description is a single, front-loaded sentence that delivers the core purpose and usage directive without wasted words. It is highly concise and well-structured.
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?
For a simple one-parameter check tool with an output schema, the description provides adequate context: what it checks, when to run it, and the possible outcomes. It lacks definitions of 'ruled on' and explicit read-only assurance, but given the tool's simplicity and existing output schema, it is nearly complete.
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?
Schema coverage is 0% and the description only indirectly references the parameter via 'this name'. It does not explicitly explain the parameter format, constraints, or semantics beyond implying it is the name to check. The possible statuses add minimal context, but the description fails to fully compensate for the lack of schema documentation.
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?
The description uses a clear question form to indicate the tool checks whether a name is free, defined, or ruled on. It implies a check action and the resource (name in ontology), distinguishing it from siblings like ontology_add (adding) and ontology_lint (linting). Missing an explicit verb like 'checks' but still understandable.
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?
'Run BEFORE naming anything' explicitly tells when to use the tool, establishing it as a prerequisite check. It does not mention alternatives or exclusions, but the timing guidance is clear and context-rich.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The gate: collisions, code resolution, drift — each FAIL carries its repair.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only cryptically states that 'each FAIL carries its repair,' suggesting the tool outputs failures with repair instructions, but it does not explain side effects, permissions, or what 'collisions,' 'code resolution,' and 'drift' concretely mean. This is insufficient for a tool with zero annotation support.
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?
The description is a single sentence, making it very concise with no unnecessary words. However, its cryptic and metaphorical phrasing means it is not well-structured for immediate comprehension; it is under-specified rather than efficiently clear.
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?
Despite having an output schema, the description is too vague to understand what the tool actually does or how it fits into a workflow. It does not explain what inputs it operates on, what 'gate' implies, or how the listed concepts (collisions, resolution, drift) are detected or repaired. The description is incomplete for a tool with this level of complexity.
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 input schema has zero parameters, so the baseline score is 4. The description does not need to explain parameters, and it adds no param-related information, which is acceptable given there are none.
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?
The description calls the tool 'The gate' and references collisions, code resolution, and drift, which hints at a validation or linting role. However, it lacks a specific verb like 'checks' or 'validates', and the metaphor makes the exact operation ambiguous. It gives some sense of purpose but remains vague.
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 description offers no guidance on when to use this tool versus the sibling tools such as ontology_check, ontology_words, or ontology_add. There is no mention of prerequisites, context, or scenarios where this tool is preferred, leaving the agent without direction on selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The vocabulary as rows (kind: core | inner | adopted | custom | empty for all).
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must carry behavioral disclosure. It does not state whether the operation is read-only, how results are ordered, whether pagination applies, or any side effects. The safety profile is entirely unspecified.
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?
The description is extremely short and front-loaded, but it is not a complete sentence and omits an explicit action. The phrase 'empty for all' is terse but ambiguous.
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?
For a simple one-parameter list tool with an output schema, the description is minimally adequate, but it does not clarify what 'vocabulary' refers to or how this tool fits into a workflow. It could be more helpful with an explicit verb and usage hint.
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 description adds meaning to the 'kind' parameter by enumerating possible values (core, inner, adopted, custom) and explaining that empty string returns all. This goes beyond the schema, which only declares a string with a default.
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?
The description identifies the resource (vocabulary) and output shape (rows) with a filter dimension (kind), making its purpose reasonably clear despite lacking an explicit verb. It does not explicitly distinguish itself from sibling tools like ontology_check or ontology_add, but the semantics are distinct enough.
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?
No guidance is provided on when to use this tool versus alternatives. The mention of 'empty for all' implies an optional filter, but there is no context about use cases, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Vocabulary the codebase is asking for: recurring declared names with no word.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden for behavioral disclosure. It does not mention side effects, permissions, read-only status, or output format. The phrase 'recurring declared names with no word' hints at the search criterion but not at the behavior of the tool.
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?
The description is a single short sentence, so it is concise. However, it is under-specified; the brevity comes at the cost of clarity. It does not waste words, but it also does not provide enough information to be considered well-structured.
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?
The tool has a simple schema and an output schema, so return values are not necessarily needed in the description. However, the core function and purpose are not clearly explained, and the description leaves significant ambiguity. The context provided by siblings like 'scan_surface' and 'ontology_check' does not compensate for the lack of descriptive detail.
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 input schema has a single parameter 'top' with 0% description coverage. The description does not mention 'top' at all, failing to explain that it likely controls the number of results. The description adds no semantic value beyond the schema's default value.
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?
The description 'Vocabulary the codebase is asking for: recurring declared names with no word' provides a specific focus but lacks an explicit verb or clear action statement. It implies the tool identifies candidates for vocabulary additions, but does not state that it scans or returns them. This makes the purpose clear in a vague sense, but it does not explicitly distinguish it from sibling tools.
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 description gives no guidance on when to use this tool versus alternatives. There is no mention of context, prerequisites, or exclusions. It only defines the topic of the scan, leaving the user to infer usage from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What the code declares: counts by language, skips said out loud.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior, but it only offers an unclear phrase 'skips said out loud' and no details about side effects, scope, or limitations. The description is far too vague to understand the tool's actual behavior.
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?
The description is very short but lacks clarity and structure. It reads as cryptic and under-specified, not concise in an effective way. The phrase 'skips said out loud' adds confusion rather than value.
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?
Despite having an output schema, the description does not explain what the output represents. The context from sibling tools does not clarify the tool's role, and the description is too incomplete to understand the tool's purpose in the broader ecosystem.
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 input schema has zero parameters, so the baseline is 4. The description does not need to explain parameters, and the high schema coverage (implicitly 100%) means there is nothing to compensate for.
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?
The description vaguely mentions counting by language but does not specify what is being counted or what 'skips said out loud' means. It fails to clearly state the tool's function, making it indistinguishable from siblings like scan_candidates.
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?
No guidance is provided on when to use this tool instead of alternatives. There is no mention of context, prerequisites, or exclusions, leaving the agent without direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
ast-grep over the repo: a pattern that PARSES, e.g. 'def $F($$$)' with lang=python.
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | ||
| pattern | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It usefully highlights that the tool PARSES (rather than text-matches) and operates repo-wide, but does not disclose read-only status, error behavior for invalid patterns, or performance implications.
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, well-structured sentence front-loads the core functionality and uses an example to clarify usage. No unnecessary words or repetition.
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?
Given the presence of an output schema, the description does not need to explain return values. It covers purpose, scope, and gives a practical example. Missing details about pattern syntax and lang defaults are parameter-level and do not severely undermine completeness.
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 schema has no parameter descriptions (0% coverage). The description adds meaning by mentioning 'pattern' and 'lang' via a concrete example, implicitly defining pattern as a structural code pattern and lang as a language selector, though it doesn't fully enumerate allowed values.
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?
The description clearly identifies the tool as ast-grep for structural search over the repo, with a concrete pattern example and language specification. This distinguishes it from the sibling ontology and surface-scanning tools.
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 description implies usage for syntactic/code-pattern search ('over the repo'), but it does not explicitly state when to use this tool over alternatives, nor provide any exclusions or comparison with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0ontology_addontology_checkontology_lintontology_wordsscan_candidatesscan_surfacestructural_searchTools are largely distinct: check/words/add target the ontology, scan_surface/scan_candidates focus on code analysis, lint is a holistic gate, and structural_search is clearly separate. Minor overlap exists between ontology_check (single name) and ontology_lint (overall issues), but contexts are clear.
Naming mixes prefixes: ontology_check, ontology_words, ontology_add, ontology_lint use 'ontology_' while scan_surface and scan_candidates use 'scan_', and structural_search is standalone. Patterns also vary between verb-based (check, add, lint) and noun-like (words) or adjective-noun (structural_search).
With 7 tools, the surface is well-scoped for managing a code ontology: basic CRUD (check, words, add), scanning (surface, candidates), validation (lint), and advanced search (structural_search). Not overly large or thin.
Core workflows (check, add, list, lint, scan) are covered, but the set lacks update/delete operations for words (only add exists) and no way to view details of a single word beyond listing. This leaves minor lifecycle gaps, though most typical use cases are supported.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Statically audits MCP tool surfaces for token cost, schema quality, and design issues.
Access and maintain design system docs, tokens, components, skills, and contexts across any project.
Serves your design system and coding standards to coding agents, so they stop guessing.
Screens public GitHub repos and PRs to generate risk maps, findings, and merge-readiness signals.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/shinyobjectz/montology'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
