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

With no annotations provided, the description carries the burden. It discloses that updates take effect immediately with no restart required, and that it returns the new config. However, it doesn't clarify whether changes persist across sessions or details about partial updates beyond 'specified keys'.

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

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

Two sentences, efficiently conveying both get and set modes. No wasted words.

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

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

Given the tool's simple nature, the description covers invocation, behavior, and return values. The schema fully documents parameters. It lacks error handling details, but overall complete for this 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?

Schema description coverage is 100%, and each parameter has its own description. The tool description merely lists the parameter names without adding extra meaning beyond the schema.

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

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

The description clearly states the tool reads or updates runtime configuration, listing the specific config keys. It distinguishes itself from file/search tools in the sibling list by being the only configuration tool.

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

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

It provides explicit usage modes: without arguments it returns current config, with arguments it updates specified keys. This gives clear context for when to invoke it, though it doesn't mention when not to use it or alternatives (none needed).

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 full burden. It discloses the computational approach (computing content hashes for every chunk) and the output format (file pairs sorted by similarity), but does not explicitly state whether the operation is read-only or mention potential performance impact.

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: two sentences covering purpose, method, output, and use case. Every sentence delivers 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 simplicity (one parameter, no output schema), the description is fairly complete. It explains the return format at a high level and provides usage guidance. A minor gap is the lack of an explicit statement that the operation is read-only, but the description is otherwise sufficient.

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

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

The schema already provides a detailed description of the threshold parameter, including meaning, default, and range. The tool description adds no additional parameter semantics beyond what the schema provides, so the baseline score of 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?

The description clearly states the tool detects near-duplicate documents using content hashes and returns file pairs with high chunk overlap. It is specific about the verb (detect) and resource (documents in the index), and distinguishes itself from sibling tools like ingest_file or query_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 provides a clear use case: 'Use to identify accidentally duplicated or re-ingested content.' While it doesn't explicitly mention when not to use it or name alternatives, the context is sufficient given the tool's unique niche among siblings.

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

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

No annotations are provided, so the description carries the full burden. It discloses return values (deleted, removedChunks, existed) and the conditional requirement, which goes beyond the schema. It does not explicitly state irreversibility, but the term 'delete' implies it, and chunk removal is mentioned.

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 three sentences, front-loaded with the action, and every sentence adds value. It is concise without sacrificing important details like return values and parameter selection.

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 moderate complexity of the tool, the description covers the essential decision (filePath vs source), the required parameter constraint, and the return values. It lacks edge-case details like what happens if both parameters are provided, but this is minor given the overall clarity.

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%, but the description adds critical semantic context by mapping parameters to ingestion methods and clarifying the 'either/or' requirement. This goes beyond the schema's examples and helps the agent choose correctly.

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

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

The description clearly states the tool deletes a previously ingested file or data from the vector database, using specific verbs and resource. It distinguishes itself from sibling tools like ingest_file and query_documents, as deletion is a unique operation.

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

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

Explicitly explains when to use each parameter: filePath for files ingested via ingest_file, source for data ingested via ingest_data. It also states that either must be provided, guiding the agent on parameter selection.

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

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

With no annotations, the description carries the burden of disclosure. It reveals that the tool returns the export file path and stats (document count, chunk count, file size), and that the output is importable later. It does not mention potential side effects, but the operation is clearly non-destructive and the return information adds useful 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?

The description is two sentences, front-loaded with the core purpose. Every sentence adds value: purpose, return stats, and future importability. No unnecessary 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?

For a simple tool with one optional parameter and no output schema, the description is nearly complete. It states purpose, return values, and use case. It could mention behavior if the output file already exists, but that is a minor gap.

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

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

Schema description coverage is 100% because outputPath has a detailed description with default behavior. The tool description does not add extra meaning beyond the schema, but the schema itself is sufficient, so the baseline score of 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?

The description clearly states the tool's function: 'Export the current index to a JSON file for backup or migration.' This specifies the verb (export), resource (current index), and output (JSON file), distinguishing it from sibling tools like ingest_file, query_documents, and delete_file.

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

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

The description provides clear use cases ('for backup or migration') and notes the exported file can be re-imported with a future import_index tool. While it does not explicitly name alternatives or when-not-to-use, the context is sufficient for an agent to decide when to invoke 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?

With no annotations, the description carries the full burden. It discloses the internal mechanism (AST-level metadata), provides the return format, and states a key limitation (requires CodeChunker). For a read/search operation, this is transparent enough, though it does not explicitly mention error conditions or confirm it is non-mutating.

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 three concise sentences: it front-loads the core action, then adds the mechanism, and finally the return shape and constraint. Every sentence earns its place with no redundancy or filler.

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

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

For a simple one-parameter tool with no output schema, the description is complete. It provides the return structure, the search domain, and the prerequisite condition (CodeChunker ingestion). An agent has enough to select and invoke the tool correctly.

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

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

