Alcove

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

The description clearly explains that the tool only reports findings and scans two locations, suggesting actions but not executing them. It also includes an important caution about not exposing raw internal docs. However, without annotations, it could be more explicit about being read-only, though the description implies it.

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

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

The description is well-structured with clear sections and bullet points, but it is slightly verbose. Every sentence adds value, and the main purpose is front-loaded. A minor trim could achieve a 5.

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 parameters and no output schema, the description fully explains the tool's purpose, usage, behavior, and caveats. There is no missing information for an agent to understand 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?

There are no parameters, so the schema provides full coverage. The description adds significant meaning by detailing the two scan locations and the tool's reporting nature, which is valuable 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 audits documentation health across two specific locations (alcove doc-repo and project repo). It uses a specific verb 'audit' and resource 'documentation health', and distinguishes from sibling tools like init_project and configure_project by noting it only reports findings.

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 (when user wants to know missing/outdated/misplaced docs) with example queries. It also provides guidance on what not to do (never suggest exposing raw internal docs) and directs the agent to always ask the user before proceeding with init_project or configure_project.

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?

Since no annotations are provided, the description carries the full burden of behavioral disclosure. It clearly explains the tool runs git commands, automatically initializes a git repo if missing, and returns a 'no_changes' status instead of an error when there are no changes. This adequately informs the agent of side effects 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 exceptionally concise, with the main purpose stated in the first sentence. Subsequent details are logically organized: use case, behavior with vs without parameter, auto-init, and no-change response. Every sentence adds 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 has no output schema, the description fully compensates by detailing return behavior (including the 'no_changes' status), git operations, and initialization logic. This covers all essential aspects a developer or AI agent would need to 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?

Schema coverage is 100% as the only parameter 'vault_name' is documented. The description adds value by explaining the effect of omitting the parameter (backs up all vaults), which goes beyond the schema description that merely states 'omit to back up all vaults.' This provides actionable insight.

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 'Create a git commit snapshot of a vault's current state,' which clearly specifies the verb ('create snapshot'), resource ('vault'), and mechanism ('git commit'). This distinguishes it from sibling tools like 'audit_project' or 'check_doc_changes' which serve 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?

The description explicitly states when to use this tool: 'when the user asks to back up, sync, or save the current state.' It also explains the behavior for vault_name provided vs omitted, guiding usage. However, it does not mention when not to use it or list alternatives.

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

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

Describes the comparison mechanism, return format (grouped by status), and the effect of auto_rebuild. Discloses that without auto_rebuild it is read-only with no side effects. No contradictions.

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

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

Concise, well-structured sentences. No wasted words; each sentence adds value. Front-loaded with purpose, followed by usage, mechanism, return, and parameter details.

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?

Completely describes what the tool does, when to use, mechanism, return value, and parameter behavior. Adequate for a single-parameter tool with no output 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?

Input schema has 100% coverage with a clear description. The description adds usage context for the auto_rebuild parameter, justifying a score above 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 checks for added, modified, or deleted documentation files since the last index build. It uses a specific verb and resource, and distinguishes from siblings like rebuild_index and search_project_docs.

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 says to use before search_project_docs to ensure index freshness or when user asks about changes. Also states it is safe without auto_rebuild, providing clear when-to-use and safety 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 full burden. It discloses that the tool is a create-or-update operation that only modifies specified fields, leaving others intact. However, it does not mention potential side effects like file locking, authorization requirements, or error conditions. For a configuration tool, this is adequate 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 consists of four concise sentences, each providing essential information: what the tool does, what settings can be overridden, the partial update behavior, and the prerequisite. There is no redundant or extraneous content, and the structure front-loads the core purpose.

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 a configuration tool with 5 parameters and no output schema, the description covers purpose, usage, and parameter overview. However, it does not indicate what the tool returns (e.g., success/failure confirmation), which is a gap that could hinder the agent's understanding of the tool's outcome.

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

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

The input schema already has high description coverage (100%) for all parameters, providing clear definitions. The description adds an overview of parameter categories but does not introduce new semantic nuances beyond what is in the schema. Therefore, the value added is minimal, and 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 verb 'Create or update' and the resource 'per-project settings in alcove.toml', specifying the fields that can be overridden. It distinguishes from the sibling tool 'init_project' by explicitly requiring it as a prerequisite, ensuring the agent knows when to use which.

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 when-to-use guidance and a clear precondition: 'Run init_project first if the project does not yet exist.' It also explains partial updates: 'Only the fields you specify are changed; unmentioned settings are preserved.' This helps the agent decide when and how to invoke the tool correctly.

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 exist, so the description fully covers behavioral traits: declares read-only with 'no side effects,' explains chunking behavior, and documents error conditions (file not found or path out of bounds).

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 (5 sentences) with no filler. Purpose is front-loaded, usage guidance follows, and technical details are efficiently presented. Every sentence adds value.

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

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

For a tool with 3 parameters and no output schema, the description covers all essential aspects: purpose, when to use, parameter semantics, chunking, and error handling. The agent has sufficient information to 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?

