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. It adds only that the tool returns an id; it says nothing about persistence scope, permission requirements, duplicate handling, or whether tags/project must pre-exist. For a write tool with zero annotation coverage that is a substantial 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?

Two short sentences, zero waste, with the purpose front-loaded before the return-value note. Its brevity is a virtue structurally, though it shades into under-specification for a 4-parameter write 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?

An output schema exists, so 'Returns its id' being terse is acceptable, but with no annotations, 0% parameter coverage, and an undocumented project-scoping parameter, the definition leaves an agent without enough to call this correctly in a multi-project store.

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 mentions none of the four parameters — not title, text, tags, or project. The non-obvious 'project' parameter (default 'default') and the tags array are completely undocumented anywhere, so the description does not compensate at all for the coverage 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?

Specific verb+resource ('Save a note') plus a parenthetical naming the kinds of content it holds (decision, finding, how-to), which makes the intent concrete. It does not explicitly differentiate itself from the sibling update_note, so an agent must infer that 'Save' means create-new rather than amend-existing.

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 content-type examples imply when this tool is appropriate (capturing decisions, findings, how-tos), but there is no explicit routing versus update_note, get, or search, and no statement about when not to use it. Usage is inferable but not guided.

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 the important recoverability trait ('stays recoverable through restore_version'), which is valuable beyond the schema, but omits permissions, permanence after version lifetime, and side effects on chunks.

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 short sentences, front-loaded with the action and followed by the key recoverability note. There is no wasted text.

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 covers the essential delete-and-recover model for a mutation tool with an output schema. It still lacks permission requirements and the conditions under which recovery stops being possible, which matter for a destructive operation with no annotations.

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 the single required item_id, so the description should compensate. It only hints that the target may be 'a note or chunk', which adds some type context but does not explain the expected ID format or whether IDs are shared across both resource 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 states a specific verb ('Delete') and resource ('a note or chunk'), which is clearer than a bare name. It partially distinguishes itself from the sibling restore_version by noting recoverability, though it doesn't clarify the exact identity or type of the target item_id.

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?

Usage is implied: delete a note or chunk, and recover via restore_version. However, it doesn't explicitly say when to choose this over update_note or when deletion is inappropriate, leaving alternatives and exclusions to inference.

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. It implies a read ("Fetch") and says the full text and metadata come back, but says nothing about what happens when the id is missing, whether note ids and chunk ids share a namespace, or what access is required. For a lookup tool with zero annotation coverage, that is a real 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?

A single tight sentence with the verb, the resource, the selector, and the return payload all front-loaded. No filler to trim.

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?

An output schema exists, so return values need not be explained, and the description correctly stays brief on that. However, with no annotations and a 0%-covered schema, the agent still lacks the id-format and not-found semantics needed to call this reliably rather than falling back to search.

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 one parameter (item_id) with 0% schema description coverage. The description's 'by id' tells the agent what item_id is, which partly compensates, but it does not clarify the accepted id format or whether note and chunk ids are interchangeable.

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 verb and resource: fetch one note or chunk, by id, returning full text and metadata. That distinguishes it from the other retrieval siblings (search, list_versions) which return collections. It doesn't name a sibling explicitly, so it stops short of a 5.

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?

Usage is only implied: you call this when you already have an id and need the full payload. There is no explicit statement of when to prefer this over search, nor what to do when the id is unknown (i.e. search first). Nothing is misleading, but the agent must infer the routing.

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 does disclose the valuable incremental behavior (unchanged files skipped, changed files re-chunked). However, it never says that indexing writes state, what happens to files deleted from disk since the last run, which project/store is affected, or whether the operation is idempotent or costly.

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 tight sentences with zero filler and the core action front-loaded. Slightly dense clauses ('chunked by heading with file and line provenance') but every clause adds 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 two-parameter mutation-style tool with no annotations and no output schema, the description should cover the undocumented project parameter and say something about the result or scope of indexing. It covers the main path behavior well but leaves the second parameter and the effect of the operation unexplained.

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% for two parameters. The description clarifies that path is a directory root traversed for files, which is useful, but the project parameter is never mentioned at all, and there is no detail on path format, recursion depth, or how project scopes the index.

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 verb (Index) and resource (Markdown, text and reStructuredText files under path), plus the chunking strategy. It is unmistakably distinct from the note-oriented siblings like get, search, and add_note.

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?

