Skip to main content
Glama
aliasunder

Vault Cortex Obsidian MCP Server

by aliasunder
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Search by Property

vault_search_by_property
Read-onlyIdempotent

Find notes by exact frontmatter property value without text queries. Supports scalar and array properties, optional folder filtering, returns matching note metadata.

Instructions

Find notes where a frontmatter property matches a value — metadata-only search, no text query needed. Handles both scalar properties (status: "active") and array properties (tags, related): for arrays, matches if any element equals the value (contains check, not exact array match). Matching is exact and case-sensitive; an unknown key or unmatched value returns an empty array, not an error.

Example: vault_search_by_property({ key: "status", value: "in-progress" }) Example: vault_search_by_property({ key: "type", value: "session-log", folder: "Code Projects" })

When to use: Finding notes by metadata when you don't have a text query. Prefer vault_search when you also have a text query (it supports property filters too). Prefer vault_search_by_tag for tag-specific queries (supports hierarchical prefix matching). Use vault_list_property_keys to discover valid keys and vault_list_property_values to see what values a key takes.

Parameters:

  • key + value are both exact and case-sensitive — no partial matching or globbing. All property values are compared as strings, so numeric or boolean properties must be passed as their string representation.

  • For array properties (tags, related), value is tested against each element individually (contains check) — "blog" matches a note with tags: ["blog", "draft"] but not tags: ["my-blog"].

  • folder narrows results to a subtree; omit for vault-wide search. Combined with key+value, this lets you check how a property is used within a specific area.

Returns: JSON array of note metadata (path, title, tags, related, folder, type, created, modified, bytes, leading_callout?, additional_properties), sorted by filesystem mtime descending — recently-synced notes may sort ahead of older content edits.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
keyYesProperty key name (e.g. "status", "type", "tags"). Use vault_list_property_keys to discover valid keys.
limitNoMax results (default 20). Increase for broad metadata queries.
valueYesValue to match (exact, case-sensitive, e.g. "active", "session-log"). Use vault_list_property_values to discover valid values for a key.
folderNoRestrict to a folder prefix (e.g. "Projects")

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.50.0
    • addedInput schema / properties / limit / default
      Added value: +20
    • addedInput schema / properties / limit / maximum
      Added value: +9007199254740991
    • addedInput schema / properties / limit / minimum
      Added value: +1
    • changedInput schema / properties / limit / type
      Previous value: -"number"New value: +"integer"
  2. Addedv0.32.1
  3. Removedv0.32.0
  4. Changed4 schema fields changedv0.23.5
    • changedInput schema / properties / folder / description
      Previous value: -"Restrict to a folder"New value: +"Restrict to a folder prefix (e.g. \"Projects\")"
    • changedInput schema / properties / key / description
      Previous value: -"Property key name (e.g. \"status\", \"type\"). Use vault_list_property_keys to discover valid keys."New value: +"Property key name (e.g. \"status\", \"type\", \"tags\"). Use vault_list_property_keys to discover valid keys."
    • changedInput schema / properties / limit / description
      Previous value: -"Max results (default 20)"New value: +"Max results (default 20). Increase for broad metadata queries."
    • changedInput schema / properties / value / description
      Previous value: -"Value to match (exact, case-sensitive). Use vault_list_property_values to discover valid values for a key."New value: +"Value to match (exact, case-sensitive, e.g. \"active\", \"session-log\"). Use vault_list_property_values to discover valid values for a key."
  5. Changed2 schema fields changedv0.23.3
    • changedInput schema / properties / key / description
      Previous value: -"Property key name"New value: +"Property key name (e.g. \"status\", \"type\"). Use vault_list_property_keys to discover valid keys."
    • changedInput schema / properties / value / description
      Previous value: -"Value to match (exact, case-sensitive)"New value: +"Value to match (exact, case-sensitive). Use vault_list_property_values to discover valid values for a key."
  6. Changed3 schema fields changedv0.22.1
    • addedInput schema / properties / folder / minLength
      Added value: +1
    • addedInput schema / properties / key / minLength
      Added value: +1
    • addedInput schema / properties / value / minLength
      Added value: +1
  7. Added

TDQS

A4.9/5.0
Behavior5/5

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

Discloses important behavior beyond annotations: exact and case-sensitive matching, contains semantics for arrays, string coercion for numeric/boolean values, empty-array return instead of error, and mtime-descending sort order. With no behavioral annotations provided, this fully compensates.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but almost every sentence adds value. The array-contains behavior is explained twice (once up front and once under parameters), which is a minor redundancy, and the structure could be tightened slightly. Overall it is dense and well-organized.

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?

Covers purpose, exact matching semantics, array behavior, error behavior, sorting, parameter guidance, and sibling-tool routing. Combined with the schema, an agent has everything needed to call this correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema only defines types and required/optional; the description adds critical semantics: key/value are exact and case-sensitive, array values are matched per element, folder narrows to a subtree, and numeric/boolean values must be passed as strings. This is far beyond the schema.

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 first sentence states exactly what the tool does: find notes by frontmatter property value, with no text query needed. It distinguishes this from vault_search and vault_search_by_tag, and the examples make the purpose concrete.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use it (metadata-only search without a text query) and when not to: prefer vault_search when a text query exists, prefer vault_search_by_tag for tag-specific searching, and use vault_list_property_keys/values for discovery. This is model-level guidance an agent can act on directly.

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

Deploy Server

Other Tools