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

Annotations already declare readOnlyHint and idempotentHint, so the tool is known to be safe and repeatable. The description adds useful behavioral context: it returns a summary inline, full details via a resource URI, and warns that file paths are server-internal. It does not contradict annotations, though it omits mention of auto_reindex's potential side effect, which is acceptable given its presence in the schema.

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, front-loaded with the core purpose, and each sentence provides valuable information: the operation, the output summary, and a critical usage caveat about paths. There is no redundancy or 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?

For a simple tool with one optional parameter, the description covers the essential output behavior and provides a pointer to full details. The schema handles parameter documentation, and annotations cover safety, so the description completes the picture without needing an 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?

The description does not describe the auto_reindex parameter, but the input schema already provides a complete description ('Auto re-index if stale (default: true)') with 100% coverage. Per the rubric, a high schema coverage yields a baseline of 3, and the description adds no additional parameter meaning.

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

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

The description clearly states the tool's function: 'Find duplicate code (verified via graph isomorphism).' This distinguishes it from sibling tools like write, edit, and suppress, which have unrelated purposes. The title reinforces this, and the mention of graph isomorphism adds specificity.

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 use case (duplicate code analysis) and provides guidance on how to consume the output (use the astrograph resource URI for full details, not server-internal paths). However, it does not explicitly state when not to use this or compare to alternatives, though no obvious sibling overlaps exist.

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

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

Annotations indicate destructiveHint=true, but the description goes further by revealing that it blocks duplicate new code and warns on similarity. This is valuable behavioral context beyond what annotations provide, helping the agent anticipate operational safeguards.

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 short sentences, front-loaded with 'Edit file.' and immediately followed by the key behavioral constraint. Every word earns its place with no unnecessary fluff.

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

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

The tool is relatively simple with full schema and annotations, but no output schema exists, so the description could benefit from mentioning what the tool returns on success or failure. It also lacks usage context versus sibling tools. The core behavior is outlined, but a few gaps remain.

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 clear descriptions for all parameters. The description adds context about duplicate checking for new_string, but this is more of a tool-level behavior than parameter-specific semantics. The baseline of 3 is appropriate since schema already handles 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 tool edits a file, which is a specific verb and resource. It does not explicitly distinguish from the sibling 'write' tool, but the context of editing (replacing existing text) is implied and the duplicate-blocking behavior adds specificity.

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

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

No guidance is provided on when to use this tool versus alternatives like 'write' or when not to use it. The duplicate-blocking behavior hints at one use case, but there is no explicit when/when-not or alternative mention.

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

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

Annotations already indicate idempotent (idempotentHint=true) and non-destructive (destructiveHint=false) behavior. The description adds the context of generating 'reasonable defaults' but does not clarify whether the tool overwrites an existing .astrographignore or preserves custom entries. The description does not contradict annotations.

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

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

The description is a single sentence, front-loaded with the verb 'Auto-generate' and the resource '.astrographignore'. It is succinct with no wasted words.

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

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

Given the tool's simplicity (no params, no output schema) and the presence of annotations, the description adequately conveys the core behavior. However, it lacks guidance on when to use this tool over alternatives like 'write' or 'edit', and it does not mention the fate of an existing .astrographignore file, leaving some context incomplete.

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

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

The tool has zero parameters, and the schema confirms this with 100% coverage. There is no need for parameter descriptions. The baseline for zero parameters is 4, and the description appropriately does not invent 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 tool's action ('Auto-generate') and target resource ('.astrographignore') with a specific purpose ('excluding files from indexing'). This distinguishes it from sibling tools like 'write' and 'edit' which are generic file operations.

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 when a default ignore file is needed, but it does not explicitly state when to use this tool versus alternatives such as manually creating the file via 'write' or 'edit'. No exclusions or alternative recommendations are provided.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true, which already cover safety and idempotency. The description adds no extra behavioral context beyond restating the action, but it is consistent with the annotations, so no contradiction.

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

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

The description is a single, concise sentence with no wasted words. It fully communicates the tool's purpose in minimal space.

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

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

Given the tool's simplicity (no parameters, no output schema, read-only), the description is complete enough. It clearly states what the tool does, and no further context is necessary for an agent to select and invoke it correctly.

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

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

The tool has zero parameters, so no parameter semantics are needed. Per the baseline for 0 params, a score of 4 is appropriate since the description does not need to compensate for any parameter documentation gaps.

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 'List suppressed hashes' uses a specific verb and resource, clearly indicating the tool's action. It does not explicitly differentiate from sibling tools like 'status' or 'analyze', but the specificity to 'hashes' and 'suppressed' provides adequate clarity.

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 no guidance on when to use this tool versus alternatives. It lacks any context about use cases, prerequisites, or comparison to sibling tools such as 'suppress' or 'unsuppress'.

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

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

