Kybase

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

With no annotations, the description carries full disclosure burden and meets it: it explains the no-resend behavior, the inserted blank-line separator, and the background re-embed side effect. These are concrete behavioral traits beyond what the schema states.

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?

Three tight sentences cover purpose, preference over an alternative, formatting behavior, and side effects. No repetition of schema details and 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?

The description plus schema covers the main decision (append vs update), target resolution (id/title/section), placement semantics (at), and the side-effect profile. It does not describe return values or error conditions, but for a no-output-schema append operation that gap is minor. Overall it is sufficient 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 60% and the tool description adds no direct parameter semantics beyond referring generally to 'your text'. The schema already documents at, title, section and content constraints, so the description provides no extra parameter-level value. Baseline 3 is appropriate given partial schema coverage.

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 'Add text to a note without resending the rest,' a specific verb-resource pair, and explicitly contrasts it with update_note. This makes the tool's scope unambiguous and distinguishes it from sibling mutation tools.

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 to prefer this tool over update_note for journals, logs and running lists, naming both the alternative and the usage context. This is direct when-to-use guidance the agent does not have to infer.

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 discloses a create mutation and optional nesting, but it does not state important behaviors such as idempotency (what if a folder with the same name exists), required parent existence, permissions, or what happens on failure/success. The only added note about optional nesting is already derivable from the schema (parent_id non-required), so it adds little beyond the structured data.

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 extremely lean: two sentences, four main pieces of information, no redundancy. The purpose is front-loaded ('Create a new folder') and the only nuance (optional nesting) follows directly. Every word earns its place, and the structure is ideal for a search model.

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?

Although the operation is relatively simple, the description is not complete enough for correct invocation. It doesn't mention the existence of a parent (e.g., that parent must already exist) or the output/return value (no output schema). An agent cannot tell from this description what success looks like or whether there are preconditions, side effects, or uniqueness constraints—important gaps for a create 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 schema has 0% description coverage, so the tool description must compensate for the undefined parameter semantics. It does add the note that the folder may be nested under a parent, clarifying the parent_id purpose, but it does not describe the name parameter beyond its existence or any constraints. It fails to explain that 'parent' means a folder ID, the expected naming conventions, or how nested paths work, leaving the agent to infer too much.

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 a verb and resource: 'Create a new folder.' It also adds a key scoping nuance, 'Optionally nested under a parent,' which distinguishes it from sibling tools like update_folder, delete_folder, and create_note without needing to inspect those schemas. The resource and action 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 offers no guidance on when to use this tool vs alternatives. It does not mention any exclusions, prerequisites, or competing tools, leaving the agent to infer solely from the tool name. Without context such as 'Use this when you need to create a folder and not when...' the selection criteria are absent.

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 usefully reveals that embedding is generated automatically in the background and that server-side wikilink/tag rules apply. It does not mention what the tool returns, whether creation is synchronous, or failure behavior, leaving some operational gaps.

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 no filler: purpose first, then a noteworthy behavioral detail, then the required server rules. Every clause earns its place and the most important instruction is front-loaded.

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 definition covers the core action, background embedding, and required pre-steps, which is sufficient for basic usage. However, with no annotations and no output schema, it leaves return value, embedding completion status, and folder selection guidance largely unstated.

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 only 20%, so the description must compensate. It adds meaningful semantics for the tags parameter by requiring verification against list_tags before coining new tags. It does not clarify title, content, folder_id, or the relationship between folder_id and folder_path beyond what the schema already states.

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 note,' which clearly states the verb and resource. It does not explicitly distinguish itself from siblings like append_to_note or update_note, though the create semantic makes the primary intent 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 gives explicit pre-use workflow instructions: search_notes first, link related notes, and call list_tags before introducing a new tag. However, it does not state when to prefer an alternative such as update_note or append_to_note, so it lacks explicit 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?