The description does not add parameter-specific information beyond the schema. The schema already fully documents symbolName with case-sensitivity and an example. With 100% schema coverage, the baseline score of 3 is appropriate; no additional parameter details are necessary.

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: 'Find where a symbol (function, class, variable, etc.) is defined in code files.' It specifies the resource (code files) and the search domain (AST-level entity metadata). This distinguishes it from sibling tools like find_references, which would focus on usages rather than definitions.

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 usage context is implied: use when you need to locate a definition. It gives an important constraint ('Only works for code files that were ingested with AST-level chunking') but does not explicitly compare to alternatives like find_references or say when not to use this tool. This is adequate but not explicit.

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

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

With no annotations provided, the description carries the full burden and excels: it details the two-phase search strategy, merge order, deduplication key, output structure, and a prerequisite condition. This goes beyond a typical description and provides rich behavioral detail.

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, with four sentences that are all informative. It front-loads the main action, then provides algorithm, return shape, and constraints 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?

The description covers the return structure (mitigating no output schema), explains the algorithm, and states a prerequisite. It could optionally mention possible referenceType values or error behavior, but these are not essential for usage.

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?

Both parameters (symbolName, limit) are fully described in the input schema, including semantics ('exact match in imports; substring match in text mentions') and limits (default 10, range 1-50). The description adds no new parameter semantics beyond the schema, so it does not exceed the schema's coverage.

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

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

The description clearly states 'Find all references to a symbol across ingested code files', which is a specific verb+resource+scope. It distinguishes from sibling find_definition by using 'references' rather than 'definition'.

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 a clear usage context ('across ingested code files') and a prerequisite (AST-level chunking), but it does not explicitly mention alternatives or when not to use it. Usage is implied by the purpose rather than explicitly compared to sibling tools like find_definition.

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 what is checked (model loaded, DB readable, dirs reachable, cache writable) and the return format (structured pass/fail with summary and fix suggestions). It doesn't state whether the operation is read-only, but the content implies a non-mutating diagnostic. This is good coverage for a health check.

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

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

Two sentences: the first states the high-level purpose, the second details specific checks and output format. Every sentence adds value, and it is front-loaded with the verb 'Diagnose'. Extremely concise.

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

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

For a parameterless tool with no output schema, the description is remarkably complete. It explains the checks performed, the return type, and even mentions fix suggestions. There is no ambiguity about what the tool does or returns.

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

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

The tool has zero parameters, so the schema provides all the needed information. The description correctly avoids adding parameter syntax since none exist. Baseline 4 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?

The description clearly states it diagnoses server health and configuration, enumerating specific checks (embedder, LanceDB, BASE_DIRs, cache). It doesn't explicitly differentiate from the sibling 'status' tool, but the verb 'diagnose' and listed components make 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 implied: use when needing to diagnose server health. No explicit when/when-not or alternatives are mentioned, such as comparing with 'status' for system-level checks. The description provides context but lacks exclusion guidance.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It reveals a key behavioral trait—re-ingestion with the same source identifier updates existing content—and specifies the return shape. While it does not mention auth, permissions, or side effects, it covers the main behavioral consequences for the typical use case.

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

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

The description is two sentences long and front-loaded with the tool's core purpose. It efficiently packs the alternative tool reference, the re-ingestion behavior, and the return value into a compact, well-structured format with zero 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?

Given the tool has 2 parameters (one nested), no annotations, and no output schema, the description provides a complete picture: what it does, when to use it, how the source identifier behaves, and what it returns. It lacks explicit error scenarios or prerequisites, but these are not critical for a simple ingestion tool. The return value statement covers the output side.

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 50% (content and format described in schema, metadata partially). The description adds significant value by explaining the 'source' identifier protocol with examples (e.g., 'clipboard://2024-12-30', 'chat://2024-12-30/project-discussion'), which is essential for correct invocation. This compensates well for the moderate schema coverage.

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

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

The description uses the specific verb 'Ingest' and clearly specifies the resource: 'in-memory content as a string'. It further distinguishes itself from a sibling tool by explicitly pointing to 'ingest_file' for disk files, 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 explicitly states when to use this tool (in-memory string content) and when not to (files on disk, via 'use ingest_file for files on disk'). This provides clear alternatives and context for selection.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses recursion, chunking strategies (AST-level for code, semantic for documents), and return value structure (per-file status plus totals). It does not cover edge cases like error handling or overwrite behavior, but the provided details are substantial.

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

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

The description is two sentences: the first front-loads the action and scope, the second provides usage guidance. Every sentence earns its place with no fluff or repetition.

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

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

Given the tool's moderate complexity (2 params, no output schema, no annotations), the description covers purpose, usage timing, and return values. It is sufficiently complete for an agent to select and invoke the tool correctly, though it could mention whether ingestion overwrites existing documents.

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

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

