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

With no annotations, the description carries the burden and does well: it explains the return values and the meaning of 'alive' (false means every empty result is untrustworthy). It also adds context about the tool's role as a proof-of-retrieval, but doesn't cover potential failure modes or edge cases.

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?

The description is front-loaded with the core purpose and each sentence adds value (what it does, when to use, what it returns, and a closing rationale). Slightly longer than necessary but efficient.

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?

Given the tool's simplicity (one optional param, no output schema), the description is complete: it explains the return structure, the meaning of key fields, and usage timing. It fully supports an agent in understanding when and why to invoke it.

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% for the single optional parameter, which already has a clear description. The tool description adds no extra parameter semantics, so the baseline of 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 clearly states the tool is a 'positive control for retrieval' and explains that it asks the index for known notes by title to verify they return. This uniquely distinguishes it from siblings like search_notes or check_vault_integrity.

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?

Explicit usage guidance is provided: 'Use this at session start, before trusting any empty search result, and any time a vault has been quiet or moved between machines.' However, it does not mention when not to use it or name alternative tools, so it falls short of a 5.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains that the tool returns missing targets ranked by 'how many DISTINCT notes reference each missing target,' which is a behavioral trait beyond what the parameter schema provides. It also gives interpretive guidance (e.g., 'one note pointing at an unwritten note is an ordinary forward reference'), which helps set expectations. However, it doesn't disclose the return format or pagination, so I deduct a point for missing that behavioral detail.

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?

The description is a single, dense paragraph but is packed with information: purpose, context, ranking logic, and usage timing. It's not overly verbose, but it could be broken into shorter sentences for readability. Still, every sentence earns its place; no fluff. Content-wise it's efficient, but structure could improve.

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?

Given the tool's complexity (a vault integrity check with ranking), the description is fairly complete. It explains the why (git's limitation), the how (ranking by references), and when (session start). With no output schema, it doesn't describe return structure, but the ranking logic is enough for an agent to understand the tool's purpose. A slightly missing piece is the exact output format, but the description provides adequate context for confident use.

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%, and the parameter min_references is described in the schema ('How many distinct referencing notes before a missing target counts as load-bearing. Default 3.'). The description adds context about the significance of the parameter by explaining the ranking concept, which goes beyond the schema. The baseline is 3, and the description's added context on the parameter's meaning justifies a 4.

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 clearly states the tool's purpose: 'Find wikilinks that point at notes which do not exist.' It specifies the resource (wikilinks) and the action (find broken links), and the verb 'Find' is specific. It distinguishes from siblings like resolve_link and get_backlinks by focusing on integration with the vault, not just structure.

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?

