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

With no annotations, the description carries the full burden. It explains directionality (source -> target), the automatic inverse link when bidirectional=true, and enumerates all link types with their inverses. This covers core behavior well, though it omits details about error handling or note existence validation.

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 well-structured with sections for purpose, link types, best practices, and args. It is fairly long but every sentence is informative and avoids redundancy, making it easy to parse.

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?

It covers all essential details for correct invocation: direction, link types, bidirectional behavior, parameter meanings, and best practices. The existence of an output schema means return values need not be explained. It lacks edge-case details (e.g., duplicate links), but that 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?

Schema coverage is 0% (schema only gives types and defaults), but the description fully compensates by explaining each parameter, including the valid values for link_type and the meaning of bidirectional. This adds significant semantic value 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 clearly states the tool's purpose: creating a semantic link between two notes. It distinguishes itself from sibling tools like slipbox_delete_link and slipbox_get_linked_notes by focusing on the create operation, and it adds nuance with directionality and link type semantics.

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 best practices (e.g., 'Create links immediately after creating notes') and explains when to use bidirectional=true, giving clear contextual guidance. However, it does not explicitly compare to alternatives like slipbox_remove_link or slipbox_get_linked_notes, which is a minor gap.

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 full behavioral burden and excels: it mandates exact content preservation ('Store content exactly as the user provided it'), explains note type behavior, requires references for literature notes, and warns against rewriting unless explicitly asked. This goes far beyond what the schema alone conveys.

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 long but appropriately structured into labeled sections (Note Types, Authoring, Best Practices, Args), with every section adding practical guidance. The core purpose is front-loaded in the first sentence, and the Args section maps cleanly to the schema.

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 complex creation tool with no annotations, the description covers note type semantics, staging workflow, content fidelity, tagging, duplicate avoidance, linking, and parameter formats. An agent has enough context to invoke it correctly without needing return-value details, especially since an output schema exists.

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 0%, so the description is the only source of parameter meaning. It defines title, content, note_type, tags, and references with formats, examples, defaults, and type-specific constraints, fully compensating for the empty schema descriptions.

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 'Create a new atomic Zettelkasten note,' a specific verb, resource, and core constraint. It clearly differentiates itself from siblings like slipbox_create_link and slipbox_update_note by focusing on note creation and atomicity.

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 gives explicit guidance: search first with slipbox_search_notes to avoid duplicates, create links immediately after with slipbox_create_link, and use 'fleeting' as a staging type when citations are missing. These are concrete when/when-not and alternative-tool instructions.

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 exist, so the description carries the behavioral burden. It discloses that the tool generates a structure note, organizes all member notes, and creates bidirectional links, and it notes the default create_links behavior in Args. It does not discuss failure modes or side effects on the cluster state, but for a creation operation the core behavior is transparent enough.

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 purpose is front-loaded, the prerequisite is in a short sentence, and the Args section is scannable. There is minor redundancy between the opening sentence and 'Generates a structure note...', but the added detail about bidirectional links earns its place.

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?

