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

Annotations already flag destructive and idempotent, but the description adds real value beyond them: chunks and vectors are removed together, the effect is irreversible, and a selector is mandatory. It does not describe what happens to non-matching documents or any partial-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?

Three short sentences, front-loaded with what is deleted and how it is selected, then the side effect, then the hard constraint. 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 mutation tool with no output schema, annotations plus description cover safety (destructive/irreversible), scope (scoped selectors), and side effects (chunks/vectors). The main omission is the collection-wide 'all' path, which overlaps ambiguously with the sibling drop_collection.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters, making 3 the baseline. The prose names the selector kinds (id, exact uri, path prefix) but omits the collection default and the collection-wide 'all' flag, adding little beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb (Remove) plus resource (documents from a collection) and the three selector modes. It is clear this is a scoped document deletion, distinct from list_sources/list_collections, though it never contrasts itself with drop_collection or explains the collection-wide "all" mode the schema exposes.

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 precondition 'requires at least one selector' tells the agent how to invoke it validly, and 'irreversible' warns of consequence. However it gives no when-to-use vs. siblings (drop_collection for whole collections) and no guidance on choosing between id, uri, and prefix selectors.

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?

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds meaningful context beyond that: it stresses the operation is irreversible and enumerates what is destroyed (vectors, chunks, documents). It does not, however, mention auth requirements or confirm-gating behavior beyond the schema.

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 short sentences, front-loaded with the destructive action and its scope, followed by the irreversibility warning and the routing guidance. 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 destructive tool with no output schema and full annotation coverage, the description supplies everything needed: scope of deletion, irreversibility, and the alternative tool. Nothing an agent needs to call 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?

Schema description coverage is 100% and 'confirm' is already documented as needing to be true in the schema itself. The description adds no parameter-level detail, so the baseline 3 applies when the schema does the heavy lifting.

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 (delete) plus resource (entire collection) with explicit scope: 'all its vectors, chunks, and documents.' It names the sibling tool delete_sources as the contrasting option, so an agent can distinguish it without opening either 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?

Provides an explicit when-not-to-use rule: 'Prefer delete_sources when removing only some documents.' This routes the agent to the correct alternative based on a clear condition, leaving nothing 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, non-open-world). The description adds genuinely new behavioral context by disclosing what is returned: the full untruncated text and accompanying document metadata, which is not derivable from the annotations.

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 front-loaded sentence with no filler. The resource, the scope ('one chunk'), and the return content all land in one pass.

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 tool with no output schema, the description covers what is returned (untruncated text plus metadata) adequately. It omits any note about behavior when the id is invalid or missing, which 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 description coverage is 100% and there is only one parameter, so the schema fully documents chunk_id. The description's 'by its id' adds no syntax or format detail beyond that, making the baseline 3 appropriate.

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 (return/fetch) and resource (one chunk's full untruncated text plus document metadata), which is precise. It implicitly differentiates from the 'search' sibling by emphasizing 'full untruncated' text, but never names the alternative explicitly.

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 no explicit when-to-use statement; the usage is only implied by the schema note that chunk_id comes 'from a search result.' An agent can infer the lookup-after-search workflow but must do so itself.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered structurally. The description usefully discloses that it returns contiguous surrounding chunks rather than isolated fragments, but says nothing about budget truncation behavior (maxChars), pagination, or size limits.

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: purpose and addressing first, then the usage trigger. No filler, and the key routing information 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?

For a read-only expander with full schema coverage and annotations carrying the safety profile, the description covers what it returns and when to use it. It lacks output-format/pagination detail, but with no output schema that gap is minor.

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

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

Schema coverage is 100%, so baseline is 3. The description meaningfully adds that the hit can be addressed either by chunk_id OR by document_id + ordinal, which the schema lists as independent optional fields without stating they are alternative addressing modes.

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 (Return) and resource (contiguous chunks around a search hit) and clarifies the value: reading a whole function/section. It is clearly distinguishable from siblings like search (which finds fragments) and get_chunk.

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 after `search` when a result looks cut off" gives a clear trigger condition and sequences it relative to a sibling. It stops short of explicitly naming alternatives (e.g., get_chunk) or when not to use it, 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.

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

Annotations only cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false). The description goes well beyond them, disclosing content-hash skip semantics on re-run, .gitignore honoring, binary/oversized-file skipping, and language-aware chunking strategy. This is exactly the operational context an agent needs before invoking a bulk mutation.

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, zero filler, and the primary action is front-loaded before the safety and filtering behaviors. Every clause carries distinct 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 nine-parameter bulk mutation with no output schema, the description covers behavior and safety well. The only gap is what the call returns (e.g., counts of indexed/skipped/pruned files), which matters here since no output schema exists to fill that in.

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

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

Schema description coverage is 100%, so every one of the nine parameters is already documented in the schema. The description restates .gitignore honoring but adds no format, default, or interaction detail beyond the schema, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (index) and resource (files or directories) plus the destination (a vector collection) and outcome (semantic search). This is clearly distinguishable from the sibling index_text, which operates on raw text rather than paths.

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 context is implied by 'into a vector collection for semantic search,' but the description never says when to choose this over index_text or search, nor does it state prerequisites (index must exist, collection must exist). Guidance is present but inferential rather than 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?

