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

With no annotations, the description carries full behavioral burden. It discloses background indexing, immediate return with file count, model download, absolute path requirement, glob matching semantics, supported file types, silent ignoring of unsupported types, and partial-search behavior during indexing. This is exceptional coverage.

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 about 120 words yet packed with essential details: purpose, usage timing, background behavior, glob semantics, supported types, return shape, and concurrency. It is front-loaded with purpose and avoids redundancy, earning every sentence.

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

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

Given the complexity (background indexing, globs, model download), the description covers prerequisites, return shape, edge cases (unsupported files silently ignored, partial search results), and the follow-up tool (index_status). No critical gap remains.

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%, but the description explains each parameter: path must be absolute and existing; include_globs/exclude_globs are illustrated with examples and matching rules (relative to folder, forward slashes). This fully compensates for the schema's lack of 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 description states a specific verb+resource: 'Register a local folder so its documents become searchable.' This clearly distinguishes it from siblings like remove_folder and reindex, and conveys the intended outcome immediately.

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 explicitly says 'Use this once per folder before searching it,' and directs the user to 'call index_status to track progress.' It also notes the first index downloads a ~130 MB model, providing valuable context for when this tool 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?

With no annotations provided, the description fully bears the burden of behavioral disclosure. It explains that similarity uses stored embeddings (whole-file centroid vs. best-matching chunks), works even if the model is not loaded, returns cosine similarity scores and previews, and errors if the file has no stored embeddings. This is rich, honest transparency about inner workings and edge cases.

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-organized into a brief overview, usage hint, technical mechanism, and return format, all within a few sentences. No fluff—each sentence adds value, from the purpose to the error condition. It is front-loaded with the most important 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?

Given the moderate complexity and presence of an output schema, the description does a strong job: it explains the return format, score meaning, preview semantics, and error conditions. It only misses the 'top_k' parameter explanation and could optionally mention that the result list is ordered by score. Overall, it is nearly complete but missing one key param detail.

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

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

The schema has 2 parameters with 0% description coverage, so the description must compensate. It adequately explains the required 'path' parameter ('must be a file inside a registered folder that has already been indexed'). However, the optional 'top_k' parameter is not mentioned at all, leaving the agent to guess its meaning. The description covers only half the parameters, earning a 3.

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+resource: 'Find indexed documents most similar in meaning to a given file.' It further clarifies the use case with examples like 'related notes, duplicate content' and explicitly distinguishes from sibling tools such as search by framing it as 'more like this.' This is a clear, purpose-focused 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 provides explicit usage context: 'Use for "more like this"' and lists concrete examples. It also states a prerequisite ('path must be a file inside a registered folder that has already been indexed'). However, it does not explicitly state when not to use it or mention alternatives like search for keyword queries, 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?

With no annotations, the description carries full disclosure burden. It details the entire return object structure, explains the embedding.status field and its error/not-loaded meanings, and mentions the limit of 10 failed files. This provides substantial behavioral context beyond a minimal 'get status' description.

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

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

The description is well-structured: a one-line summary, then usage guidance, then return format. It is a bit long due to detailed return spec, but every sentence adds value, though slightly redundant given an output schema exists. Still, it remains concise 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?

For a read-only status tool with no parameters, the description covers purpose, usage timing, return structure, and error interpretation. It even addresses diagnostic use cases and performance cost. This is fully sufficient for an agent to correctly select and 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?

The tool has zero parameters, so the baseline is 4. The description doesn't need to explain parameters, and the input schema is empty. No gaps to compensate for, so the score matches the baseline.

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 reports index health and background indexing progress. It also provides specific usage scenarios (after add_folder/reindex and for diagnosing incomplete search results), which distinguishes it from sibling tools like search or reindex that have different purposes.

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

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

Explicitly instructs when to use the tool: 'Use after add_folder or reindex to check whether indexing has finished, or to diagnose why search results look incomplete'. Also notes it's 'Cheap to call', setting expectations for frequent use. This is direct guidance on appropriate contexts.

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 responsibility. It goes beyond a simple verb phrase by disclosing the exact return structure: 'Returns {ok, folders: [{path, files, failed_files, chunks, added_at, last_indexed_at}, ...]}.' This gives the agent a precise expectation of what the tool outputs, which is especially valuable since the input schema is empty and there is no other source of behavioral information.

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: two sentences, with the core action first and the return format following. Every sentence adds value, including the usage guidance, and there is 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 having no parameters and a trivial input schema, the description covers purpose, use cases, and return format. It gives sufficient context for an agent to decide when to invoke it and what to expect, without requiring additional details like permissions or side effects since it is a read-only list operation.

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

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

The tool has zero parameters, so there is nothing to explain. Per the rubric, 0 parameters gets a baseline score of 4, and the description adds no parameter-specific semantics because none are needed.

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 registered folders with file/chunk counts and last index time. This specifically distinguishes it from sibling tools like search, add_folder, and remove_folder, making the purpose immediately obvious.

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?

Explicit usage guidance is provided: 'Use this to check what is searchable before calling search, or to find the exact registered path for remove_folder.' This directly tells the agent when to use this tool and ties it to related actions, covering both use cases and implicitly ruling out use for search or removal itself.

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

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