With an output schema present, the agent does not need the description to explain return values. The description covers the prerequisite, the behavior, and all parameters, which is sufficient for a 3-parameter creation tool with no nested objects. It does not address potential errors like invalid cluster IDs, but that is a minor gap.

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 0%, so the description must explain all parameters. It does: cluster_id is defined as an ID from the cluster report with a concrete example, title is an optional override of the suggested title, and create_links is explained with its default true. This fully compensates for the empty schema descriptions.

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: 'Create a structure note from a detected cluster.' It further clarifies that it organizes all notes in the cluster and creates bidirectional links, which distinguishes it from generic slipbox_create_note and from cluster-management siblings like slipbox_dismiss_cluster.

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 gives a concrete prerequisite: 'Run slipbox_get_cluster_report first to see available clusters and their IDs.' This tells an agent when in the workflow to call the tool. It does not explicitly state when not to use it or name alternatives, so it falls short of full routing guidance.

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 burden of disclosing behavior. It clearly conveys deletion and adds a meaningful edge-case behavior: it errors when no link exists. It does not discuss side effects, permissions, or reversibility, but for a targeted link deletion this is reasonably transparent.

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 compact and front-loaded, with the primary action first, the differentiating behavior second, and parameter explanations last. Every sentence earns its place with no filler.

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 two-parameter tool, the description covers the action, the key error condition, both parameter roles, and the distinction from the closest sibling. An output schema exists, so return-value details do not need to be spelled out here.

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 0%, so the description fully compensates by explaining both parameters: source_id is the note containing the link, and target_id is the note being linked to. This adds real meaning beyond the bare schema property names.

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: 'Delete a specific link from one note to another.' It also distinguishes itself from the sibling slipbox_remove_link by noting its error behavior, so an agent can tell the two apart without inspecting schemas.

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 names the sibling slipbox_remove_link and explains the key difference: this tool returns an error if no link exists. This makes the choice between the two tools clear, though it stops short of stating an explicit 'use this when you need...' rule.

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 disclosure burden. It warns that the deletion is permanent and that 'This also removes all links to and from this note', which are the critical side effects an agent must know before invoking the 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 compact and front-loaded: the purpose and the destructive warning appear immediately, and the Args section is minimal without unnecessary padding. Every sentence serves a purpose.

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 destructive tool with no annotations, the description covers the essential facts: irreversible deletion, link side effects, and a safer alternative. An output schema exists, so return-value documentation is not required, and nothing necessary for correct invocation is missing.

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 0%, so the description must compensate for the single parameter. However, it only restates 'The ID of the note to delete', which adds little beyond the parameter name 'note_id'. It omits any guidance on the ID format, where to obtain it, or whether any validation constraints apply.

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 'Delete a note permanently' – a specific verb, resource, and degree of effect. It distinguishes this from slipbox_delete_link and slipbox_update_note, and the context makes the destructive scope 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?

It explicitly advises 'Consider updating note_type to "fleeting" instead if uncertain', naming a concrete alternative for the uncertain case. This gives clear when-to-use and when-not-to-use guidance, with no ambiguity.

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 burden of disclosing safety and effects. It clearly states the action is 'permanently' applied and scoped to maintenance suggestions, which indicates irreversibility. It could go further by clarifying that no notes are deleted, but the permanence and scope are sufficiently conveyed.

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 compact and front-loaded: it states the core purpose in the first sentence, gives a short usage rationale, and includes a minimal Args section with an example. No sentence is wasted.

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 is simple with one required parameter and an output schema present, so return-value details are unnecessary. The description covers purpose, usage timing, permanence, and parameter example. A small gap is that it does not tell the user how to discover cluster IDs, but that is likely covered by sibling tools like get_cluster_report.

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 0% description coverage for cluster_id, so the description must compensate. It adds a concrete example ('poetry-craft-revision') and identifies the parameter as a cluster ID, but beyond that it mostly restates the parameter name. For a single simple string parameter, this is adequate but not enriching.

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 ('dismiss') with a clear resource ('cluster') and scope ('from maintenance suggestions'). It clearly distinguishes this from sibling tools like create_structure_from_cluster by positioning it as the 'don't remind me' action.

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 states when to use the tool: after a cluster has been reviewed and determined not to need a structure note, or when the user doesn't want reminders. It provides clear context but does not name or exclude specific alternative 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?

No annotations are provided, so the description carries the behavioral disclosure burden. It conveys a non-mutating query ('Find') and explains the central-note concept via incoming/outgoing links, but it does not state how results are ordered, how ties are handled, or whether 'limit' truncates a fully computed ranking. These are moderate gaps for a no-annotation 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 front-loaded with the core purpose and keeps explanatory text to two useful sentences before the Args block. It is compact and readable, though the Args section mostly duplicates the schema's default value rather than adding new 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?

For a one-optional-parameter tool with an output schema and no annotations, the description covers the essential purpose, the definition of central notes, and the limit parameter. It does not detail sorting or algorithm internals, but those are unlikely to be required for correct invocation; the main missing piece is explicit sibling-tool routing.

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 0% description coverage, and the description adds 'Maximum results (default: 10)', which clarifies that limit means result count and matches the schema default. It provides no guidance on allowed ranges, zero/negative values, or truncation behavior, but the parameter is simple enough that this is only a minor gap.

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 'Find the most connected notes in the Zettelkasten', a specific verb+resource statement, then defines central notes as hubs with the most incoming and outgoing links. This clearly distinguishes the tool from siblings like find_orphaned_notes or find_similar_notes by focusing on graph centrality.

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?

