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 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 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 full burden. It discloses the return structure ({ baseDirs, files, sources }), explains that sources lists non-file ingested items, and the scope parameter details behavior for relative/out-of-base prefixes. It does not explicitly state read-only intent or mention recursion depth/sorting, but for a list tool the essentials are covered. Edge cases for scope are thoroughly 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?

The description is two sentences: first states the core function and return object, second clarifies what 'sources' contains. No filler, front-loaded with the verb 'List'. The parameter schema is detailed but that is separate. The main description earns its place.

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

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

For a list tool with no output schema, the description explains the return object and the meaning of sources. The scope parameter covers traversal/filtering behavior. It could additionally disclose recursion depth or permission requirements, but these are less critical for a read-only list operation. Overall, sufficiently complete 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?

Schema coverage is 100% for the single optional parameter 'scope', and its description is detailed (absolute path, prefix matching, union for arrays, behavior for relative/out-of-base). The tool description adds no extra parameter semantics beyond the schema. Per guidelines, high schema coverage yields a baseline of 3, which 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 what the tool does: 'List supported files (PDF, DOCX, TXT, MD) under the configured base directories and whether each is ingested.' This is a specific verb+resource combination with scope (supported extensions, base directories, ingestion status). It distinguishes from siblings: query_documents and status focus on querying, ingest_* on adding content, delete_file on removal. The tool is unambiguously the file-listing utility.

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: use this when you need to see files and their ingestion status, and it notes that sources include non-file ingest_data content (web pages, clipboard). The scope parameter description adds clear guidance about absolute path prefixes and how to interpret empty results (compare against baseDirs). However, it does not explicitly contrast with alternative tools such as query_documents or status, nor state when not to use it.

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

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

With no annotations, the description carries the full burden, and it does disclose non-obvious behavior: result ordering is authoritative over score, score is lower-is-closer, source is only populated for ingest_data items, and multiple heading paths signal a cross-section chunk. It omits any statement of read-only safety, rate limits, or empty-result behavior, keeping it below a 5.

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?

Front-loaded with the core purpose, then dense but load-bearing detail about result fields and sourceContext semantics. Every sentence carries information, though the back half packs several distinct facts into long clauses that 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?

There is no output schema, and the description compensates well by enumerating the return fields (filePath, chunkIndex, text, fileTitle, score, source) and explaining sourceContext. With no annotations, it should also cover the read-only nature and any scope-omission fallback, which it leaves implicit.

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 schema already documents query, limit, and scope thoroughly (including the absolute-path prefix rule). The description's detail is almost entirely about returned fields, not input parameters, so it adds little beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ('Search ingested documents') and specifies the retrieval mechanism ('hybrid keyword + semantic matching'), so the agent knows exactly what capability this is. It does not name or contrast any sibling (e.g. read_chunk_neighbors or list_files), so it falls short of the sibling-differentiating 5.

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

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

Provides real guidance on interpreting output ('use the returned order as the ranking; score may disagree with it') and on query construction, which implies the tool's role. However, it never says when to prefer this over siblings like read_chunk_neighbors or list_files, and gives no exclusions or prerequisites, so usage is only implied.

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 present, the description carries the full behavioral burden and does so: it discloses the return shape (target chunk flagged isTarget: true plus neighbors, ascending by chunkIndex), the edge case (out-of-range chunkIndex returns []), and the defaults/limits (before=2, after=2, max 50 each). Optional sourceContext is explained, including that multiple heading paths signal a section-crossing chunk.

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?

Front-loaded with purpose, then how to call it, then return behavior, then the optional sourceContext detail, then defaults. Every sentence contributes, though it is a dense single block rather than cleanly separated clauses.

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?

No output schema exists, so the description must explain returns, and it does (target + neighbors, ordering, empty result). Combined with the documented defaults, limits, and input constraints, an agent has everything needed to call this correctly against a 5-parameter schema.

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 already 100%, so the baseline is 3. The description adds genuine meaning beyond the schema by stating that chunkIndex originates from a query_documents result and by restating the mutual-exclusion rule for filePath/source, plus the semantics of sourceContext's heading paths.

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

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