The input schema already provides 100% coverage with descriptions for both parameters (path and extensionFilter), including examples. The description adds no additional parameter semantics beyond what the schema already contains, so a baseline score of 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 the tool's function with a specific verb and resource: 'Batch ingest all supported files in a directory.' It also adds detail about recursive scanning and file types, distinguishing it from sibling tools like ingest_file (single file) and ingest_data.

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

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

The description explicitly states when to use the tool: 'Use this for initial bulk ingestion or after deleting the database.' However, it does not name alternatives or provide when-not-to-use guidance, which would warrant a 5.

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

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

With no annotations provided, the description carries the burden of disclosing behavior. It explicitly states that re-ingesting replaces existing data, revealing a destructive side effect, and also specifies the return object structure. It does not cover other potential behaviors like long-running VLM processing, but the key destructive behavior is disclosed.

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

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

Two sentences with zero waste. First sentence front-loads action and resource, second sentence covers constraints and return value. Highly scannable and efficient.

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

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

Given no output schema and no annotations, the description covers essential operational context: supported file types, absolute path requirement, replacement behavior, and return format. It lacks explicit separation from sibling ingest tools (ingest_data, ingest_directory) but otherwise provides a complete picture for a single-file ingestion 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?

Schema coverage is 100%, so baseline is 3. The description adds value by listing allowed file extensions (PDF, DOCX, TXT, MD) for filePath, which the schema does not specify. It also clarifies replacement semantics tied to the file path. It does not add extra detail for visual or visualQuality beyond what the schema provides, so a slight uplift 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 specifies the verb 'Ingest' and resource 'document file (PDF, DOCX, TXT, MD) into the vector database'. It implicitly distinguishes itself from sibling tools like ingest_directory by focusing on a single document file with an absolute path, and from ingest_data by specifying file formats.

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

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

The description states clear context: use for ingesting a document file, path must be absolute, and re-ingesting the same path replaces existing data. It does not explicitly name alternatives or exclusions, but the singular 'file' and mention of supported extensions imply single-file use, differentiating from ingest_directory.

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

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

With no annotations, the description carries the burden and does well by stating the tool operates on configured base directories, supported file types, and returns a specific structure including a distinction between file scan and ingest_data sources. It does not discuss permissions or pagination, but these are less critical for a listing operation.

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

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

The description is two sentences, front-loaded with the core action, and concise. It avoids redundancy with the schema and every part 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?

The description plus schema is sufficiently complete: it clarifies the return object and sources concept, and parameters are fully described. It doesn't elaborate on file object fields or empty states, but these are not essential for a listing 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?

Schema coverage is 100%, with both parameters already well-documented in the schema. The tool description adds no additional parameter semantics beyond what is in the schema, so the baseline of 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 the tool lists supported files (PDF, DOCX, TXT, MD) and their ingestion status, with a specific verb and resource. It also distinguishes the return structure, making its purpose distinct from sibling tools like query_documents or ingest_file.

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 explicit when-to-use or alternative tools are mentioned. However, the description implies its use for inspecting file inventory and ingestion status, and the mention of sources vs. files gives some context. It does not state when to prefer it over query_documents or status.

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

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

With no annotations, the description carries the burden of disclosing behavior. It adds value by specifying the return shape (filePath, chunkIndex, text, fileTitle, score) and clarifying score semantics (0 = best, higher = worse) and the source field for ingest_data items. It does not discuss errors or permissions, but for a read-only search tool, this is sufficient.

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

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

The description is two concise sentences: the first states the action, the second lists the result fields and score behavior. Every word earns its place, with no redundancy or filler.

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

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

Despite having 8 parameters and no output schema, the description covers the key missing piece—the return value structure—along with the non-obvious score ordering. The schema already provides exhaustive parameter details, so the description plus schema form a complete picture for an agent to invoke this tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not elaborate on individual parameters; it only mentions hybrid matching, which is already reflected in searchMode. Since the schema fully documents all parameters, the description adds no extra semantic value for params, but it does not need to.

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

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

The description opens with a specific verb and resource: 'Search ingested documents with hybrid keyword + semantic matching.' It clearly distinguishes this tool from siblings like delete_file, ingest_file, and list_files, and even from find_definition/find_references by emphasizing general hybrid search rather than specific symbol lookup.

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

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

The description states the tool's core function and that it returns relevance-sorted results, giving implied context for when to use it. However, it does not explicitly contrast it with siblings such as find_definition or find_references, nor does it state when to prefer one over another, so usage guidance remains implicit 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?