'Good candidates for hub notes' implies the intended use case of identifying key knowledge hubs. However, it never explicitly tells an agent when to prefer this tool over the many sibling search/find tools, nor when not to use it, so the guidance is implied rather than fully actionable.

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 burden of disclosing behavior. It correctly implies a read-only operation via the verb 'Find' and adds the interpretive context that orphaned notes represent unintegrated knowledge. However, it does not explicitly state side-effect freedom, output behavior, or other operational traits beyond the core result.

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 concise, front-loads the primary function in the first sentence, and each subsequent sentence adds meaningful context about why orphaned notes matter and what to do with the results. 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?

For a zero-parameter, read-only discovery tool with an output schema available, the description covers what the tool returns, why it matters, and how to act on the results. Nothing essential for invoking it correctly is missing.

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 and the schema coverage is 100%, so parameter documentation is unnecessary. Baseline for 0 params is 4; the description adds no parameter details but none are needed.

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 states a specific verb and resource: 'Find notes with no connections to other notes.' This clearly distinguishes the tool from siblings like slipbox_find_similar_notes and slipbox_find_central_notes, because it targets a unique criterion: absence of connections.

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 for when to use the tool: 'Review these periodically to either link them to existing notes or identify candidates for deletion.' It does not explicitly name alternative tools or state when not to use it, but the periodic-review purpose is useful and actionable.

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 implies a read-only operation through 'Find', but it does not explicitly state that it does not modify notes or that it is non-destructive. It does explain the similarity basis, which adds useful behavioral context, but it omits details about error behavior (e.g., missing note_id) or any side effects. The read-only nature is implied, not confirmed.

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 concise and well-structured. The primary purpose is front-loaded in the first sentence, followed by a brief explanation of similarity logic and then a clear Args list. No redundant or filler content; every sentence earns its place.

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 read-only query tool with an output schema, the description covers the core purpose, similarity logic, and parameters. It does not mention result ordering, behavior on nonexistent note_id, or any limitations, but these are minor given the output schema exists and the tool is straightforward. The description is nearly complete; a small gap is the lack of explicit note that the note must exist or that results are returned in any particular order.

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 0%, so the description must explain parameters. It does so thoroughly in the Args section: note_id as 'ID of the reference note', threshold as 'Minimum similarity score 0.0-1.0 (default: 0.3)', and limit as 'Maximum results (default: 5)'. This adds meaning beyond the bare schema, including ranges and defaults, fully enabling correct invocation.

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 'Find notes similar to a given note' with a specific verb (Find) and resource (notes similar to a reference). It further distinguishes itself from sibling tools by specifying similarity criteria (shared tags, common links, content overlap), making it distinct from search, central, or orphaned note tools. No ambiguity.

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 a usage hint: 'Useful for discovering connections you might have missed.' This implies when to use it, but it does not explicitly contrast it with alternatives like slipbox_search_notes or slipbox_get_linked_notes. There is no explicit statement of when not to use this tool or what conditions select it over siblings. The guidance is implied but not explicit.

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 present, so the description carries the burden of behavioral disclosure. It transparently states the read-only nature through the verb 'Get', discloses the alphabetical sorting behavior, and implies no side effects, which is sufficient for this simple 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 tight and front-loaded: purpose sentence, output behavior sentence, and usage guidance sentence. Every sentence contributes essential information with no redundancy or filler.

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 zero-parameter read-only tool with an output schema, the description is fully sufficient. It explains what is returned, the ordering, and when to use it, leaving no operational ambiguity for an agent deciding 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?