With no annotations, the description fully carries the safety and behavior disclosure. It reveals that paths outside registered folders are refused, distinguishes plain-text vs binary extraction, explains 1-based inclusive line ranges, caps output at ~100k characters with a 'truncated' flag, and lists the return structure.

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 a single, well-organized paragraph with front-loaded purpose. Every sentence adds distinct value (usage, safety, format handling, parameters, output limits, return fields) with 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?

For a read_file tool with an output schema, the description covers the full workflow (after search), all parameter behaviors, format differences, output cap, and return shape. It is complete enough for an agent to invoke correctly without external documentation.

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% and the description compensates richly. It defines path constraints (must be in a registered folder), explains start_line/end_line as 1-based and inclusive, says to omit both for the whole file, and clarifies the truncation behavior for the line range.

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 'Read the text of one indexed document, optionally a line range,' a specific verb plus object. It distinguishes from siblings by positioning the tool as the follow-up to search, pulling full context around a hit.

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 'Use after search to pull full context around a hit,' giving a clear when-to-use. It does not explicitly enumerate when-not-to-use or name alternatives, but the positioning relative to search and the registered-folder constraint provide sufficient 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?

With no annotations, the description carries the full burden. It discloses key behaviors: background execution, incremental default with mtime/content hash skipping, purging of deleted files, folder limiting, force rebuild semantics, and the return value. This is comprehensive and exceeds the minimum.

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 and appropriately sized. The opening sentence states the core purpose, followed by contextual usage, parameter explanations, and return value information. Every sentence earns its place with no 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?

The description covers trigger conditions, change detection behavior, folder scoping, force usage, and return format. Even though an output schema exists, the added return value description is helpful. It is complete for a background maintenance 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 0%, so the description must compensate. It fully explains both parameters: 'folder' limits to a registered folder (path as shown by list_folders), and 'force=true' rebuilds every file from scratch. This adds meaning beyond the raw 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 function: 'Refresh the index: pick up new, changed, and deleted files.' It uses a specific verb and resource, and the scope is explicit, distinguishing it from sibling tools like index_status (status) and list_folders (listing).

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

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

The description explicitly says when to use the tool: 'Use when documents changed on disk since they were indexed.' It also references index_status for tracking and explains the folder/force options. However, it does not explicitly state when not to use it or name alternative tools for the same action, 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?

With no annotations, the description takes full responsibility for disclosing behavior. It states that all index data (files, chunks, search index) is purged, that on-disk documents are untouched, and that in-progress background indexing is cancelled. It also provides the return tuple. This is exemplary disclosure for a mutating tool.

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

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

The description is three sentences, with the main action in the first sentence and essential clarifications in the second and third. Every sentence contributes useful information and there is no fluff. The structure loads the primary purpose first and then adds nuance, making it easy for an agent to parse.

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 (not shown in detail), the description covers the core behavior, side effects, and return value. It does not address error handling or idempotency, but given the tool's simplicity and the existence of an output schema, the description is reasonably complete. A small gap is the lack of any note about the folder needing to be registered, but that is implied by 'Unregister'.

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 only parameter, 'path', has no schema description (0% coverage) and the tool description does not elaborate on the expected format, whether it must be absolute, or whether it needs to match the exact path used in add_folder. The description only uses the word 'folder', which is nearly synonymous with 'path'. Thus it provides no added 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 opens with a specific verb phrase 'Unregister a folder and purge all its index data' and enumerates exactly what is purged (files, chunks, search index). It also clarifies the non-destructive effect on disk data, which distinguishes it from a delete operation. The tool name alone would be ambiguous, but the description eliminates that.

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 the tool is for removing a folder from the index, and explicitly points to list_folders for listing registered folders, giving context. It also warns that on-disk documents are untouched, which tells the agent not to use this tool if physical deletion is intended. However, it does not explicitly name alternatives like reindex or add_folder for comparison, so it stops short of full 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?

With no annotations, the description fully carries the transparency burden. It discloses the return format, score normalization (0-1), mode degradation via the `note` field, snippet highlighting with **bold**, and references `read_file` for full context. This gives the agent a clear model of what to expect and how to act.

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

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

The description is front-loaded with the core purpose, then organized into logical sections: usage guidance, parameter explanations, and return value details. Every sentence carries meaningful information, 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?

This is a complex tool with 5 parameters, no annotations, and no schema descriptions. The description covers all parameters, explains return structure and edge cases (degradation note), and provides a next-step pointer (read_file). It is fully self-contained for correct invocation.

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

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

Schema coverage is 0%, so the description compensates completely. It explains `query` behavior in each mode, `top_k` range (1-50), `folder` source (path from list_folders), `file_type` extension, and `mode` with three values and defaults. No parameter is left unclear.

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+resource phrase: 'Search all indexed documents and return the most relevant passages.' It also includes scope ('all indexed documents') and a usage cue ('Use this first whenever the user asks about the content of their local documents') that distinguishes it from sibling tools like find_similar.

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 explicitly states when to use this tool ('Use this first whenever the user asks about the content of their local documents') and provides detailed mode selection guidance: 'best for most queries', 'best for identifiers or rare exact words', and 'best when wording differs'. This is clear and actionable.

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