Usage is implied by the name and the 'under path' phrasing, but there is no explicit when-to-use guidance, no prerequisites, and no statement about how this relates to the search/get tools that consume the index. An agent must infer the workflow.

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 disclose one genuinely useful trait: every write creates a version, so the list is effectively a write history. It omits ordering, pagination, permissions required, and whether the operation is read-only, all of which an agent would benefit from knowing.

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?

One short sentence with the resource and the key behavioral fact front-loaded, and the parenthetical adds real value rather than restating the name. Nothing extraneous.

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?

An output schema exists, so return values need not be described, and with zero parameters the description's burden is light. It is nearly complete, though it could note ordering (e.g., newest first) and how version identifiers connect to restore_version.

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 takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No parameter details are needed or missing.

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 verb and resource ('List the knowledge base's versions'), which is unambiguous. It doesn't explicitly contrast with siblings like get or restore_version, but the resource scope makes the purpose clear.

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?

Usage is only implied by the verb: an agent can infer this is the way to enumerate versions, presumably before calling restore_version. No explicit when-to-use or when-not-to-use guidance, and no mention of alternatives such as get.

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 real work: it discloses copy-on-write semantics ('a new version is written; history is kept'), telling the agent this is effectively non-destructive rather than an in-place overwrite. It does not cover permissions, whether the current version can be restored, or failure 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?

One sentence with the action front-loaded and the important side effect in a parenthetical. No filler, and nothing essential is buried.

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?

An output schema exists, so return values need not be explained, and the tool is a simple single-parameter mutation. The remaining gap is sourcing and validating the version argument, which the description leaves entirely to inference.

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% for the single 'version' parameter, so the description must compensate. It implies the parameter identifies an 'older version' to promote, but does not say whether it is a version number versus an ID, where to obtain it, or whether the current version is a valid input.

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 verb and resource: make an older version current again. An agent can tell this apart from list_versions, get, or delete without opening a schema. It does not explicitly name the sibling that lists versions to source the input from, which keeps it from a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'make an older version current again' implies the use case (rolling back to a prior state), but there is no explicit when-to-use/when-not guidance and no mention of siblings such as list_versions for discovering valid version numbers. Usage is inferred rather than stated.

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. It usefully discloses hybrid mode behavior (vector + keyword merged with RRF) and historical-version semantics, but omits read-only status, permissions, rate limits, and result-size 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?

Three sentences, front-loaded with purpose, then mode behavior, then filtering and versioning. Every sentence adds useful information; the only minor weakness is the slightly awkward line break in the mode sentence.

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 seven parameters, 0% schema description coverage, no annotations, and an output schema that covers return values, the description explains the complex parts (modes, filters, versioning) but omits 'k' semantics and safety/scope details. It is adequate but has clear gaps.

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 gives meaning to mode values, kind values ('note' or 'chunk'), tag/project filtering, and version semantics, but leaves 'k' and exact query behavior 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 description states a specific verb ('Search') and resources ('notes and document chunks'), and adds the mode dimension. It does not explicitly distinguish itself from the sibling 'get' tool, but the retrieval scope is clear.

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 explains how to filter and how to search historical versions ('Pass version... see list_versions'), but gives no guidance on when to use this search tool versus 'get', nor any explicit when-not conditions. Usage is implied rather than stated.

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 does disclose a genuine side effect ('re-embedded automatically'), which is real value beyond structured data, but it omits the critical mutation semantics: whether omitted/null fields leave values unchanged or clear them, whether tags are replaced or merged, and whether the update is reversible.

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 short sentences with zero filler, and the mutation scope is front-loaded before the side-effect note. Nothing could be cut without losing 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?

An output schema exists, so return values need no explanation, and the re-embedding note helps. But for a 5-parameter mutation with 0% schema coverage and no annotations, the description leaves the partial-update contract and the meaning of item_id unaddressed — an agent cannot call this confidently.

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 lists four field names that map loosely onto the schema, but adds no semantics — nothing on whether null means 'no change' or 'clear', nothing on tag replacement vs merge, and it never mentions item_id, the sole required 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 verb ('Change') and resource ('note') and enumerates the mutable fields (title, text, project, tags). It is clearly distinct from add_note/delete, though it never names a sibling or states the scope constraint that item_id identifies the target.

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?

'Change a note's ...' implies this is for modifying an already-existing note rather than creating one, which implicitly separates it from add_note. However there is no explicit when-to-use guidance, no mention of prerequisites (note must exist), and no routing to restore_version for reverting.

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