Since no annotations are provided, the description carries the full burden. It explicitly discloses that the operation is destructive (cascade delete), that notes are soft-deleted (recoverable), the recovery context (restore_note, retention window), and that the action is irreversible in the sense of losing folder structure unless moved first. It also notes the side effect of moving content. This is strong for a destructive 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 concise, front-loaded with the primary effect (cascade delete), then explains consequences and provides an alternative. No redundancy, every sentence adds value. It is appropriately structured for a destructive operation.

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 destructive tool with no output schema, the description covers the key aspects: cascade deletion, soft-delete behavior, recovery, and an alternative. It could also mention if there are any permission requirements or if the operation fails for non-existent folders, but these are likely self-explanatory. Overall, it is complete enough for the agent to call correctly.

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 provides the parameter 'id' with format UUID and pattern, but no description. The tool's description doesn't directly describe the parameter, but it implicitly indicates that 'id' identifies the folder to delete. Since the schema coverage is 0% and there is only one parameter, the description's context is enough to infer. However, it doesn't explicitly say 'the id is the folder identifier', but that is obvious from context. Given the single param, score 4 is fair.

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 deletes a folder and its full subtree, and distinguishes cascading behavior from a single item deletion. It names the sibling delete_note and contrasts with delete_note, making the purpose unmistakable.

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 explains the cascade behavior and its implications for notes in subfolders, and gives an alternative approach (move items out) to preserve organization. However, it does not explicitly say when NOT to use it (e.g., if you want to keep any content), but the alternative is 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 carries the full behavioral burden and does so very well. It discloses that the operation is a soft delete, what views are affected, that the note is recoverable for 30 days, and that it is eventually purged. This far exceeds a generic 'deletes a note' description.

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?

Two sentences front-load the primary behavior and then provide the most relevant recovery and inspection guidance. Every clause adds useful information and there is 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 single-parameter operation with no output schema, the description is complete: it explains the immediate effect, the recovery window, the eventual purge, and how to view trashed notes. No critical calling context 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 description only says 'by id', which adds little beyond the schema's property name for the id parameter. Since schema description coverage is 0%, the description should compensate, but it does not explain valid IDs, behavior for missing IDs, or idempotency. The schema itself defines UUID format, but the description adds no meaning beyond that.

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?

Clearly states that this tool soft-deletes a note by id and describes the exact effect: the note disappears from list_notes, search, get_note, and the graph. This distinguishes it from related tools like restore_note and delete_folder.

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?

Explains that the delete is recoverable and points to restore_note as the recovery path, and instructs agents to use list_notes with trashed:true to inspect the trash. It provides clear context for when to use the tool, though it does not explicitly exclude cases like permanently deleting or deleting folders.

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 disclosure burden and meets it: it states the default return shape (id/title/folder_path plus snippet), warns that include_content is expensive, says results are paginated, and documents exact→prefix→substring title resolution. This goes well beyond what the schema alone provides.

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?