The tool has zero parameters)Skip, so there is no parameter semantics to explain. The schema coverage is effectively complete for an empty properties object, and the description adds value by describing the result rather than needing to describe inputs.

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-resource pair ('Get all tags in the Zettelkasten') and defines the output as an alphabetically sorted list. This clearly distinguishes it from sibling tools that operate on notes or links rather than tags.

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 advises using this tool before creating new notes to ensure tag consistency, giving a concrete when-to-use scenario. It does not explicitly name alternatives or state when not to use it, but the context is clear for a simple zero-parameter getter.

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 full burden. It discloses caching (default) and refresh behavior, automatic cron execution, and the scoring factors that influence results. It does not explicitly state that the operation is read-only (aside from the word 'get'), nor does it mention any auth or rate-limit requirements. Still, the disclosure of caching, refresh side effects, and scoring logic goes well beyond the schema, so a 4 is appropriate.

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 well-structured: a one-sentence purpose, a brief explanation, a bulleted list of scoring factors, and a clear Args block. It is not bloated, but the scoring factors could arguably be moved to a separate section without harming clarity. It is front-loaded with the core purpose, so it earns a 4.

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 presence of an output schema (which covers return values) and the fact that all four parameters are fully explained in the description, the tool is complete. The description covers purpose, behavior, scoring, and parameter semantics. No critical missing pieces like error handling or timeouts are necessary because the output schema and the tool's simple nature make them non-essential.

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 0%, so the description must fully compensate. It does: the 'Args' section explains each parameter with meaning and range (min_score 0.0-1.0), behavior (limit max clusters), and implications (include_notes, refresh). This adds significant value beyond the bare schema types and defaults, making it clear how each parameter affects the result.

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 clear, specific statement: 'Get pending cluster analysis for structure note creation.' It then explains what clusters are and how they relate to structure notes, distinguishing this tool from siblings like slipbox_refresh_clusters and slipbox_create_structure_from_cluster. The verb 'get' and the resource 'cluster analysis' are 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 provides strong contextual guidance: it explains that high-scoring clusters are candidates for structure notes, and mentions the caching behavior and automatic cron runs. However, it does not explicitly compare this tool to siblings like slipbox_refresh_clusters or slipbox_dismiss_cluster, nor does it state when to use an alternative. The guidance is implied rather than explicit, so it earns a 4 rather than 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?

There are no annotations, so the description carries the behavioral disclosure burden. It explains what the tool returns (linked notes), how direction affects the result set, and the default 'both' behavior. The imperative 'Get' implies a read-only operation, and no conflicting destructive behavior is suggested.

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, followed by a usage hint, a compact direction list, and an Args block. Every sentence adds useful information; there is no filler or over-elaboration.

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?

With an output schema available and only two parameters, the description covers the behavioral purpose, parameter semantics, directions, and default value. The only minor gap is the absence of explicit guidance on when to prefer sibling graph-analysis tools, but this does not block correct invocation.

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 0%, so parameter documentation falls entirely on the description. It explains note_id as the starting point and direction with its allowed values and default. It could add more constraints for note_id, but the provided semantics are sufficient for a two-parameter tool.

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 starts with a precise verb-resource pair: 'Get notes linked to or from a specific note.' It defines outgoing/incoming/both directions and frames the tool as knowledge-graph exploration, clearly distinguishing it from single-note retrieval or search tools like slipbox_get_note or slipbox_search_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?

'Use this to explore the knowledge graph around a note' gives a clear context for when to call it, and the direction definitions clarify the kind of traversal intended. It does not explicitly say when not to use it or name a sibling alternative, but the intended use is evident.

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 burden of behavioral disclosure. It effectively communicates read-only behavior and details what the response contains ('full note content including metadata, tags, and links'), which goes beyond the schema. It does not cover failure modes such as missing identifiers, but this is a minor gap for a simple retrieval 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 compact, front-loaded, and every line earns its place: purpose, return contents, usage guidance, and parameter meaning. No filler or irrelevant detail.

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 one-parameter read tool with an output schema present, the description covers the essential aspects: what the tool does, how to identify the note, and when to use it. It lacks explicit not-found or error behavior, but that is not critical for normal invocation.

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 0%, so the description must compensate for the bare 'identifier' parameter. It does so by explaining that the identifier can be a note ID or exact title and gives a concrete ID format example. Ambiguity handling between the two forms is not addressed, but the compensation is strong for a single parameter.

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?

States a specific action ('Retrieve a note') with resource and lookup method ('by ID or title'), and clarifies the result includes full content, metadata, tags, and links. This clearly differentiates it from sibling read tools like search_notes or get_linked_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?