Schema coverage is 100% with good descriptions, but the description adds crucial context: explains that offset is character-based, describes default behaviors, and clarifies the omit-to-read-entire-file pattern, going beyond what the schema provides.

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 a clear verb+resource: 'Read the full content of a specific documentation file by its relative path.' It distinguishes itself from siblings like search_project_docs and get_project_docs_overview by focusing on reading a known 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?

Explicitly states when to use: 'when you know the exact file to read' and provides a typical workflow after using other tools. Also addresses large file handling with offset/limit, giving clear guidance on chunking.

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 provided, so description carries full burden. It fully discloses behavior: scans two locations, classification labels, empty list return, and read-only nature. No contradictions.

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

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

Well-structured and concise: first sentence states purpose, then usage advice, then details about locations and classifications. Front-loaded with key information; 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?

Covers all needed information: purpose, when to use, where it scans, classification labels, edge case (empty list), and reference to related tool. No missing details given lack of output 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?

There are no parameters, so schema coverage is 100%. Baseline for 0 params is 4. The description adds no parameter info, 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?

Clearly states it lists documentation files with sizes and classification labels. The verb 'List' and resource 'documentation files for the current project' are precise, and the description distinguishes from siblings like get_doc_file and init_project.

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 advises to call this tool first when the user asks about docs or wants a summary. It notes it is read-only with no side effects. While it does not explicitly list when not to use it, it provides clear guidance.

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

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

Even without annotations, the description fully discloses behavior: it creates files in specific locations, handles missing docs automatically, and respects the overwrite parameter. No contradictions or hidden effects are implied.

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, using three sentences that efficiently convey the tool's purpose, customization options, and behavior. Every sentence adds 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?

The description covers the main functionality, customization via parameters, and conditional behavior. It lacks details about return values or error handling, but given the tool's complexity and lack of output schema, it is largely complete for an initialization 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%, but the description adds meaningful context beyond the schema: it explains the dual purpose of project_path (external docs) and that omitting 'files' triggers creation of all missing internal required docs. This adds value above the baseline 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 initializes documentation for a new project using templates, specifying internal (PRD, Architecture) and external (README, CHANGELOG, QUICKSTART) docs. This distinguishes it from sibling tools like lint or validate.

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 context: when project_path is given, external docs are also created; the 'files' parameter selects specific documents; without 'files', all missing internal required docs are created. However, it does not explicitly mention when not to use this tool or suggest alternatives.

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

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

Although no annotations are provided, the description clearly conveys that the tool is read-only (linting) and lists the checks performed. It does not explicitly state that it does not modify files, but the context implies analysis. It could be improved by confirming no side effects.

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: first sentence states purpose, followed by usage context, then a bullet list of checks, and finally the optional parameter. Every sentence adds value, and the information is front-loaded.

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

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

Given there is no output schema, the description adequately explains what the tool returns (checks with type) and covers all necessary aspects: purpose, when to use, what it checks, and parameter usage. It is complete for a lint 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 provides full coverage (100%) for the single parameter 'project'. The description adds value by explaining the effect of omitting the parameter (scans all projects), which goes beyond the schema's description. Hence, above 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 defines the tool's purpose: linting project documentation for semantic issues. It lists specific check types (broken links, orphan files, stale markers, stale dates) which distinguishes it from sibling tools like audit_project or validate_docs that focus on other aspects.

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 (e.g., check doc quality, find broken links, audit hygiene) and mentions the optional project filter. However, it lacks explicit when-not-to-use guidance or alternatives, which would make it 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 fully discloses behavior: read-only, no side effects, no parameters, returns array of project names, empty array if no projects, case-sensitive. This is comprehensive.

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 structured with a purpose statement, bullet list of use cases, and behavioral details. Every sentence is meaningful, and it is concise with no 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 simple list tool with no parameters and no output schema, the description is fully complete: it explains what is returned, the source, case sensitivity, and empty case behavior.

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

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

The input schema has no parameters, and the description confirms 'Does not require any parameters.' Since schema coverage is 100% trivially, the description adds value by clarifying the lack of parameters. Baseline 4 for 0-parameter tools.

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 'List all projects that have documentation stored in the alcove doc-repo', providing a specific verb and resource. It distinguishes from sibling tools by focusing on listing vs. other operations like search, init, etc.

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 lists four explicit scenarios when to use the tool, such as verifying project existence before calling get_project_docs_overview, and mentions using it before scope='global' search. It provides clear when-to-use and alternatives 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?

No annotations are provided, so the description carries full burden. It implies a read operation but does not disclose potential behaviors like authentication needs, rate limits, or pagination. For a simple list operation, the transparency is adequate but not rich.

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 sentence, front-loaded with the verb and resource. It is concise and contains no extraneous 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 simplicity of the tool (no parameters, no output schema, no annotations), the description is largely complete. It explains the scope 'all' and the inclusion of document counts. Missing details like sorting or pagination are acceptable for a basic list all 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?

Schema description coverage is 100% with zero parameters. The description does not need to add parameter info. It does not provide any additional meaning beyond the schema, which is empty.

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 a specific verb 'List' and a clear resource 'knowledge base vaults', and adds 'with their document counts' for extra detail. It clearly distinguishes from sibling tools like backup_vault or search_vault 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?