Three sentences, front-loaded with purpose, with each clause adding a distinct operational fact: return shape, cost trade-off, pagination, and id/title resolution. There is no filler or repetition.

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 lookup with no output schema, the description provides the essentials: what it returns by default, what the expensive alternative returns, pagination behavior, and parameter semantics. There is nothing an agent needs to invoke this tool correctly that 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 descriptions are 0%, but the description compensates by explaining the meaning of id/title (either works, with explicit resolution), include_content (full text, expensive), and the paginated nature of limit/offset. The schema still supplies defaults and constraints, so together they are sufficient.

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: 'Get notes that link to the given note via [[Title]] wikilinks.' This unambiguously defines the tool as an inbound-wikilink lookup and separates it from get_note, search_notes, and get_neighbors.

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 tells the agent when to use the default response versus include_content:true, and names get_note as the cheaper alternative for retrieving full text of specific notes. It also communicates pagination convention and the forgiving title lookup order, so the agent knows how to call it correctly and when to prefer another 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It details the return format thoroughly, explains that semantic_edges are based on cosine similarity, and clarifies that unresolved_links are not edges but dangling references. The warning about the unfiltered response potentially not fitting in context is a valuable behavioral trait. It doesn't explicitly state read-only behavior, but given the focus on retrieval and the lack of any mutation verbs, it's implicitly safe.

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 dense and information-rich, but it is slightly long, covering multiple aspects such as structure, semantics, and usage warnings. It front-loads the core purpose and structural details, which is effective, but the later part about node titles being valid wikilink targets adds context that might be less critical. Overall, it is efficient without being verbose.

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 (multiple edge types, indexing conventions, and scoping options), the description covers most essential details: node format, edge indexing, semantic edge threshold, unresolved links, and scoping recommendations. It lacks some information like whether depth is inclusive or exclusive, but that is handled by the schema. The warning about context limits is crucial for an agent. No output schema exists, so the description must cover return format, which it does thoroughly.

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 provides 100% description coverage for all six parameters, including their purpose and constraints. The description adds context by explaining how these parameters affect the graph structure (e.g., depth for hop count, min_score for semantic edge threshold) and how nodes reference each other. However, this is marginal value beyond the schema; the description could have delved deeper into parameter interactions, but the baseline of 3 is appropriate given high schema coverage.

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 identifies the tool's purpose: to retrieve a knowledge graph with specific node/edge types. It distinguishes itself from siblings by focusing on graph structure rather than individual notes or lists. The explanation of nodes, edges, and semantic_edges is specific and actionable.

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 this tool versus alternatives: it recommends scoping with folder_id or root_title+depth when you need only part of the graph, and it warns about the unfiltered full-vault return being too large for context. This guidance is direct and practical, helping the agent choose appropriate parameters.

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 transparency burden, and it delivers: undirected traversal, links_out/links_in sent only when true, absence at depth 2 meaning no arrow direction, deduplication at shortest depth, and the distinction between human-written links and semantic similarity. It even defines what an empty result means.

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 densely purposeful: every paragraph explains a non-obvious behavior or decision boundary, and the core purpose is front-loaded in the first sentence. The extended clarifications prevent misinterpretations that would otherwise require trial and error.

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 covers output shape, traversal semantics, and empty-result meaning very thoroughly. The main gap is target-note parameter resolution: an agent still cannot be fully certain whether to pass id, title, or both, and what happens if both are supplied.

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 only 33%, so the description must compensate, but it never explains how the target note is identified via id or title, nor their relationship or precedence. It adds excellent semantics for depth, but the two most important parameters for addressing 'ONE note' are left essentially undocumented.

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 first sentence states a specific operation with a precise resource and scope: 'What is around ONE note in the [[wikilink]] graph, out to depth hops.' It also clarifies the output shape ('flat list of titles') and explicitly contrasts itself with get_graph, making it easy to distinguish from siblings.

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 routing guidance: use get_graph for the edge structure with 'same scope,' and use get_graph's semantic_edges or search when similarity or finding a note is the goal. It also explains when an empty result is meaningful, so an agent knows what conclusion to draw.

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, and it does so extensively. It discloses windowing behavior and the content_truncated/content_total_length flags, how headings behave when notes are truncated, section offset re-basing, one-level-deep wikilink resolution, the 4000-char cap on included linked-note content, and the subtle difference between updated_at and content_updated_at. No behavioral surprises are left for the agent to discover at call time.

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 nearly every sentence carries functional information that is not available anywhere else since there are no annotations and no output schema. It is front-loaded with the core purpose and moves logically from retrieval to pagination, headings, sections, link resolution, and timestamps. It is not concise, but the length is justified by the tool's complexity; it loses a point only because a more scannable structure (e.g., shorter paragraphs or labeled behaviors) would help agent parsing.

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?