With no annotations, the description carries the full burden for behavioral disclosure. It thoroughly explains return behavior: target chunk (isTarget: true), neighbors ascending by chunkIndex, out-of-range returns [], and defaults (before=2, after=2, max 50 each). This goes well beyond basic descriptions and covers edge cases and ordering.

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 three sentences, directly front-loaded with the main purpose. Each sentence earns its place: purpose, parameter usage, and return behavior. No filler or redundancy.

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

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

Despite lacking an output schema, the description fully explains the return structure: target chunk, neighbors, ordering, and edge-case behavior. It also sets expectations for defaults and limits, making it complete for a moderate-complexity read 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?

Schema coverage is 100%, so the baseline is 3. The description adds significant context beyond the schema: it explicitly ties chunkIndex to a query_documents result, emphasizes the exclusivity of filePath vs source, and reiterates defaults and maximums. This enriches the parameter semantics meaningfully.

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

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

The description clearly states a specific action: 'Read the chunks immediately before and after a query_documents result, in the same document.' This distinguishes it from query_documents (which retrieves results) and other tools by focusing on neighboring chunks. The verb 'read' and resource 'chunks' are explicit and specific.

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

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

The description gives explicit usage guidance by instructing to 'Pass chunkIndex from the result plus exactly one of filePath (ingest_file) or source (ingest_data).' This contextualizes the tool as a follow-up to query_documents. However, it does not explicitly compare to alternatives or state when not to use it, so it falls just short of a 5.

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

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

No annotations are provided, so the description carries full burden. It explicitly discloses destructive behavior: 'Delete existing chunks' and 'slow, destructive operation.' This goes beyond vague warnings and gives concrete behavioral details, making the tool's impact 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 two sentences: the first states the action and method, the second covers use cases and a warning with an alternative. Every phrase adds value, and the destructive nature 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 the operation is destructive and potentially slow, the description covers what it does, when to use it, why, the alternative, and a warning. No output schema is present, but the core selection and invocation context is fully addressed, making it complete for an agent.

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% and the only parameter optimizeAfter already has a clear description in its schema. The tool description does not add parameter-level context, so the baseline of 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?

The opening line 'Re-ingest ALL indexed files from scratch' states a specific verb and resource, and the description explicitly contrasts with reindex_stale ('prefer reindex_stale for routine updates'), distinguishing it from sibling tools. It clearly names the operation and 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 gives explicit when-to-use conditions ('after changing the embedding model, chunker parameters, or when the index is corrupted') and provides a direct alternative with an exclusion ('prefer reindex_stale for routine updates'). This is exactly the guidance needed for selection.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals the detection method (mtime comparison) and the return value (count of stale files re-ingested), which goes beyond a generic restatement. It could mention potential side effects or state changes more explicitly, but overall it provides meaningful insight into the tool's behavior.

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

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

The description is two sentences, front-loaded with the core action, followed by the return value and usage guidance. Every sentence earns its place with no redundancy or fluff, making it highly concise and well-structured.

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 tool with no parameters, no annotations, and no output schema, the description covers the what (re-ingests changed files), the when (index out of date), the mechanism (mtime), and the expected response (count). This is fully adequate for an agent to select and invoke the tool confidently, especially given the sibling tool context.

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

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

The tool has zero parameters, and the schema is empty, so the baseline is 4. The description doesn't need to explain parameters; it correctly focuses on the tool's operation and output, adding no irrelevant parameter details.

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 specific action (re-ingest), the target resource (files with changed disk contents), and the detection mechanism (mtime comparison). This distinguishes it from siblings like reindex_all, which likely re-ingests everything, and ingest_file, which targets a specific file.

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

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

The description explicitly provides a use case: 'Use when you know files have been modified but the index is out of date.' This gives clear context for when to invoke the tool. It does not explicitly mention alternative tools or exclusionary conditions, but the guidance is sufficient for an agent to make an informed choice.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It conveys read-only intent via 'Get' and describes output formatting (MB, s) and per-instance behavior, but does not mention error cases, auth requirements, or data safety. The disclosed behavior is useful but not exhaustive.

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

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

The description is two sentences, front-loaded with the core purpose and output fields. The conditional instance guidance is concise and both sentences add value with no filler.

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

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

For a simple status tool with one optional parameter and no output schema, the description covers the key returned fields and instance behavior. It is mostly complete, though it could mention the relationship to health_check, but this is not strictly necessary for a standalone status 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?

The schema describes the 'instance' parameter fully, and the description adds context about when to use it (multiple instances). Since schema coverage is 100%, the baseline of 3 applies; the description slightly reinforces but does not significantly add beyond the schema.

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

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

The description clearly states 'Get index status' with a specific list of returned fields, indicating a read-only status operation. It does not explicitly differentiate from sibling tools like health_check, but the verb+resource combination 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?

The description provides conditional usage guidance: 'When multiple instances are configured, pass instance name for per-instance status.' It does not explicitly state when to use this tool over alternatives like health_check, so usage context is implied rather than fully explicit.

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