Annotations indicate readOnlyHint=false and openWorldHint=true, so the tool may mutate state and access external resources. The description adds a vague behavioral detail about returning a 'recommended_actions plan,' but it's unclear whether the tool actually configures bindings or merely recommends actions for the agent to execute. It does not disclose side effects of bind/unbind modes or prerequisites like project_root, so it fails to provide meaningful context beyond annotations.

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

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

The description is concise at two sentences and front-loads the core purpose. However, the second sentence ('Returns a guided recommended_actions plan...') is vague and could be more informative without adding length, so it slightly loses efficiency.

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

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

This is a complex tool with 7 parameters, 4 modes, and no output schema, so the description must explain overall behavior and return format. It only provides a vague 'recommended_actions plan' with no details on its structure or interpretation. It also omits important constraints like how mode affects behavior or when compile_db_path is needed, leaving the description incomplete for safe and effective use.

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 each parameter having a clear description (e.g., mode enum, language filter, compile_db_path override). The tool description itself adds no parameter-specific information, but given the schema already handles semantics, a baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Inspect and configure deterministic LSP command bindings for bundled language plugins.' This is specific with a clear verb+resource and distinguishes it from sibling tools like suppress/analyze/status, which focus on other concerns.

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 through 'Returns a guided recommended_actions plan for search/install/config workflows,' suggesting it's for setup tasks. However, it does not explicitly state when to use this tool vs alternatives or provide exclusions. No mention of when to prefer lsp_setup over sibling tools like set_workspace or write/edit.

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

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

Annotations already indicate destructiveHint and idempotentHint, and the description adds meaningful scope ('all persisted metadata') and a state outcome ('Resets server to idle'). It does not contradict annotations, though it omits details like irreversibility, which is already 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?

Two short sentences deliver the core action and result with no filler. Information is front-loaded and every phrase 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?

Given the tool's simplicity (no parameters, no output schema), the description plus annotations fully convey what is erased and the resulting idle state. No additional context is necessary 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 tool accepts zero parameters, so the baseline is 4. The description properly avoids inventing parameter details and the empty schema is sufficient.

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 'Erase' with a clear resource 'all persisted metadata' and adds a post-condition 'Resets server to idle.' This clearly distinguishes it from siblings like metadata_recompute_baseline and write.

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

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

No guidance is provided on when to use this tool versus alternatives such as metadata_recompute_baseline or suppress. The description only states what the tool does, with no context about appropriate scenarios or exclusions.

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

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

The description states 'Erase metadata,' which indicates a destructive action, directly contradicting the destructiveHint=false annotation. This is a significant inconsistency that misleads the agent about the tool's safety profile. No other behavioral traits are 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 a single, concise sentence that gets straight to the point. It is front-loaded with the primary action and requires no unnecessary elaboration.

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 the simple no-parameter signature, the tool performs a major operation (erasing metadata) with contradictory safety annotations. The description fails to clarify the impact, prerequisites, or consequences, making it incomplete for an agent to invoke safely.

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

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

The tool has zero parameters and the schema is empty, so schema coverage is 100%. Based on the rubric, zero parameters baseline is 4. The description adds no parameter information, but none is 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 erases metadata and re-indexes the codebase from scratch. This specific verb+resource combination distinguishes it from the sibling metadata_erase tool, which only erases metadata without re-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?

The description provides no guidance on when to use this tool versus alternatives like metadata_erase. No context, prerequisites, or exclusions are mentioned, leaving the agent to infer usage from the name and description alone.

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

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

Annotations already indicate read-only=false and destructive=false, and the description adds the re-indexing side effect, which is valuable behavioral context beyond the annotations. No contradiction present.

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 two-clause sentence that communicates both the action and a key side effect with zero redundancy. Every word 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 tool with one parameter and no output schema, the description is sufficient: it names the operation, the target resource, and the re-indexing consequence. It doesn't need to explain return values, and its simplicity fits the tool's low complexity.

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

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

Schema coverage is 100% and the 'path' parameter is clearly described as 'Absolute path to the new workspace directory'. The description does not add additional parameter semantics beyond what the schema already states, so baseline 3 is appropriate.

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

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

The description uses a specific verb ('Set or change') with a clear resource ('workspace directory') and adds a distinctive side effect ('Re-indexes the codebase'). This clearly differentiates it from sibling tools like write/edit and analyze.

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 context: it's for setting or changing the workspace directory, which is a clear purpose. However, it doesn't explicitly state when not to use it or mention alternatives, so it lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint and idempotentHint, covering the safety and repeatability profile. The description adds meaningful behavioral context: 'Returns instantly even during indexing,' which highlights that the tool is fast and non-blocking. It does not detail the exact response format, but this is not critical given the annotations and simple nature.

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: 'Check server readiness. Returns instantly even during indexing.' Every word earns its place, with no unnecessary detail or repetition. It is appropriately sized for the tool's simplicity.

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 zero-parameter tool with no output schema and strong annotations, the description is complete. It conveys the core purpose and one key behavioral trait that could influence invocation timing. An agent has enough information to select and invoke it correctly.

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

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