This is a complex tool with 7 parameters, zero required fields, no annotations, and no output schema, so the description must cover invocation behavior, return fields, and edge cases. It does: response fields like content_truncated, content_total_length, headings, next_offset, and unresolved links are all explained; pagination, section mode, link resolution, and timestamp semantics are fully covered. Nothing needed to call the tool correctly appears to be 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 coverage is 71%, and the description substantially compensates for the undocumented params (id, title) while adding meaning to the documented ones. It explains title matching fallbacks, the meaning of offset/limit in windowing and section mode, section selection semantics, resolve_links depth, and include_content tradeoffs. This goes well beyond the schema and makes parameter behavior predictable.

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 states a specific verb and resource: 'Get full note content by id or title.' It immediately distinguishes the tool from list/search siblings by focusing on retrieving a single note's full content, and the rest of the description clarifies the nuanced retrieval semantics (title matching, windowing, sections). This is unambiguous and distinguishes the tool's role among the sibling tools.

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 advanced options: use resolve_links when 'you need a note's linked context without extra round-trips' and use section to fetch a heading and its body alone. It does not explicitly contrast this tool with sibling alternatives like list_notes or search_notes, but for a single-note fetch tool the intended use is well implied. The absence of explicit exclusions or alternative-tool routing keeps it from 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, and it does so thoroughly. It explains the behavior of pending notes (still found by text search), notes with previous embeddings (remain in semantic search with last vector), and never-embedded notes (excluded until processed). It also discloses the default semantic cutoff behavior, the meaning of semantic_profile values, and the non-comparability of raw cosines across models. This is exemplary transparency.

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 information-dense, covering multiple important behaviors and caveats. It is front-loaded with the core status semantics, then expands into edge cases and configuration details. While it could be tightened, every sentence adds meaningful context that an agent would need to correctly interpret the tool's output. The length is justified by the complexity of the semantic search behavior it explains.

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 status tool with no output schema, the description is remarkably complete. It explains what the tool reports, how to interpret each piece of information, what the default behavior is, why the model name is included, and what to do if the count appears stuck. An agent has everything it needs to call this tool and correctly interpret its results.

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 the schema is trivially complete. The description adds substantial context about what the tool reports (total/indexed/pending counts, completion flag, model name, cutoff status), which is more than enough for an agent to understand what the tool will return. A 4 is appropriate because while there are no parameters to document, the description goes beyond the schema in explaining the tool's output semantics.

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 precise summary: 'Semantic-index progress: total/indexed/pending notes, complete=true when pending=0.' This states the tool's function (reporting indexing status) and its key output semantics. It clearly distinguishes itself from sibling tools like search_notes or get_note by focusing on index progress and embedding model information.

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 tells the agent when to use this tool: to check indexing progress, to understand why pending notes may be stuck (check Ollama/server logs), and to determine the active embedding model and any semantic cutoff. It also explains when not to rely on it: it doesn't filter search results, and it clarifies that automatic abstention is not part of the default retrieval contract. This is strong usage 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 disclosure burden. It usefully reveals two behavioral traits: the return shape is a flat array and paths are already resolved. However, it does not mention ordering, whether deleted or hidden folders are included, or what fields accompany each folder. It is helpful but not fully 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?

Two compact sentences, each earning its place: the first defines the core behavior and output shape, and the second gives actionable downstream usage. Information is front-loaded and there is no filler or repetition of schema data.

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 parameterless, read-only listing tool with no output schema, the description is complete enough for an agent to call it correctly. It states what the tool returns, how the result is structured, and how the result should be used in related operations. Nothing essential 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?

This tool has zero parameters, and the schema already covers that fully, so the baseline is 4. The description adds relevant context by explaining how returned folder ids should be used with create_folder/update_folder, though it does not need to explain any parameters of this tool itself.

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: "List all folders (flat array)". It also clarifies the key distinguishing behavior—"full path already resolved—no need to walk parent_id yourself"—so the tool is immediately distinguishable from related tree-walking or graph tools. This is a precise, unambiguous purpose statement.

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 contextual guidance for when this tool is useful: you get complete folder paths without manually traversing parent_id. It also tells you how to use the result, saying to pass a folder's id as parent_id to create_folder/update_folder. It does not explicitly name alternatives or exclusions, but the intended context is 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, the description carries the full behavioral burden and delivers richly. It discloses subtle behavior around updated_after (only own edits count, not link rewrites from other notes), the trashed-mode filter override, soft-delete recoverability, and that content_length is included so long notes can be distinguished without a fetch.

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 every sentence carries useful information, with no filler. It is, however, a long single paragraph packing multiple nested caveats, which makes it denser than necessary; splitting the timestamp guidance and trashed-mode guidance would improve scannability.

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 9-parameter tool with no output schema, the description covers the tricky filter semantics, sorting, and trashed behavior well enough to invoke correctly. It does not describe the full response shape or pagination beyond limit, so an agent is left to infer what fields besides updated_at and content_length are returned.

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?

Despite 89% schema coverage, the description adds significant semantic value beyond the schema. It explains the meaning of created_after vs updated_after, the sort default and its effect, the max limit of 200, and the fact that trashed:true ignores other filters. These are distinctions an agent cannot reliably infer from parameter names alone.

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') and immediately adds the ordering rule ('sorted by recency'). It also differentiates from siblings by noting content_length can avoid a get_note call and by tying trashed mode to restore_note, so an agent can tell this endpoint apart from adjacent tools.

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 strong situational guidance: created_after is for 'what is new', updated_after is for 'what changed since I was last here', and it explicitly warns they are not interchangeable. It also explains trashed mode and that other filters are ignored there. However, it never explicitly names alternatives like search_notes for cases where list_notes would be the wrong 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?

