Skip to main content
Glama

resolve_mentions

Match names mentioned in content against existing vault nodes before saving, so new notes link to existing people, organisations, projects, or topics instead of creating duplicates.

Instructions

Match names mentioned in content — people, organisations, projects, topics — against existing vault nodes, so a save links to what is already there instead of creating a second "John Smith".

Pull every proper name out of the content first, then pass them all in one call. Each name is compared against node titles and aliases, case- and whitespace-insensitive. Returns: { found: [{name, uid, title, type, path, summary, via}, ...], missing: [name, ...], } via is "title" or "alias" for an exact match, or "partial" when the name only appears as a whole word inside a title or alias (e.g. "Loci" against "Loci — knowledge vault") — treat partial hits as candidates to confirm, not as matches. A name listed more than once in found matched several nodes; ask the user which one they meant.

Args: names: Names to resolve, as they appear in the content. types: Optional list of node types to search (e.g. ["entity", "project"]). Omit to search every active node.

Input Schema

NameRequiredDescriptionDefault
namesYes
typesNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.7.0

TDQS

A4.1/5.0
Behavior3/5

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

With no annotations supplied, the description carries the full disclosure burden, and it does real work: matching is case- and whitespace-insensitive against titles and aliases, the default scope is every active node, and `via` distinguishes title/alias/partial matches with guidance on interpreting each. It never states that the operation is read-only or non-mutating, though the surrounding 'returns found/missing' framing strongly implies it.

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?

Front-loaded with purpose, then usage, then a structured Returns block and Args block — the organization is easy to scan. There is mild redundancy, since the `via` and duplicate-name semantics are explained in prose right after being shown in the return shape, but no sentence is wasted.

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?

For a two-parameter tool with no output schema and 0% schema coverage, the description covers purpose, call pattern, default scope, matching rules, return shape, and result-interpretation edge cases. Nothing an agent needs to call or interpret it correctly appears to be missing.

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?

Schema coverage is 0%, so the description must supply all parameter meaning and does: `names` is defined as names as they appear in the content (and the batching expectation), while `types` is optional, takes node-type strings with examples, and omitting it searches every active node. That is meaning well beyond the bare array schemas.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: matching names mentioned in content against existing vault nodes' titles and aliases, with the concrete motivation (avoiding a duplicate "John Smith"). What's missing is explicit differentiation from overlapping siblings such as check_duplicate, find_nodes and search_vault, which an agent could reasonably confuse with this tool.

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?

Gives an explicit operational rule — extract every proper name from the content first, then pass them all in a single call — which is actionable usage guidance rather than vague implication. It also tells the agent how to act on results (confirm partial hits, ask the user when a name matched several nodes), but never names an alternative tool or a when-not condition.

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