Metadata Snapshot

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

Annotations say readOnlyHint=false, idempotentHint=false, openWorldHint=true, yet the description reads like a pure projection read ("serve", "returns...") and explicitly disclaims the commit/reconcile role — so the agent gets no explanation of what the non-read-only side effect actually is, whether repeat calls differ, or what external source is contacted. The conflict with the annotations is not resolved, only muddied; with annotations present, this should have clarified the write/caching behavior rather than omit it.

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?

It is short and the return-contents sentence is front-loaded and useful. But the opening "Metadata snapshot (vaultwarden_metadata)" restates the name and title, and the trailing "CONCEPT:VW-KG.ingest.metadata-only" is an internal taxonomy tag with no decision value for an agent.

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 values needn't be spelled out, and the description partly does so anyway. What is missing is the operationally important context: what the tool actually does to the environment (given readOnlyHint=false), whether authentication or a configured source is required, and what the opaque params_json must contain — none of which the schema or annotations cover.

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 100%, so the single params_json field is nominally documented, giving the baseline of 3. But the schema text ("JSON object of metadata-source parameters") is a near-empty container, and the description adds no hint about which keys that blob accepts or how filtering/scope is expressed, leaving an opaque free-form parameter unexplained.

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 says it "serves the certified metadata-only source projection" and enumerates what is returned (identifiers, type codes, timestamps, counts, typed relationships), which implies a metadata read/snapshot. However, the phrasing is heavy domain jargon ("certified projection", "CONCEPT:VW-KG.ingest.metadata-only") and never states plainly what the tool operates on or where the snapshot comes from. Compared to the sibling vaultwarden_metadata_backfeed_metadata, the distinction is only implicit (backfeed unsupported).

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?

"Scion SDK source_sync is the only graph commit/checkpoint/reconcile authority" and "Backfeed is explicitly unsupported" give useful negative guidance by naming what this tool must NOT be used for. But there is no positive statement of when to call it, what triggers it, or which sibling to pick instead for mutation/graph work.

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