The tool accepts no parameters, and the input schema is empty with 100% coverage. The description implicitly confirms that no arguments are needed, aligning with the baseline for zero-parameter tools. There is no additional parameter information required.

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: 'Check server readiness' with a specific verb and resource. It distinguishes itself from sibling tools like analyze or suppress, which serve different purposes. The added note 'Returns instantly even during indexing' further clarifies its scope.

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

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

The description implies that this tool is used to check server status, and the note about returning instantly during indexing suggests it can be used as a quick readiness probe. However, it does not explicitly state when to prefer this over alternatives or mention any exclusions, relying on the user to infer the use case.

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

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

Annotations already indicate idempotent and non-destructive behavior. The description adds workflow context (from analyze output) and a usage caution, but does not disclose additional behavioral traits such as side effects or persistence. This is adequate given the annotations.

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

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

The description is two sentences, front-loaded with the action, and every sentence contributes 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?

For a single-parameter tool with good annotations and no output schema, the description covers purpose, usage criteria, and workflow context. It is self-contained and sufficient.

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

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

Schema description coverage is 100% and the description repeats the schema's 'WL hash from analyze output' without adding further meaning or examples. Baseline of 3 is appropriate.

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

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

The description clearly states the action (suppress) and the target (a duplicate identified by WL hash from analyze output). It distinguishes from siblings like unsuppress and analyze by focusing on the suppression step.

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 the tool ('Only suppress AFTER confirming the duplication is intentional') and when not to ('Refactoring should be the default action'), providing clear decision guidance.

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

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

Annotations provide idempotentHint and destructiveHint, but the description adds no extra behavioral context. It doesn't explain what unsuppressing entails (e.g., removing a hash from a suppression list) or any side effects. The description is essentially tautological with the tool name.

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

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

The description is concise with a single sentence and no fluff, but it is under-specified rather than efficient. It lacks structural elements like context or usage examples, which limits its usefulness despite its brevity.

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?

A simple tool with one parameter and no output schema still requires context on what 'unsuppress' does to the hash, its relationship to suppression lists, and any return indication. The description is insufficient for an agent to fully understand the operation; sibling tools suggest a suppression workflow, but the description doesn't leverage this.

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 documentation of the wl_hash parameter (100% coverage), including its description and type flexibility. The description adds no additional parameter-level detail, so the baseline of 3 applies.

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

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

The description uses a specific verb 'Unsuppress' and resource 'a hash', clearly indicating the action. It implicitly distinguishes from the sibling 'suppress' by being its inverse, though it doesn't explicitly reference the suppression list context.

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 no guidance on when to use this tool versus alternatives like 'suppress' or 'list_suppressions'. No context or exclusions are given, leaving the agent to infer usage solely from the name.

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

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

The description adds valuable behavioral context beyond the annotations by stating that duplicates are blocked and similar content triggers warnings. This clarifies the tool's safety profile, especially since annotations mark it as destructive (destructiveHint=true). It provides insight into the exact conditions under which the tool refuses or cautions, which is not evident from the schema or annotations alone.

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

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

The description is extremely concise, consisting of two sentences. However, the first sentence ('Write file.') is a near-tautology of the tool name, adding little value. The second sentence is informative and earns its place, but the overall structure could be more efficient by merging the core action with the behavior.

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 simple two-parameter tool and the presence of annotations, the description covers the key behavior but misses important context. It does not mention what happens on success (e.g., return value) or clarify how the 'warns on similarity' mechanism works. It also fails to differentiate from 'edit', leaving an agent uncertain about which tool to invoke for existing files. This is a moderate gap for a tool that is otherwise straightforward.

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 covers 100% of the parameters with clear descriptions ('Code to write' and 'Absolute file path'). The tool description adds no additional parameter-level detail, so it meets the baseline for high schema coverage without enhancing the semantics.

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 verb 'write' with the resource 'file', clearly indicating the tool's action. It adds behavioral specifics ('Blocks if duplicate exists, warns on similarity') that hint at its safe-write niche, but it does not explicitly distinguish itself from the sibling tool 'edit', which likely also handles file modifications.

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 this tool is for writing new files without overwriting existing ones, and it warns on similar content. However, it does not explicitly state when to prefer 'write' over 'edit' or when not to use it (e.g., if overwriting is intended). This leaves the usage context somewhat implicit.

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