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

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses that the collection is 'automatically opened and cached for subsequent operations', which is useful behavioral context. It also mentions the return value is a success or error message. No contradictions with 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?

The description is concise, well-organized with a brief summary, Args section, Returns, and Examples. It is front-loaded and every sentence provides useful information without unnecessary fluff.

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 complexity of the tool (many nested parameter types), the description covers purpose, usage, parameter roles, side effect (auto-open and caching), return value, and examples. It is complete enough for an agent to correctly invoke the tool.

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

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

Although the schema has detailed descriptions, the description's Args section adds context like 'unique session key' for collection_name and 'min 1' for vector_fields. With schema coverage reported as 0%, the description compensates by summarizing parameter roles and constraints, adding value beyond the schema.

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

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

The description explicitly states 'Create a new Zvec collection and open it for use', which is a specific verb-resource pairing. It distinguishes from siblings like 'open_collection' by noting this tool creates and automatically opens, while 'open_collection' is for existing collections.

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 includes explicit guidance: 'Use this when you need to initialize a new vector database' and 'Don't use when: Collection already exists (use open_collection instead)'. It provides examples for when to use and when not, making it clear for the agent.

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?

The description discloses that the tool creates an index, which is consistent with readOnlyHint=false. It mentions that the index accelerates queries. However, it does not specify what happens if the index already exists (overwrite? error?) or any prerequisites like required permissions or collection existence. Given the annotations provide little additional context, the description could be more transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear purpose statement, conditional usage guidelines, an Args section, and examples. It avoids unnecessary repetition. Slightly longer than necessary but each sentence contributes value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the main variants (vector vs scalar indexes) and mentions the return type. However, it does not address important contextual aspects such as whether the index creation is idempotent, what happens on failure, or prerequisites like requiring an existing collection and field. Given the tool's complexity, this information would be useful for an agent to invoke 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 input schema already contains descriptions for all parameters (collection_name, field_name, index_param with sub-schemas). The description adds minimal extra semantics by providing examples and stating the tool uses validated input parameters. Schema description coverage is high due to the detailed schema, so the description's added value is marginal.

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

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

The description clearly states the tool's purpose: 'Create an index on a field to accelerate queries.' It uses a specific verb-resource pair and distinguishes itself from siblings like 'drop_index' and 'destroy_collection' by focusing on creation of indexes. The mention of different index types (HNSW, Flat, IVF, Invert) further clarifies the scope.

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

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