Explicitly says to use this tool 'to read note contents before creating links or updates,' which is a clear usage context tied to relevant siblings. It does not mention when NOT to use it or name alternatives, so it stops 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, the description carries the burden of behavioral disclosure. It explains filtering by created_at or updated_at, optional date bounds, and the default limit. However, it does not disclose result ordering, how date boundaries are handled, or pagination behavior, leaving some uncertainty about exact behavior.

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 compact, front-loaded with the primary action, and organized with a clear Args block. It is slightly redundant with the schema's property definitions, but since the schema lacks descriptions, the explicit parameter documentation is justified and easy to scan.

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 read-only listing tool with an output schema, the description covers the essential invocation details and parameter semantics. It does not discuss ordering or edge cases, but the output schema and the simplicity of the operation make the definition sufficiently complete for correct invocation.

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 0%, so the description must fully compensate. It explains every parameter beyond the raw schema: ISO date format for start_date/end_date, the true/false semantics of use_updated, and the default limit. This is exactly the kind of parameter-level guidance an agent needs.

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 notes by creation or update date.' This makes the tool's purpose immediately clear and distinguishes it from content-based or similarity-based sibling tools. It also gives practical use cases, reinforcing what the tool is for.

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 states when the tool is appropriate: 'Useful for reviewing recent work or finding notes from a specific period.' It provides clear context, though it does not explicitly point to alternatives such as slipbox_search_notes for content-based lookup or when not to use this tool.

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 must carry the full burden of behavioral disclosure. It states what the tool does (rebuild index) but does not reveal any side effects, such as whether it overwrites the existing index, if it destroys data, if it requires exclusive access, or if it is safe to run concurrently. For a maintenance operation that modifies state, this is a significant gap.

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 sentences with zero wasted words. The action is front-loaded, and the usage context is delivered in the second sentence. It is appropriately concise for a zero-parameter maintenance tool.

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 no parameters and an output schema present, the description provides the essential trigger conditions. However, it omits behavioral details like whether the operation is destructive, if it locks the database, or if it can be run while other operations are in progress. Given no annotations, the description should disclose more about the operation's impact, so a 3 is appropriate.

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 according to the scoring rule the baseline is 4. The description adds no parameter-specific information, but none is needed; the schema already confirms an empty parameter set. The description's clarity about the action suffices.

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 states a specific verb ('rebuild'), resource ('database index'), and source ('from markdown files'), which clearly distinguishes it from sibling tools that handle notes, links, clusters, or searches. There is no other rebuild-oriented sibling, so the purpose is 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 explicitly states when to use the tool: when notes were edited outside the MCP server or the database seems out of sync with the filesystem. It provides clear context for invocation but does not mention alternatives or exclusions, which is acceptable since this is a unique maintenance operation with no direct sibling alternative.

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 behavioral disclosure burden. It clearly states the tool scans all notes, uses three clustering signals, and writes results to cluster-analysis.json or SLIPBOX_CLUSTER_REPORT_PATH. It does not explicitly say whether the existing report is overwritten or whether the SQLite index must exist, but the 'regenerate' and 'saved to' language covers the primary side effect.

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 first sentence is a crisp summary, followed by a scannable bulleted list of analysis criteria and a clear statement of the output location. Every sentence adds necessary information with no repetition or filler.

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 zero-parameter command with an output schema available, the description provides the essential execution facts: what is analyzed, how clusters are formed, and where the report is written. It would be slightly stronger with an explicit pointer to slipbox_get_cluster_report for reading the saved report, but that gap does not block correct invocation.

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 and the empty schema is fully self-documenting, so the baseline of 4 applies. The description enhances understanding by explaining what the analysis is based on, even though there are no parameter meanings to clarify.

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 opening sentence names a specific operation ('Regenerate cluster analysis and save report'), and the bulleted list defines the analysis scope. This distinguishes it from siblings like slipbox_get_cluster_report and slipbox_dismiss_cluster by focusing on regeneration and report writing.

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 this should be used when refreshed cluster analysis is needed, and it states the analysis dimensions. However, it does not explicitly contrast it with slipbox_get_cluster_report for reading existing reports or 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?