It states that it lists all vaults, providing clear context for when to use. However, it does not explicitly mention when not to use or contrast with alternatives like search_vault for searching within vaults.

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?

Discloses auto-detection of project, fallback to inbox, and copy vs move behavior. No annotations exist, so description carries full burden. It provides sufficient transparency beyond simple mutation.

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

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

Four succinct sentences: purpose, usage, auto-detection, copy/move default. Front-loaded with no redundant 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?

Covers key behaviors and parameters. Lacks output specification, but for a simple import tool this is acceptable. Could hint at return value (e.g., confirmation path).

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 description adds meaning: copy default true, project auto-detected, source absolute path. Each parameter gets extra context beyond schema 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 clearly states the tool's purpose: 'Promote a document from an external vault (e.g. Obsidian) into the alcove doc-repo.' This distinguishes it from sibling tools like get_doc_file or search_vault, which deal with internal 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?

Explicitly says 'Use this tool when the user wants to import, migrate, or copy a file from outside alcove.' Provides context but does not explicitly list when not to use or alternative tools.

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?

Discloses key behavior: returns immediately without blocking, and search results reflect changes after completion. No annotations provided, so description carries burden; it does so well for a simple async 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?

Three concise sentences, each providing essential information: action, blocking behavior, usage trigger, and effect. No superfluous text.

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?

Covers purpose, when to use, and async behavior. Lacks mention of idempotency or error conditions, but given simplicity and absence of output schema, completeness is adequate.

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?

No parameters exist; schema coverage is 100%. Description adds no parameter info, which is acceptable for a tool with zero inputs. Baseline score of 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 'Trigger an incremental index update' with a specific verb and resource. It distinguishes itself from sibling tools like search_project_docs or list_projects by focusing on background indexing.

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 says 'Run this after adding or updating documents,' providing clear usage context. Omits mention of when not to use or alternatives, but the sibling set does not offer a similar rebuild 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?

No annotations are provided, so the description carries the full burden. It discloses automatic BM25 fallback to grep and scope behavior. However, it doesn't describe what the output looks like (e.g., file names, snippets) or mention any rate limits or auth requirements, which would enhance transparency.

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

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

The description is well-structured with bullet points for scope guidance, and the main purpose is front-loaded. While every sentence adds value, it could be slightly more streamlined. Overall, it's appropriately sized and clear.

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

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

Given no output schema and 4 parameters, the description thoroughly explains search behavior and scope usage. It does not describe the return format or what happens with no results, but for a search tool, it covers the essential aspects 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 100%, and the description adds significant value beyond the schema: it explains the default scope derived from CWD, provides concrete examples of when to use each scope (including Korean), and clarifies the mode parameter's effect (skipping BM25 index).

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 searches documentation files for a keyword/phrase, specifying two search mechanisms (BM25 ranked and grep) and two scopes (project and global). It distinguishes itself from sibling tools like 'search_vault' by targeting project docs specifically.

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

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

Provides explicit and actionable guidance on when to use global vs project scope, including specific user language examples (e.g., 'all projects', 'everywhere', Korean phrases). It also implies default behavior for project scope. Though it doesn't mention alternatives like 'search_vault', the sibling list makes the differentiation clear.

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 provided, so description must carry burden. It does not mention any side effects, authentication needs, or rate limits. However, as a search tool, it is likely read-only and safe. A mention of read-only nature would improve transparency.

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, no redundancy. The first sentence states purpose, the second adds usage context. Efficient 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?

Given 3 parameters, all described in schema, and no output schema, the description is sufficient. It provides the key context of separation from project documentation. Could mention return format but not critical.

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 baseline is 3. Description adds context on usage but does not elaborate on parameter semantics beyond what schema already provides (limit, query, vault). Adequate but no added value for parameter understanding.

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?

Clearly states action (search), resource (knowledge base vaults), and distinguishes from project documentation by explicitly saying 'separate from project documentation', which helps differentiate from sibling tool search_project_docs.

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?

Tells when to use: for research notes, reference materials, curated knowledge bases. Implicitly says not to use for project documentation. Also mentions option to search all vaults by omitting vault parameter or using '*', providing clear 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?

Despite no annotations, description discloses read-only nature, checks performed, and fallback behavior for missing policy. Only minor omission is potential scope of doc scanning, but overall 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?

Description is structured front-loaded with purpose and usage, then detailed checks and return. Sentences are efficient, though slightly verbose but not excessive.

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, description covers key aspects: purpose, usage, checks, and return format. Slight gap in exact output structure, but sufficient for agent understanding.

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?

Input schema has no parameters (0 params), so baseline is 4. Description adds context about validation without needing 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 verb 'validate' and the resource 'current project's documentation against policy.toml'. It distinguishes from siblings like lint_project by emphasizing policy compliance checks.

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 says when to use: 'user asks to check doc quality, run a policy check, or verify docs before a release'. Also advises use of configure_project if policy missing, providing clear guidance.

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