Annotations already declare non-read-only, idempotent, non-destructive, closed-world. The description adds the key behavioral nuance the annotations cannot express: default replace:true deletes existing content for the same uri, while replace:false appends. That upsert-vs-append distinction is exactly the kind of context an agent needs.

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: the first establishes scope, the second delivers the replace/append rule. Nothing is redundant and the actionable guidance 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?

With no output schema and seven parameters, the description covers the purpose and the one parameter choice that materially changes behavior. It does not mention return values or interaction with collection/kind filtering, but nothing critical to a correct call 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 coverage is 100%, so the baseline is 3. The description goes slightly beyond the schema by framing replace:false as 'append a new version' and tying uri to stable replacement, clarifying intent rather than restating the field. Most parameter detail, however, still lives in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('index arbitrary text ... into a collection') and enumerates the content types it handles (notes, snippets, memory, logs), which implicitly separates it from index_paths. It never explicitly names the sibling it is not, so differentiation is inferred rather than stated.

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?

Gives clear operational guidance: reuse a stable uri to replace prior content, or pass replace:false to append a version. This tells the agent how to achieve both upsert and versioning. It stops short of saying when to prefer index_paths or search over 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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new context by enumerating what is returned (embedding model, dimensionality, document/chunk counts, on-disk size), which is valuable since no output schema exists. It omits any mention of ordering or behavior on an empty collection set.

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 front-loaded sentence with no filler; the resource comes first and the returned fields follow. Every clause 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 no output schema, the description must carry the return-value burden, and it does by naming the five fields the agent will receive. For a no-parameter, read-only listing tool with full annotation coverage, nothing needed to call 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 takes zero parameters, so the baseline is 4. There are no parameter semantics to clarify, and the description correctly spends no words on 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?

States a specific verb and resource ("List all vector collections") plus the exact attributes returned, so the agent knows this is a collection inventory rather than a search or stats call. It does not explicitly contrast itself with siblings such as list_sources or stats, 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 implicit rather than stated: a zero-parameter, read-only listing tool has an obvious call condition, and there is only one collection-listing sibling. However, there is no explicit when/when-not guidance or named alternative (e.g. use stats for aggregate metrics).

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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds only that results include chunk counts and sizes and are collection-scoped, which is modest added value beyond the structured fields.

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, no filler. The inventory purpose is front-loaded and the usage guidance follows immediately, with nothing that fails to earn 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 read-only listing tool with a fully documented schema and no output schema, the description supplies what the agent needs: what is listed, what comes back (chunk counts and sizes), and when to reach for it. Pagination is handled by the documented limit/offset parameters. Little 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 100% — limit, offset, uriPrefix and collection are all documented with defaults and constraints in the schema itself. The description adds nothing about parameter formats or interactions, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List documents already indexed in a collection') and adds the returned fields (chunk counts and sizes). It implicitly separates itself from list_collections and search by scoping to indexed documents, but never names a sibling to sharpen the distinction.

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?

Gives two concrete when-to-use scenarios and names the sibling tools they pair with: pre-search inventory ('before searching') and post-index verification ('confirm an index_paths run covered what you expected'). An agent can route to this tool without 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?

Annotations already declare this as read-only, idempotent, non-destructive, and closed-world. The description adds useful behavioral context: ranked output with cosine scores, file path, line range, truncation behavior, and the remedy of increasing limit or switching to get_context.

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 compact sentences, front-loaded with the core action and followed by return shape, filters, and truncation guidance. Every sentence contributes usable 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 ten-parameter semantic search tool with full schema coverage and annotations covering safety, the description is complete: it explains purpose, return values, filter scope, and what to do when results are truncated.

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

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

Schema description coverage is 100%, so all ten parameters are already documented in the schema. The description summarizes the filter categories (path prefix, exact path, language, content kind) and mentions limit, but it adds no syntax or default details beyond the structured fields.

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 precise verb and resource: 'Run a semantic similarity query against indexed content.' It distinguishes this from retrieval alternatives by naming get_context for follow-up context when results are truncated.

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 clear usage cue: increase limit or use get_context when results look truncated. It also notes available narrowing filters, but it does not explicitly contrast when to use this tool versus other sibling search/index tools beyond the truncation case.

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?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds value beyond that by disclosing exactly what information the call yields, which matters since there is no output schema, though it says nothing about cost, pagination, or failure modes (harmless for a zero-arg stat read).

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 returned-fields summary is front-loaded before the use case. Every clause 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 no output schema, the description carries the return-value burden and does so by enumerating the fields an agent gets back, plus the health-check use case. For a zero-parameter read tool with full annotation coverage, nothing needed to call 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 takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate and it correctly avoids inventing parameter detail.

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 ('Show') and enumerates the exact resources returned: database path, embedding model/provider, collection count, and totals. The scope is clearly server-level rather than collection-level, but it never names or contrasts itself with the overlapping sibling list_collections, so sibling differentiation is left to inference.

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?

Gives a concrete when-to-use context: verifying server health and the active model before diagnosing empty search results. That is a clear scenario, but no exclusions or explicit alternative tools (e.g., list_collections) are mentioned, so it stops 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.