The description explicitly says when to use this tool: 'Run at session start alongside check_search_health.' It also provides context on why it matters (git's limitations) and what the ranking means, helping distinguish from other tools like search_notes. It clearly suggests a usage pattern, though it doesn't explicitly say when not to use it, but the session-start guidance is strong.

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

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

With no annotations provided, the description must carry the transparency burden. It does well by explaining that it returns explicit backlink edges (as opposed to semantic similarity), the scope ('vault has decided this note is load-bearing'), and the effect of include_outbound. It doesn't explicitly state it's read-only, but that's implied and not contradicted. Overall, it discloses the core behavior effectively.

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?

The description is a bit longer than strictly necessary but every sentence contributes: purpose, differentiation, use cases, and optional parameter. It is well-structured with the core question first, followed by context and usage guidance. No redundant or filler content, though it could be tightened slightly.

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?

Given the absence of an output schema, the description adequately explains what the tool returns (backlinks, with optional outbound links). It covers the key distinctions from siblings and includes essential usage context. However, it doesn't mention potential edge cases (e.g., behavior for nonexistent note paths) but this is minor for a read-only tool.

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?

The input schema already describes both parameters thoroughly (note_path with an example, include_outbound with default). The description adds marginal value by explaining the purpose of the result but doesn't add new parameter-level detail. Baseline of 3 is appropriate since schema coverage is 100%.

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 crystal-clear statement: 'Which notes explicitly link TO this one.' It names the specific resource (notes) and the action (listing backlinks), and explicitly contrasts with semantic search and sibling tools like get_similar_notes and get_connection_graph, making its unique purpose unambiguous.

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?

The description explains when to use the tool: 'Use it to judge how important a note is, to find every place a decision is cited before changing it, and to trace how a concept actually gets used.' It also distinguishes it from semantic search, providing clear exclusions. The optional include_outbound behavior is mentioned, which helps decide between this and related graph tools.

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

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

With no annotations, the description must disclose behavior. It mentions multi-level and semantic connections, but does not disclose potential performance implications for deep graphs, how thresholds affect results, or whether it triggers expensive embedding computations. It provides some behavioral context but leaves room for more detail.

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?

The description is a single, concise sentence that clearly states the tool's function without extraneous information. It front-loads the primary action (build a connection graph) and includes key qualifiers (multi-level, starting from a note, semantic connections). It is appropriately sized for the tool's complexity.

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?

The description, combined with a fully covered schema, provides enough information for an agent to understand and invoke the tool. It lacks details on the output format (no output schema), but for a graph-building tool, the purpose and parameters are clear. It could mention how the graph is returned (e.g., as nodes/edges) but the absence is not critical.

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?

The schema covers all parameters with clear descriptions. The description adds context by explaining the purpose (multi-level, semantic connections), which complements the schema. For example, 'threshold' and 'max_per_level' are self-explanatory, but the description reinforces their role in building the graph. It does not add new parameter details but integrates them into the tool's purpose.

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 clearly states the tool builds a multi-level connection graph starting from a note, showing semantic connections. It is distinct from sibling tools like get_similar_notes (which likely returns a flat list) and search_notes (text-based search). However, it could be more explicit about the visual/graph output nature.

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?

The description implies usage for exploring semantic connections, but provides no explicit guidance on when to use this tool vs. alternatives like get_similar_notes or get_embedding_neighbors. It does not mention any prerequisites or exclusions.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, but it only restates the core operation. It does not explain what the returned neighbors are, whether distances are included, how threshold interacts with k, or any assumptions about embedding normalization.

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?

The description is two short sentences with the core action front-loaded. It is appropriately sized for a simple tool and contains no filler or redundant restatement of the tool name.

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?

Given no output schema and no annotations, the description should explain what the tool returns and how the parameters affect results. It does not describe the output shape, whether neighbors are notes or raw vectors, or how k and threshold interact, leaving significant gaps for an agent.

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 description coverage is 100%, so the baseline is 3. The description adds no additional parameter semantics beyond what the schema already provides; 'embedding_vector' is already described as a 384-dimensional array, and k/threshold have defaults and bounds in the schema.

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 clearly states the tool's function: 'Find nearest neighbors for a given embedding vector.' This is a specific verb-resource pairing. It does not explicitly contrast with sibling tools like get_similar_notes, though 'custom similarity searches' hints at its distinct vector-based use case.

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?

The phrase 'Useful for custom similarity searches' provides implied usage context but no explicit when-to-use or when-not-to-use guidance. It does not mention alternatives such as get_similar_notes for note-level similarity or explain when this lower-level vector search would be preferred.

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

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

With no annotations provided, the description carries the full behavioral burden. It communicates a read-only retrieval operation and optional filtering, but does not disclose limitations, error behavior, or whether full content includes formatting or metadata.

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?

A single, well-structured sentence with no filler. The core action and optional capability are front-loaded, making it easy for an agent to parse quickly.

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?

For a low-complexity tool with two well-documented parameters, the description adequately conveys what it returns and the optional include_blocks behavior. It could mention return format or error cases, but the absence of an output schema is partially mitigated by the clear retrieval language.

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 description coverage is 100%, so the baseline applies without the description needing to explain parameter syntax. The description does add context around 'full content' vs 'specific blocks/sections,' but adds little beyond the schema.

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 uses a specific verb ('Retrieve') and resource ('full content of a note'), clearly distinguishing it from sibling tools like search_notes or get_backlinks. The optional block/section extraction adds precise scope.

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?

The description clearly implies this tool is for retrieving note content, but it does not explicitly state when to use it instead of siblings or mention exclusions. Usage context is implied rather than directed.

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

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

With no annotations, the description carries the transparency burden. It does disclose the retrieval method (embeddings) and the output categories, which implies a read-only operation. However, it does not mention behavior for missing notes, embedding availability, or the exact meaning of 'available blocks.'

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?

The description is one concise, front-loaded sentence that communicates purpose and return value without wasted words.

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?

The tool has no output schema or annotations, so the description must compensate. It lists return types but leaves 'available blocks' ambiguous and provides no failure semantics, output structure, or usage guidance relative to sibling tools. This is adequate but incomplete.

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 baseline is 3. The description adds no parameter-specific detail beyond the schema's existing documentation of note_path, limit, and threshold, and it does not clarify how limit and threshold interact.

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 clearly states the tool finds semantically similar notes using embeddings and names the returned data (paths, similarity scores, available blocks). It distinguishes from keyword-based search_notes, but does not differentiate from sibling get_embedding_neighbors, which may also use embeddings.

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?

No explicit when-to-use or when-not-to-use guidance is provided. The phrase 'using embeddings' implies semantic similarity use cases, but there is no comparison to alternative tools like search_notes or get_embedding_neighbors, leaving selection ambiguous.

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

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

With no annotations, the description must reveal behavioral traits. It clearly indicates a read-only operation ('Get statistics') and implies no side effects. The examples of returned data (notes, blocks, model) provide transparency about the output, though it does not explicitly state that it is non-destructive or safe, but the phrasing is sufficient for a simple stats tool.

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?

The description is a single, front-loaded sentence that directly states the purpose and provides concrete examples of what is included. There is no redundant or extraneous information; every word adds value.

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?

Given the tool has no parameters and no output schema, the description adequately explains what the tool returns (total notes, blocks, embedding model, etc.). It is complete enough for a basic stats tool, though the 'etc.' could be more explicit. No additional context about limitations or setup is required for such a straightforward operation.

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?

The tool has zero parameters, so no parameter explanations are needed. The schema coverage is 100% (empty properties). Per the baseline for 0 params, a score of 4 is appropriate; the description adds no parameter info because there are none to describe.

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 clearly states the verb 'Get' and the resource 'statistics about the Smart Connections knowledge base', providing specific examples (total notes, blocks, embedding model). It distinguishes itself from sibling tools like get_similar_notes and get_connection_graph, which focus on specific queries or graphs rather than general stats.

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?

There is no explicit guidance on when to use this tool versus alternatives. The context implies it is for retrieving overall knowledge base statistics, but no exclusions or alternative recommendations are given. It relies on the user inferring usage from the purpose.

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

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

No annotations are provided, so the description carries the full burden. It discloses key behavioral traits: it returns null when nothing resolves (indicating genuine non-existence), which is critical for error handling. It also reveals that it honors aliases frontmatter, adding meaningful context. However, it doesn't discuss whether the path is absolute or relative, or any potential side effects, but for a read-only lookup, this is acceptable.

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?

The description is a single, well-structured paragraph that packs in examples, behavior, and usage guidance without wasting words. It front-loads the core purpose and then provides necessary details, making it easy to scan. Every sentence adds value.

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?

For a simple tool with one parameter, no nested objects, and no output schema, the description is comprehensive. It covers input formats, alias handling, return behavior (null on failure), and how it differs from alternatives. The agent has everything needed to invoke it correctly without additional context.

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?

The schema has only one parameter with 100% coverage, providing a basic description. The tool description adds examples of accepted formats (bare text, full link syntax, or path) and explains the aliases behavior, which enriches understanding beyond the schema. However, since the schema already describes the parameter, the extra value is incremental, not dramatic.

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 clearly states the tool's purpose: turning a wikilink into a real file path, with a specific verb ('resolve') and resource ('wikilink'). It differentiates from siblings by explicitly noting that it resolves the actual referenced note rather than finding similar ones, as get_similar_notes or search_notes would.

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 provides strong guidance on when to use: whenever a [[link]] is encountered and the actual file is needed, and explicitly when not to: instead of guessing filenames or using semantic search. It names the alternative (semantic search) and explains why it's inferior for this purpose, making the use case very clear.

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

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

With no annotations provided, the description fully carries the behavioral burden. It details the envelope structure, distinguishes between 'semantic' and 'keyword' modes, explains coverage implications, warns about partial blindness, and specifies that empty results can mean absence or failure—critical for correct invocation and interpretation.

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?

The description is a single dense paragraph that front-loads the primary purpose and then explains the return envelope and failure modes. Every sentence adds essential value, clarifying edge cases that would otherwise be ambiguous. No filler or redundancy.

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?

Given the absence of an output schema and the tool's complexity (mode-dependent behavior, coverage calculation, warnings), the description is remarkably complete. It covers return structure, interpretation of edge cases, and actionable guidance, leaving no critical gaps for an agent to misuse the tool.

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?

The schema has 100% coverage for all three parameters, so baseline is 3. The description adds operational guidance beyond the schema, such as 'lower the threshold to widen recall' and typical relevance score ranges, which directly helps agents calibrate threshold and limit parameters effectively.

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 explicitly states 'Semantic search over the vault' which names the verb (search), resource (vault), and method (semantic). It clearly distinguishes from sibling tools like get_similar_notes and get_embedding_neighbors by focusing on vault-wide text search and explaining the envelope structure.

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?

The description provides clear context on how to interpret results (modes, coverage, warnings) and when to trust empty results, but does not explicitly name alternative tools for different use cases. It implies usage as the primary search tool but lacks explicit when/ when-not guidance against siblings.

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