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

Annotations already declare this a read-only, idempotent, non-destructive, closed-world operation, so the safety burden is carried structurally; the description adds useful behavioral context about what a scan yields (kinds, counts, ranges). It stops short of disclosing enumeration limits — e.g. whether the "most used values" list is capped or truncated for high-cardinality fields.

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?

Two sentences, front-loaded with the purpose before the workflow guidance, with no filler. The first sentence is a long comma-delimited enumeration, which is dense but each clause maps to a distinct returned attribute, so little could be cut without losing information.

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?

An output schema exists, so return-shape explanation is not strictly required, yet the description still frames the result semantically and ties it to the downstream search_notes call. Missing only edge-case behavior such as truncation of value lists or empty-vault results for a tool whose complexity is low.

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?

Only one parameter, vault_id, and it is fully documented in the schema (100% coverage), including the multi-vault requirement and the list_vaults fallback. The description adds nothing about the parameter, so the baseline 3 applies.

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 opens with a specific verb and resource ("List every frontmatter field used in the vault") and then enumerates the returned attributes — value kinds, note counts, list-ness, ranges, top values — which makes it unmistakable versus siblings like list_tags or get_notes.

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?

It explicitly prescribes when to call it ("Call this before filtering search_notes by frontmatter") and how to feed the result into that sibling's `fields` filter, including both exact-value and range-bound usage. No inference about the alternative workflow is left to the agent.

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