With no annotations provided, the description carries the full burden and does so well. It discloses sorting order, the default cap, the behavior that one-off tags are omitted, and the reason behind that default. This goes well beyond a minimal read-only hint.

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?

Three focused sentences: the first states core behavior, the second provides workflow guidance, and the third explains default cutoff behavior. No filler or repetition; 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 one-parameter, read-only listing tool with no output schema, the description covers result content, ordering, cap, and usage rationale. Nothing critical is missing for an agent to select and invoke this tool correctly.

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 already documents the limit parameter with default, min, max, and a description. The tool description adds value by explaining what the default cutoff means in practice and why raising the limit may be necessary, which helps the agent reason about the parameter's effect.

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 a specific verb and resource: 'List tags in use with the number of notes carrying each, most-used first.' It also includes sorting and cap behavior, which distinguishes it from sibling tools like list_notes and list_folders.

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 instructs when to call the tool: 'Call this before tagging a note and reuse an existing tag when one fits.' It also explains the rationale for avoiding near-duplicates and notes the vault has no tag synonyms, making the usage guidance concrete 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?

With no annotations, the description carries full behavioral burden and excels: it discloses the expected_count safety guard, the aliasing equivalence, the ordering semantics of batch edits, the atomicity of the batch (whole batch refused, note untouched), and the error behavior that names the failing index. This goes well beyond what annotations could have provided.

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 dense but every sentence earns its place. It is front-loaded with the core behavior, then progressively explains the safeguard, aliases, batch usage, sequencing, atomicity, and the prohibition on combining forms. No redundancy or filler exists.

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 thoroughly covers the tool's behavior and edge cases, but does not state that a note must be identified via `id` or `title` (even though the schema lists required as zero). For an API call, that is a meaningful omission; otherwise the operational details are 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?