No annotations are provided, so the description carries the full behavioral disclosure burden. It states the removal operation and the bidirectional option, but does not disclose idempotency, behavior when the link does not exist, side effects, or whether the operation is reversible—important gaps for a destructive action.

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 compact and well-structured: one clear purpose sentence followed by a scannable argument list. There is no filler or repetition beyond the necessary parameter explanations.

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 three-parameter scalar tool with an output schema, the core invocation is understandable. However, the lack of sibling differentiation and the absence of behavioral guidance around a destructive operation make the description incomplete for a fully informed tool selection.

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 0%, and the description adds definitions for source_id, target_id, and bidirectional, which is helpful. However, the definitions are minimal and mostly restate the parameter names; they do not specify ID formats, lookup semantics, or additional constraints beyond what the schema already shows.

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 action and resource: 'Remove a link between two notes.' However, it does not differentiate this tool from the sibling slipbox_delete_link, which appears to have an overlapping purpose, so it stops short of full sibling-level clarity.

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 offers no guidance on when to use this tool instead of slipbox_delete_link or any other alternative. It only explains parameters, leaving the agent to infer the intended context from the tool name.

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 of behavioral disclosure. It does not mention any side effects, permissions, ordering, pagination, or behavior when no query is supplied (e.g., returns all notes). It only states the action, not the consequences or edge cases. This is a significant gap for a search tool that could return unexpected results if called with empty parameters.

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 well-structured with a clear opening sentence, followed by explanatory text and a formatted Args section. It uses examples to illustrate usage without being verbose. It could be slightly more concise in the intro, but the structure is logical and front-loaded with the core purpose. No 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?

Given the tool has 4 optional parameters and no required ones, the description covers each parameter's semantics well. However, it omits edge-case behavior such as what happens with no parameters (does it return all notes?) or how results are ordered. Since an output schema exists, return format is covered, but behavioral edge cases are not. It's adequate for basic usage but leaves some ambiguity.

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 0%, so the description must explain parameters. It does this thoroughly: query searches titles and content, tags are comma-separated, note_type lists allowed values (fleeting/literature/permanent/structure/hub), and limit has a default of 10. Examples illustrate parameter combinations. This adds substantial meaning beyond the schema's minimal type/default information.

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 'Search for notes by text, tags, or type' and elaborates that it searches across titles and content. This is specific and distinct from sibling tools like slipbox_get_note (retrieves a single note) or slipbox_list_notes_by_date (lists by date). The verb 'search' and resource 'notes' are explicit, making the 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 provides concrete examples for each parameter combination, demonstrating when to use query, tags, note_type, and limit. It implies usage scenarios clearly. While it doesn't explicitly mention alternatives or when not to use this tool, the sibling tools have distinct purposes, so an agent can infer appropriate usage. It's strong but lacks explicit exclusion guidance.

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 full burden and does well: it discloses that omitted fields remain unchanged, that empty strings clear tags/references, and that literature notes require at least one reference. It does not cover error behavior for missing note_ids or response details, but the key behavioral traits are surfaced.

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 well organized: behavioral notes come first, followed by a compact Args list. There is minor redundancy between the prose and the Args section regarding empty-string clearing, but no wasted sentences overall.

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 annotations and no schema descriptions, the description covers all six parameters plus the critical literature-reference constraint. An output schema exists, so return-value documentation is not required. It could add behavior for nonexistent notes, but the description is substantially complete.

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 0%, and the Args section fully compensates by explaining every parameter's meaning, allowed note_type values, comma-separated tags, newline-separated references, and empty-string clearing behavior. This is exactly the kind of parameter-level detail an agent needs.

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 'Update' and the resource 'existing note', so it is unambiguous that this tool mutates an existing slipbox note. It does not explicitly differentiate from siblings like slipbox_create_note or slipbox_delete_note, but the verb+resource combination leaves little room for confusion.

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 conveys when to use the tool by explaining partial-update semantics and the promotion constraint to literature notes. It does not explicitly say 'use this instead of create/delete' or provide when-not-to-use guidance, but the context is clear enough that an agent can route appropriately.

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