margins-mcp

Overview Schema Source Related Servers Discussions Admin

scan_entity_candidates

Read-only

Find capitalized phrases that recur across vault pages but lack a matching page. Returns candidates ranked by file-spread and mention-count to identify missing entity pages.

Instructions

Find capitalized phrases that recur across vault pages but have no matching slug — i.e. entities the user keeps mentioning without having a page for them. This is the inverse query of propose_wikilinks: instead of 'where should I add a wikilink to an existing page?', it answers 'what page should exist that doesn't yet?'. Returns candidates ranked by file-spread × mention-count, with snippets and the list of files where each appears. Read-only — never stages. The companion tool propose_entity_stubs takes the slugs you choose from this list and stages stub entity pages. Layered filtering: a global English/structural stoplist, an optional domain pack ('med', 'realestate', 'law', 'generic'), and an optional excludeUserRejections list (slugs the user already rejected). Existing slugs are excluded automatically — the shared vault-slug index is the same one propose_wikilinks uses. Best used right after a fresh import or split-mode compile, when the corpus has many entity references but few entity pages.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "scan_entity_candidates"
  }
}

Input Schema

Name	Required	Description
`limit`	No	Cap on candidates returned. Default 50. Total candidate count is in candidatesFound so callers can tell if there are more behind the cap.
`scope`	No	Glob to limit the walk. Default 'wiki/'. Pass a folder glob like 'Path/' to scope to one subject. Supports , *, ?.
`domain`	No	Domain pack to apply on top of the global stoplist. 'med' drops Step One / Gram Positive / Stage III etc; 'realestate' drops Class A / Phase II / Due Diligence; 'law' drops Section / Article / Chapter; 'generic' (default) applies only the global list.
`minMentions`	No	Minimum total mentions across the scope before a candidate qualifies. Default 5. Lower to surface more (noisier); raise for high-confidence only.
`minFileSpread`	No	Minimum number of distinct files a candidate must appear in. Default 3. Catches phrases that recur many times in one file (often boilerplate) and treats them as low-signal.
`minPhraseWords`	No	Minimum word count for a candidate to qualify. Default 2 — single-word sentence-start capitals are the dominant noise source on real vaults. Acronyms (AI / MBA / MCP, all-caps 2-6 letters) bypass this filter and surface regardless. Drop to 1 to also see single-word surnames like 'Holmes' or 'Cardozo' (raises recall, raises noise).
`excludeUserRejections`	No	Slugs the user has previously declined. Wired by propose_entity_stubs in v0.16+ to read rejection memory from .margins/preferences.md; you can also pass it ad-hoc.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.15.3Jul 29, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Discloses read-only nature ('Read-only — never stages') beyond the annotation. Explains the ranking algorithm (file-spread × mention-count), layered filtering (global stoplist, domain pack, user rejections), and that existing slugs are excluded automatically. No contradiction with annotations.

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?

Well-structured with clear paragraphs. Front-loads the main purpose and draws contrast with sibling. A bit long with multiple paragraphs, but each sentence earns its place. Could be slightly shorter but still effective.

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?

Given 7 parameters (all documented in schema) and no output schema, the description covers return values (candidates ranked with snippets and file list), companion tool, filtering layers, and best-use timing. Provides enough context for a correct invocation.

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

Parameters4/5

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

Schema coverage is 100%, so baseline 3. The description adds value by explaining the interaction of parameters (e.g., 'layered filtering', trade-offs like 'Lower to surface more; raise for high-confidence'). Gives context for minPhraseWords (single-word noise, acronym bypass). This adds meaning 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 description clearly states the tool's purpose: finding capitalized phrases that recur without a matching slug. It distinguishes itself from the sibling propose_wikilinks by explaining the inverse query nature. The verb 'find' and resource 'entities' are specific.

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 states when to use: 'Best used right after a fresh import or split-mode compile.' Contrasts with propose_wikilinks, clarifying the decision boundary. Also mentions companion tool propose_entity_stubs for next steps.

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