The description provides explicit guidance on when to use each index parameter type: HnswIndexParamInput/FlatIndexParamInput/IVFIndexParamInput for vector fields and InvertIndexParamInput for scalar fields. However, it lacks explicit guidance on when not to use this tool (e.g., if an index already exists or if the collection doesn't exist), so it's not 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?

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds that it returns a deletion count or error message, but does not elaborate on side effects like whether deletion is hard/soft, permissions required, or impact on related 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 relatively concise with a clear opening sentence. However, the docstring-style Args/Returns adds slight verbosity. It is well-structured and 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?

Given the destructive nature, the description covers the return type but lacks details on error handling, validation failures, or partial success scenarios. The schema covers input completeness but behavior is minimally described.

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 redundantly lists the same parameters already documented in the input schema (collection_name, document_ids). With schema descriptions present for both fields, the description adds no new meaning; it only restates them.

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

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

The description clearly states the action ('Delete') and resource ('documents by their IDs'). It distinguishes from sibling tools like insert, fetch, update, etc., which perform different operations. The purpose is immediately 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?

No guidance is provided on when to use this tool vs alternatives such as update_documents or upsert_documents. The description does not mention prerequisites, error conditions, or scenarios where deletion is appropriate.

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 provide destructiveHint: true and readOnlyHint: false. The description goes beyond by explicitly stating 'This operation is irreversible. All data will be permanently lost.' This adds critical context about the permanence and impact, matching the annotations without contradiction.

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 (4 sentences) and front-loaded with the purpose. The Args section is somewhat redundant with the schema but still clear. The warning is appropriately placed. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the annotations and output schema (returning a string), the description covers the core intent, irreversibility, parameter, and return. Minor gaps: does not specify that the collection must exist or handle error cases, but these are not critical for a delete operation with 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?

Schema coverage is 0% (description does not describe params; schema only lists 'collection_name' with minimal description). The description's Args section calls 'collection_name' a 'Collection identifier,' adding some semantic meaning but not enough to compensate for the lack of param details in the schema.

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

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

The description clearly states the tool's primary function: 'Permanently delete a collection from disk.' The verb 'delete' and resource 'collection' are specific. The tool is distinct from siblings like 'delete_documents' (deletes documents, not collection) and 'drop_index' (drops index).

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 includes a warning about irreversibility, implying permanent deletion. However, it does not explicitly state when to use this tool versus alternatives (e.g., 'drop_index' for indexes) or provide guidance on prerequisites like ensuring the collection is not in use.

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 indicate destructiveHint=true and idempotentHint=true, so the description adds little beyond disclosing the return format (success or error message). It does not elaborate on behavioral aspects like idempotency behavior (e.g., dropping a non-existent index) or potential side effects on collections.

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 concise, consisting of one sentence explaining the tool's purpose followed by a structured parameter list and return type. Every sentence adds value, and the key action 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?

Given that this is a destructive tool (annotations show destructiveHint=true) with sibling tools like 'create_index' and 'destroy_collection', the description is insufficient. It omits important context such as whether the index must exist, the behavior if it doesn't, and the exact format of the return string. The presence of an output schema is not leveraged to explain return values.

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 merely rephrases the schema's parameter descriptions ('Collection identifier', 'Name of the indexed field') without adding constraints, examples, or format details. With schema description coverage at 0%, the description fails to compensate by providing meaningful semantic enrichment.

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

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

The description clearly states the tool's function: 'Remove the index from a field.' This provides a specific verb and resource, distinguishing it from sibling tools like 'create_index' (which creates an index) and 'destroy_collection' (which removes entire collections).

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

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

There is no explicit guidance on when to use this tool versus alternatives like 'create_index' or 'destroy_collection'. The description does not mention prerequisites, such as the need for the collection to be open or the index to exist, nor does it suggest alternative actions.

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 the tool as read-only, non-destructive, idempotent, and open-world. The description adds valuable behavioral details: it uses OpenAI embeddings via environment variables, infers embedding dimension from the schema, and returns results sorted by similarity. This goes beyond annotations but does not cover error specifics or rate 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?

The description is concise and well-structured: it opens with a one-sentence summary of the core functionality, then provides process details, environment setup, parameter overview, and return value. Every sentence adds diagnostic value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity, the description covers the essential workflow, prerequisites (env vars), input parameters, and return type. It lacks explicit error handling details, but the output schema exists and the description mentions error returns, making it sufficiently complete for an agent to use 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 input schema has parameter descriptions, but the top-level schema description coverage is 0%. The tool description compensates by explaining the embedding process, environment variable requirements, and the overall workflow, adding meaning beyond the schema for critical parameters like 'query_text' and 'field_name'.

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 converts a natural language query to a vector and performs similarity search. It distinguishes itself from sibling tools like 'vector_query' and 'generate_dense_embedding' by labeling itself as the 'high-level search interface', making its role and scope immediately 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?

The description positions this tool as the 'high-level search interface' for natural language queries, implying it should be used for general semantic search. However, it does not explicitly state when to avoid it or mention specific alternatives among siblings like 'multi_vector_query' or 'vector_query', leaving some ambiguity.

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

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

The description discloses the use of OpenAI for embedding, environment variables, and automatic dimension inference, adding context beyond the annotations. Annotations already indicate non-destructive (destructiveHint=false) and readOnlyHint=false, and the description does not contradict them. It could further mention potential overwrite on upsert.

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 (4 sentences), front-loaded with the main action, and includes an Args/Returns section. However, the Args section largely duplicates schema information, slightly reducing efficiency.

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, the description covers core aspects: action, embedding mechanism, environment configuration, and return message. An output schema exists, reducing need for detailed return documentation. Leaves out error handling and performance considerations.

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's properties already have descriptions covering all parameters (collection_name, field_name, documents, and their sub-properties). The description adds marginal value by summarizing the OpenAI connection and dimension inference, but the schema provides the bulk of parameter semantics. 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?

The description uses specific verbs ('embed' and 'upsert') and identifies the resource ('Zvec collection'), clearly distinguishing it from sibling tools like 'generate_dense_embedding' which only creates embeddings, and 'upsert_documents' which likely does not auto-embed.

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

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

The description implies it is the high-level write interface but does not explicitly state when to use this tool versus alternatives like 'generate_dense_embedding' or 'insert_documents'. No when-not-to-use or exclusion criteria are provided.

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, destructiveHint, idempotentHint. Description adds only response format detail; does not explain error behavior for missing IDs.

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?

Description is fairly concise at 10 lines with clear Args/Returns structure, though could be more front-loaded and less redundant.

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?

Lacks mention of error cases, collection openness (openWorldHint=false), or handling of missing IDs; adequate for a simple fetch but incomplete for robustness.

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?

Description lists params but largely repeats schema descriptions; adds no new semantics beyond what schema provides. Baseline score due to schema 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?

Description states 'Retrieve documents by their IDs' – a specific verb+resource that clearly differentiates from sibling search tools like embedding_search and vector_query.

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

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

No guidance on when to use this tool versus alternatives; it does not mention direct ID lookup vs search nor any preconditions.

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 indicate readOnlyHint=true, idempotentHint=true, and openWorldHint=true, so the safety profile is clear. The description adds return format details (JSON with preview, model, dimension, vector) but does not disclose behavioral traits like rate limits, cost implications, or fallback behavior when env vars are missing, which would be valuable given the reliance on an external API.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with an opening sentence stating the purpose, followed by an Args list and return type. It is appropriately sized for the complexity of the tool, though the bullet list could be slightly more concise. No redundant information is present.

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 provides a complete picture of the tool's behavior: what it does, how to use it (parameters with defaults and env var fallbacks), and what it returns (JSON with specific fields). No output schema is provided, so the description compensates fully. The tool is simple and the description covers all necessary information 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?

Despite schema description coverage being 0% (schema has descriptions for each parameter), the tool description adds meaningful context beyond the schema by summarizing each parameter with defaults and env var fallback (e.g., 'api_key: OpenAI API key (or OPENAI_API_KEY env var)'). This helps an agent understand the parameter semantics without inspecting the schema.

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

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

The description clearly states the tool generates a dense embedding vector from text using OpenAIDenseEmbedding, with explicit mention of converting text into a fixed-length vector for similarity search. This distinct purpose is well differentiated from sibling tools like embedding_search or vector_query, which use embeddings rather than generate them.

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

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

The description implies use for generating embeddings for similarity search but does not explicitly state when to use this tool versus alternatives like embedding_search or vector_query. No exclusion criteria or comparison to siblings is provided, leaving the agent to infer usage without clear 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?

Annotations already declare readOnlyHint=true, so the description adds value by specifying what information is retrieved (schema, stats, config) and that the collection must be opened. No negative behaviors hidden.

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 reasonably concise at around 70 words, with a clear front-loaded purpose. The inclusion of args and returns is helpful, though it could be slightly tighter.

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 existence of an output schema, the description adequately covers the tool's behavior: it requires an opened collection and returns formatted info. It does not detail the structure of the returned info, but output schema fills that 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?

The input schema already provides clear descriptions for both parameters (collection name and response format). The description adds minimal extra meaning beyond confirming they are validated.

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 retrieves detailed information about an opened collection, specifying schema, statistics, and configuration. It distinguishes well from sibling tools that perform mutations or searches.

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

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

The description implies usage for inspecting collection details but does not explicitly state when to use this over alternatives like open_collection or when not to use it. No exclusions or context provided.

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 indicate this is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds specific mutation behavior: insertion with uniqueness constraint, failure on duplicate ID, and return of success message with count or error. This provides useful context beyond 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?

The description is concise, front-loaded with purpose, and includes structured Args/Returns sections. It avoids verbosity, though the Args section partially duplicates schema information. Still efficient and clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has a single parameter (nested) and an output schema, the description covers the essentials: purpose, constraints, input structure, output type (string with success/error). It explains the failure case but does not detail validation or side effects beyond annotations. Adequate for its complexity.

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 repeats parameter names (collection_name, documents) and document fields (id, vectors, fields) from the schema, but adds minimal new meaning. The schema already provides detailed descriptions for each property, so the description adds no new semantics. Baseline 3 is 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?

The description clearly states 'Insert new documents into a collection.' and specifies constraints: 'Documents must have unique IDs and conform to the collection schema. This operation fails if a document with the same ID already exists.' This distinguishes it from siblings like upsert_documents or update_documents.

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

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

The description implies usage for inserting new documents with unique IDs, but does not explicitly state when to avoid this tool or suggest alternatives such as upsert_documents or update_documents. Given sibling tools, more explicit guidance would improve differentiation.

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=true, destructiveHint=false, idempotentHint=true. The description adds context about the search and fusion process, explaining that results are re-ranked and returned, without contradicting annotations. It discloses the return format and that no side effects occur.

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?

Well-structured with sections for Args, Returns, Examples, and Re-ranking Strategies. Every sentence is informative and concise, avoiding redundancy. The length is appropriate for the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (multi-vector fusion, two re-ranking methods), the description covers all necessary aspects: input parameters, output format, use cases, and strategy comparisons. The output schema exists, so no need to detail return structure further. Complete and self-contained.

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 thoroughly explains the 'params' argument, breaking down each sub-field (collection_name, vectors, topk, topn, reranker_type, weights, rank_constant, metric_type, filter, response_format) with examples and rationale for re-ranking strategies. This adds significant value beyond the input schema's own descriptions.

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

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

The title and first sentence clearly state the tool performs multi-vector similarity search with score fusion and re-ranking. It distinguishes itself from single-vector search (vector_query) by specifying multiple embeddings, and from embedding_search by mentioning fusion and re-ranking.

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 explicit 'Use when' examples (e.g., 'Search using both dense and sparse embeddings') and compares re-ranking strategies (Weighted vs. RRF) with guidance on when to choose each. This helps the agent decide between this tool and alternatives.

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 indicate idempotentHint=true and readOnlyHint=false, so the tool is idempotent and may involve state changes. The description adds behavioral context: caching for subsequent operations, prerequisite that the collection was created with create_and_open, and that it returns success/error messages. It does not contradict annotations, which is good, and provides additional detail beyond 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?

The description is concise and well-structured: a brief intro, clearly labeled Args and Returns sections, and concise examples. Every sentence serves a purpose with no redundant information, achieving a high signal-to-noise ratio.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (open an existing collection) and the presence of an output schema, the description is complete. It covers the prerequisite, caching behavior, and error conditions, leaving no significant gaps for an AI agent to understand what the tool does and how to use it 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?

Although the input schema already has descriptions for each property (e.g., 'path', 'collection_name', 'read_only'), the description adds value by summarizing the parameters contextually and giving example usage. However, since schema coverage is effectively high (descriptions exist in schema), the description's contribution is moderate but helpful.

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 'Open an existing Zvec collection from disk,' specifying the verb (open) and resource (existing Zvec collection). It distinguishes from sibling tool create_and_open_collection by emphasizing 'existing' and referencing the creation tool, making the purpose unambiguous.

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

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

The description provides explicit usage instructions with 'Use when' and 'Don't use when' examples, including a direct alternative mention: 'Don't use when: Collection doesn't exist (use create_and_open_collection).' This gives clear context for when to invoke this tool versus alternatives.

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 indicate idempotency and non-destructiveness. The description adds specific behavioral details (merge segments, rebuild index) and return type, but does not mention concurrency or locks.

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 core purpose, and organized with Args and Returns sections. No unnecessary 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 tool with one parameter and an output schema, the description covers the operation's effect, input, and return value sufficiently. No 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?

Despite context signals showing 0% schema description coverage, the tool description clearly documents the required parameter collection_name with its meaning. This compensates fully.

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 it optimizes collections (merge segments, rebuild index) to improve performance and reduce storage, distinguishing it from creation/deletion tools among 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 implies optimization for better performance but lacks explicit guidance on when to use vs. alternatives or when not to use it. No comparison to sibling tools is provided.

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?

Adds beyond annotations: 'Only specified fields are updated; others remain unchanged' and 'Documents must already exist.' Consistent with idempotentHint=true. No contradictions.

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?

Well-structured with clear sections, no fluff. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given output schema (success/error message), description adequately covers input and behavior. However, could better contrast with sibling tools.

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 0% schema coverage, the description provides detailed Args section explaining each parameter (collection_name, documents) and nested DocumentInput fields (id, vectors, fields). Adds significant 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?

Description clearly states 'Update existing documents by ID' and explains partial update behavior. Differentiates from siblings like insert_documents and delete_documents.

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?

Mentions documents must exist, implying not for creation, but lacks explicit guidance on when to update versus upsert or insert. No direct comparison with alternatives.

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?

The description explains the upsert logic (insert if missing, update if exists) and mentions return type (success message with count). Annotations only provide idempotentHint, so the description adds behavioral detail beyond 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 concise (two paragraphs plus parameter listing) and front-loaded with the core operation. Every sentence serves a purpose, though the parameter listing could be more compact.

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 basic operation and return type, but lacks details on error scenarios, default values, or limitations. Given the presence of an output schema (not shown) and rich input schema, it is minimally adequate but could be more 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?

The description restates parameter names and types from the schema without adding new meaning. Since schema descriptions are already detailed (e.g., DocumentInput fields), the tool description offers minimal additional semantic value.

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

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

The description clearly states the tool's purpose with specific verb and resource: 'Insert new documents or update existing ones by ID.' This distinguishes it from sibling tools like insert_documents and update_documents.

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 does not provide guidance on when to use upsert versus insert or update, nor does it mention prerequisites or exclusions. It only describes the combined behavior, leaving the agent to infer usage context.

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 indicate read-only, non-destructive, idempotent. The description adds context about returning sorted results or errors, and specifies constraints like topk max=1000. No contradictions.

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?

Well-organized with clear sections (purpose, args, returns, examples). Front-loaded with main action. Every sentence contributes meaning without fluff.

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?

Explains main functionality and parameters well, but lacks details on the exact structure of returned search results (e.g., whether it includes scores or metadata). Adequate for a similarity search tool with good schema and 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 input schema already has descriptions for all nested properties, so baseline is 3. The description adds value by providing filter syntax examples and clarifying the purpose of each parameter in context, but it largely replicates schema info.

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 'Perform vector similarity search with optional filtering' with a specific verb and resource. It distinguishes itself from siblings like multi_vector_query by focusing on single-vector search with filters.

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 explicit use cases (e.g., 'Find the 10 most similar documents') and filter syntax examples. However, it does not mention when not to use it or compare to alternative sibling tools like multi_vector_query.

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