States a specific verb and resource (read the chunks immediately before/after a query_documents result) and ties itself directly to the sibling query_documents, so an agent can distinguish it from a plain search. The scope constraint 'in the same document' further narrows what it returns.

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?

Explains the triggering context clearly: use it after a query_documents result when you need more surrounding context, and it names the exact input to carry over (chunkIndex plus one of filePath/source). It gives no explicit 'when not to use it' or alternative (e.g., re-running query_documents with a wider window), so it stops 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 must carry the burden of behavioral disclosure. It communicates the output fields and implies a read-only operation via 'Get', but it does not explicitly state safety, side effects, or any operational conditions. The field list adds context, but some behavioral aspects remain implicit.

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, front-loaded sentence that immediately states the tool's purpose and then lists the output fields in a structured way. There is no redundancy or 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?

For a simple status tool with no parameters and no output schema, the description adequately covers the return values and purpose. It does not mention potential delays or whether the status is a snapshot, but for its simplicity, the information provided is sufficient for basic 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?

The tool has no parameters and an empty input schema, so parameter semantics are not needed. The description adds value by enumerating the output fields, which helps the agent understand what to expect, thus justifying a baseline score of 4.

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 (Get) and resource (index status), and the listed field names specify exactly what the tool returns. This distinguishes it from sibling tools like query_documents or sync_status, which 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?

No guidance is given on when to use this tool versus alternatives such as sync_status, which may also report on index state. There is no mention of exclusions or typical use cases, leaving the agent to infer 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?

No annotations are provided, so the description carries the full burden. It discloses side effects (index updates/removals), non-blocking execution, job retention, and process-exit loss. It also clarifies the behavior regarding visual profiles and STORE_IMAGES, ensuring the agent understands the tool's operational nuances.

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 overly verbose and repetitive. Phrases like 'visual profile' and 'only one job is kept' are repeated, and the whole text could be condensed to a few sentences without losing meaning. The single-paragraph structure lacks scannable clarity, and the redundancy detracts from conciseness.

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 operational aspects: return value, polling mechanism, job limitations, and process-exit behavior. It is slightly incomplete regarding error cases or permission requirements, but given the moderate complexity and the absence of an output schema, it provides sufficient context 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?

The schema description for 'path' is already highly detailed, covering optionality, file/directory semantics, baseDirs, and omission behavior. The tool description repeats this verbatim without adding new semantic information, so the value beyond the schema is minimal, resulting in the baseline score of 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 clearly states the tool's purpose: 'Reconcile the index with the files on disk: ingest new and changed files, leave unchanged files alone, and remove index entries for files that are gone.' It also specifies the non-blocking return of a jobId, making the tool's primary function 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?

Explicitly mentions alternatives and complementary tools: 'use the CLI (mcp-local-rag sync --visual) to set one, or ingest_file to replace the file' and 'poll sync_status with that jobId'. Also clarifies scope behavior and omission of path to sync all base directories, providing clear guidance on when and how to use the 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 clearly states the return shape (jobId, state, total, completed, summary, warnings, error) and explains null/unknown meanings. It does not mention side effects, but 'Get' implies a read-only operation, and no side effects are likely. The level of detail is strong for a status 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 longer than a typical one-liner, but it is dense and structured with the return object in braces, using spaces and parentheses for clarity. Every sentence adds value, though it could be slightly trimmed without loss. It is front-loaded with the core action.

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 single-parameter status tool with no output schema, the description is remarkably complete. It details all possible state values, null semantics, and the meaning of an unknown jobId. There is no obvious missing behavior; the tool's functionality is fully 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 schema covers jobId with 'Identifier returned by sync_start.' The description adds meaning by explaining that an unknown jobId indicates replacement/loss, and by showing jobId in the return structure. This goes beyond the schema's basic parameter comment.

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 starts with 'Get the current or latest sync job record' — a specific verb and resource. It clearly distinguishes itself from siblings like sync_start (which creates a job) and status (which likely relates to something else) by focusing on sync job state retrieval.

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 intended context: to poll or inspect a previously started sync job. It does not explicitly name alternatives, but the mention of 'unknown jobId means the job was replaced by a newer one or lost with a previous server process' gives practical guidance on interpreting results, which helps decide when this tool is useful.

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