Though schema coverage is high at 78%, the description adds substantial meaning beyond the schema: it explains the alias equivalence (find/old_string, replace/new_string), the semantic difference between singular and batch forms, the order-dependent matching ('each one's find is matched against the note as already changed by the edits before it'), and the all-or-nothing batch result. These are not evident from parameter definitions alone.

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: 'Replace exact text in a note without resending the rest.' It clearly distinguishes this targeted operation from siblings like update_note and append_to_note by emphasizing exact-match replacement and avoiding a full rewrite.

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 clear context for when to use the tool ('without resending the rest') and provides detailed internal guidance on choosing between singular fields and the `edits` array. However, it does not explicitly name sibling tools as alternatives or state 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 exist, so the description carries the burden of exposing mutation semantics. It clearly says the note is brought back and enumerates the error cases. It doesn't state whether restore is reversible or what metadata changes, but for this scope it 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?

Two sentences, both informative. First sentence states the primary action; second sentence enumerates error cases and a remediation step. No filler or schema repetition.

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 single-parameter tool with no output schema, the description covers purpose, preconditions, error scenarios collectivized and a remedy. The only notable gap from an agent perspective is not explicitly naming the id parameter as the note identifier, but the context makes it clear.

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 has zero description coverage and the tool description never explicitly explains that the single id parameter must be the ID of the soft-deleted note. It is inferable from the tool purposeholster, but the description adds no parameter-level meaning.

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 operational purpose: 'Undo delete_note: brings a soft-deleted note back.' This clearly identifies the action, the resource affected, and the precondition (the note must be soft-deleted). There is no ambiguity about what restore_note does.

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?

States when to use it (to undo delete_note on a soft-deleted note) and, importantly, when it will fail: never deleted, already restored, purged past retention, or title conflict. It even gives a recovery step ('rename one first, then retry'), which an agent can act on directly.

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 burden—and it does so thoroughly. It discloses that results are candidate retrieval, not factual answers; that empty results mean nothing was indexed; that relevance is relative, not absolute; that index_pending means the excerpt is stale; and that reranking is a model opinion, not confidence. It also explains the meaning of reranked:true/false and how to interpret threshold and pending_embeddings. This is exemplary transparency.

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 extraordinarily long (several thousand words) and dense, but it is well-structured with clear topical paragraphs (query semantics, reading hits, relevance, filters, reranking, debug flags). It front-loads the core purpose and gives critical routing advice early. However, some repetition occurs (e.g., multiple warnings that scores don't confirm existence), and it could likely be trimmed ~30% without losing value. Still, it is organized and each paragraph covers distinct concerns, so it earns a high score.

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 (13 parameters, no output schema, many subtle response fields), the description is remarkably complete. It explains every response field mentioned (has_more, next_offset, excerpt_offset, section, relevance, matched_by, text_tier, coverage, exact, threshold, best_score, pending_embeddings, stale_generation_chunks, question_echo, reranked, rerank_score). It also covers edge cases like wildcards and multi-word tokens. An agent calling this tool would know exactly what to expect and how to interpret results for next steps.

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 high (77%), but the description adds significant meaning beyond the schema. For example, it distinguishes created_after/before from updated_after/before (the latter only counts own-content changes, not link rewrites), explains folder_id vs folder_path (no need to look up UUID), and details how rerank and explain affect behavior. It also clarifies type enum semantics (text vs semantic vs hybrid) beyond the basic default. The description compensates for any gaps in schema documentation.

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 'Search notes' and immediately distinguishes itself from siblings: it explicitly says to use list_notes for folder/tag/recency filtering without keywords, and to use get_note to read full notes. It clearly states the tool is for ranking text against a query, not for listing or filtering. This makes it unambiguous which tool to pick.

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 usage guidance: when to prefer type=text (exact identifiers, code fragments, quoted phrases) vs hybrid (default), when to use list_notes instead of search, and how to chain with get_note using section/offset. It even explains when NOT to use search (e.g., 'latest state of X' should use list_notes first). This is exhaustive 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?

With no annotations, the description carries the behavioral disclosure burden. It discloses that the response includes the resolved path, letting the agent confirm the result without a follow-up call, and explains the parent_id null semantics. It does not cover error cases like invalid parent folders or cycles, but the core behavior is clearly 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?

Three sentences with no filler. The main operation is front-loaded, followed by parameter constraints and a valuable response-behavior note. Every sentence adds necessary 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 simple three-parameter update tool with no output schema or annotations, the description covers the operation, the required/optional parameter relationship, the null case, and the response format. Missing edge-case details such as folder-name conflicts or move-cycle prevention would improve completeness, but the agent has enough to invoke the tool correctly.

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. It adds real meaning beyond the schema by explaining that name triggers a rename, parent_id triggers a move, null means top level, and at least one of the two is required. This is strong compensation for a low-coverage 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 specific verbs ('rename', 'move') tied to the folder resource, which clearly distinguishes it from sibling tools like create_folder, delete_folder, and list_folders. The operation is unmistakable even without examining the schema.

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 clear conditions: at least one of name/parent_id must be supplied, and parent_id null targets the top level. It does not explicitly name alternatives or state when not to use this tool, but the purpose statement makes the intended use obvious.

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 behavioral disclosure burden. It reveals that title/content changes trigger re-embedding, title changes update wikilinks, substantial rewrites are subject to server rules, and expected_updated_at causes a refusal instead of silent overwrite. It does not mention return shape, errors, or how tag changes behave, but the core mutation behavior is well covered.

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 four dense sentences with no filler. The core action is front-loaded, side effects are stated immediately, and the concurrency/tag guidance 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 an update tool with no output schema and no annotations, the description supplies the critical operational facts: when side effects happen, when server rules apply, and how to avoid lost updates. It could mention the return value or folder_id null behavior, but the essential information for correct invocation is present.

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?

Only expected_updated_at has a schema description, so the description must compensate for low coverage. It does clarify expected_updated_at semantics and connects title/content to side effects. However, it adds little meaning for id, tags, or folder_id beyond their names and schema types.

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 verb and resource: 'Update note fields.' The additional side-effect details (re-embedding, wikilink updates) help characterize this as a field-level update tool rather than an append or replace operation. It does not explicitly contrast with create_note or append_to_note, so it misses the top score.

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 clear context for when to use this tool: to update fields of an existing note. It also supplies actionable guidance, such as calling list_tags before coining a new tag and passing expected_updated_at for optimistic concurrency. It does not explicitly state when to prefer append_to_note or replace_in_note, so it is not a full 5.

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