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

The description reveals that the tool requires expectedSha256 to ensure the file hasn't changed, adding safety context beyond annotations. All annotations are false, and the description aligns with a write operation. Missing details on error handling or rollback.

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 concise sentences: first states purpose and preference, second provides a critical instruction. No redundant words, ideal front-loading.

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 the key usage instruction (read file and pass hash) but omits behavior on hash mismatch or patch apply failure. With no output schema and moderate sibling complexity, the description is minimally 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?

Schema coverage is low (25%), with only project having a description. The description clarifies expectedSha256's purpose (ensuring correct version) and mentions 'unified diff' in the title. But path and patch format lack explanation.

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 this tool applies a unified diff patch to one project file and is the 'preferred write tool for focused code edits.' It distinguishes from siblings like write_file and replace_text by emphasizing focused edits, but lacks explicit differentiation.

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 advises reading the file first and passing expectedSha256, implying a prerequisite and safety check. However, it does not specify when not to use this tool (e.g., for large modifications) or mention alternatives like write_file or replace_text.

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 minimal safety hints (non-read-only, non-destructive). Description adds important behavioral details: verification of each file/patch, backup creation, and rollback on failure, which go 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?

Single sentence that is concise and front-loaded with key behavioral guarantees. No unnecessary words.

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

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

Despite complexity (3 params, nested objects, no output schema), the description omits details on patch format, sha256 usage, return value, and concurrency behavior. Incomplete for safe agent 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 only 33% (only 'project' has description). The description does not elaborate on 'edits' structure, 'patch' format, or 'expectedSha256' purpose. Parameters like 'concurrency' are left unexplained.

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?

Description clearly states the tool applies verified patches to multiple files with safety mechanisms (verification, backups, rollback). This distinguishes it from siblings like apply_patch (single file) and batch_read_files (read-only).

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 for safe batch patching but does not explicitly state when to use versus single-file apply_patch or alternatives. No mention of prerequisites or when not to use.

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 important behavioral traits beyond the readOnlyHint annotation: it returns line-numbered content and SHA-256 hashes, preserves path and secret protections, and enforces a 30-file limit. No contradiction with 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?

A single, well-structured sentence that front-loads the core functionality 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?

Covers overall purpose, output format (line-numbered content, hashes), and protection behavior. However, it lacks parameter details and return structure, which is noticeable given no output schema and low schema description coverage.

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 only 25% (only 'project' has a description). The description does not explain any parameters (files, concurrency, maxTotalChars) or how startLine/endLine/maxLines work. It should compensate but fails to add meaning beyond the schema.

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

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

The description clearly states the tool reads multiple approved text files in a single call, returning line-numbered content and SHA-256 hashes. It distinguishes itself from the sibling tool 'read_file' by batching and specifying a limit of up to 30 files.

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?

Implicitly indicates use for batch reading with efficiency ('in one call') and preserves protections like read_file. However, it does not explicitly mention when not to use (e.g., for few files) or alternatives beyond implication.

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=true and idempotentHint=true. The description confirms destructive behavior ('clears caches') but does not add specifics like which caches are cleared or if any side effects occur. Annotations carry most of the burden here.

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?

Single sentence, front-loaded with the key action, no unnecessary words. Efficient and to the point.

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 command execution tool with annotations covering destructive behavior, the description is minimally adequate. However, it lacks details on return values, error conditions, and exactly which caches are cleared. Could be more complete given 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?

Schema description coverage is 67% (2 of 3 parameters have descriptions). The tool description adds no extra meaning beyond the schema; the parameter descriptions in the schema are already clear. 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: 'Runs php artisan optimize:clear' in a Laravel application. It specifies the exact command and context, distinguishing it from sibling tools like run_artisan.

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 on when to use this tool versus alternatives, such as other cache-clearing commands or run_artisan. The description is too brief to help the agent decide.

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 mentions 'safe non-interactive defaults' and 'auto-detected', but does not disclose potential side effects (e.g., updating lock file, failure conditions). Annotations already indicate destructiveness, so description adds limited behavioral context.

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

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

Single sentence with no extraneous information, front-loaded with verb and resource. Highly concise.

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

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

With no output schema, 5 parameters, and a destructive annotation, the description is too brief. It does not explain return values, error behavior, or how auto-detection works, leaving significant gaps.

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 low (40%), and the description does not add meaning beyond the schema. It mentions 'auto-detected Composer project' hinting at the project parameter but does not explain other parameters like noDev or optimizeAutoloader.

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 'runs composer install' and the resource 'Composer project', specifying 'safe non-interactive defaults' and 'auto-detected', which distinguishes it from sibling tools like npm_install.

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 for installing Composer dependencies but does not explicitly state when to use versus alternatives (e.g., run_command). No when-not-to-use or prerequisite info is 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?

The description discloses the key behavioral trait of refusing to overwrite existing paths. Annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false) are consistent, but the description adds useful context beyond their boolean values.

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?

A single sentence that is concise and front-loaded. Every word is necessary, no fluff.

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

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

Given 4 parameters, no output schema, and many sibling tools, the description is too sparse. It omits details on content defaults, createParents behavior, return values, and when to choose this over other file manipulation tools.

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 any parameter details. Only 25% of parameters have schema descriptions (project has a description). The text adds no meaning about path, content, or createParents, failing to compensate for low 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 clearly states the tool 'Creates a new file and refuses to overwrite an existing path.' This distinguishes it from sibling tools like write_file, which likely overwrites. The verb 'creates' and resource 'new file' are specific.

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

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

The description implicitly suggests use when creating a new file and wanting to avoid overwriting, but does not explicitly provide when-to-use or when-not-to-use guidance, nor mention alternatives beyond the overwrite refusal.

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 mark destructiveHint=true. The description adds valuable context: hash verification requirement and backup retention, which go beyond the annotations and clarify the tool's safe behavior.

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

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

Two sentences, front-loaded with key information, no wasted words. Efficient 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?

No output schema and moderate complexity (3 required params, destructive). Description covers safety but lacks details on failure behavior, return value, or prerequisites (e.g., file existence). Could be more complete.

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 only 33% (only project described). The description mentions 'hash verification' hinting at expectedSha256, but does not explain path or add syntax/format details. Low compensation for poor 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 clearly states the action (delete), resource type (one regular file), and key constraints (hash verification, backup). It distinguishes the tool from siblings like create_file or write_file.

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

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

The description implies when to use (delete with safety) but does not explicitly exclude use cases or mention alternatives. It provides no guidance on when not to use this tool.

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

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

Annotations already declare readOnlyHint=true, so description's addition of what data is returned provides useful context beyond the annotation. No contradictions exist.

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?

One sentence with all crucial information, front-loaded verb, and no wasted words. Highly concise and well-structured.

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

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

Given the tool's simplicity (one parameter, no output schema), the description appropriately lists return contents. It is complete enough for an agent to understand what the tool does.

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% for the single parameter 'project', and the description does not add new meaning beyond what the schema already provides. Baseline score 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?

Description clearly states the tool returns configured stack, Git branch, manifests, package scripts, and working directories. It uses a specific verb 'Returns' and distinguishes from siblings like list_projects and read_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?

Usage context is implied (to inspect project metadata), but there is no explicit guidance on when to use vs alternatives or 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?

Beyond the readOnlyHint annotation, the description adds key behavioral context: the results are cached and invalidation triggers on Git HEAD/status changes. This helps the agent understand caching semantics and when data might be stale.

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 no filler: the first lists returned content, the second clarifies cache behavior. Front-loading the return value list is effective.

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 enumerates returned data items but lacks detail on output structure or how parameters like forceRefresh affect behavior. Given no output schema, more completeness would be beneficial.

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?

Only the 'project' parameter is described in the schema; the description does not address 'forceRefresh' or 'maxDocuments'. With 33% schema coverage, the description could have compensated by explaining these parameters, but it does not, leaving the agent to guess their 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 explicitly lists the exact data returned (branch, working-tree state, recent commits, etc.) and uses a clear verb 'Returns'. It distinguishes from siblings like get_project_info and get_project_tree by emphasizing the comprehensive cached snapshot.

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 for a full project overview via 'in one cached call', but it does not explicitly state when to prefer this tool over alternatives like get_project_info or list_directory. No exclusions or prerequisites are mentioned.

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 `readOnlyHint: true`, marking it as read-only. The description adds value by disclosing that generated, dependency, secret, and cache directories are excluded, which is behavioral context beyond the annotations. No contradictions detected.

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 conveys the core purpose and key behavioral trait (exclusions). No unnecessary words or repetitions. Front-loaded with the action verb and resource.

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?

While the description covers essential exclusions, it lacks details about the output format or structure (e.g., returns paths vs. tree objects). Given the absence of an output schema, more context would be beneficial for an agent to use the tool effectively. Annotations partially cover safety but not completeness.

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 50% (path and project have descriptions; maxDepth and maxEntries do not). The tool description does not add any parameter information, failing to compensate for the undocumented parameters. With no additional parameter semantics, the description provides minimal help 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 inspects a project structure, with mention of excluded directories (generated, dependency, secret, cache). This differentiates it from sibling tools like `list_directory` which likely list all files without exclusions. However, it does not explicitly name alternatives, so not a perfect 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?

The description provides explicit guidance on when to use the tool ('Use this to inspect a project structure'), but lacks information on when not to use it or how it compares to alternatives such as `list_directory`. The usage context is implied but no exclusions or alternative recommendations are stated.

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=true, and the description confirms it's a load operation. The description adds no extra behavioral traits beyond what annotations provide, such as caching or permission details. It is consistent with annotations, so a baseline score of 3 is appropriate.

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 two clear, front-loaded sentences. The first sentence defines the core action, and the second provides a concrete use case. No extraneous information, every sentence serves a 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?

The tool is simple with one parameter and no output schema. The description explains what the tool does and provides a usage example. However, it does not describe the return format or structure of the 'complete governing instructions', which would enhance completeness. Still, it is mostly adequate for the tool's simplicity.

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 the 'name' parameter. The description only adds an example value ('frontend-craft-director') but does not explain the pattern, constraints, or other valid values. Thus, it adds minimal additional meaning beyond the schema.

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

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

The description clearly states it loads 'complete governing instructions' for a centrally installed skill. It uses a specific verb ('Loads') and resource ('skill'), and differentiates from siblings like list_skills by focusing on loading instructions rather than listing. The concrete example of using 'frontend-craft-director' further clarifies its purpose.

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

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

The description explicitly says when to use this tool: 'For frontend design, redesign, ... call get_skill with 'frontend-craft-director' before inspecting or editing.' This provides clear context and usage ordering. It doesn't explicitly list alternatives or when not to use, but the guidance is strong.

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=true, so the description need not repeat that. It adds the behavioral detail that the diff is current and optionally scoped, but does not disclose other traits like output format or performance.

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 no extraneous words. The purpose is front-loaded in the first sentence, and the optional path is in the second. Highly 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?

The description covers the basic functionality but omits details like output type (e.g., text diff) or how the tool interacts with other git tools. Given the simplicity, it is adequate but not rich.

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?

With low schema coverage (33%), the description compensates by explaining the path parameter ('project-relative path') and alluding to the staged parameter ('unstaged or staged'). The project param is documented in 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?

Description clearly states the tool reviews unstaged or staged code changes, which is a specific verb-resource combination. It is distinguishable from sibling tools like git_status (which shows status, not diff), but does not explicitly differentiate.

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 some usage guidance by mentioning optional path limiting, but lacks explicit when-to-use or when-not-to-use instructions and does not reference alternatives among siblings.

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

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

The annotations already declare readOnlyHint=true, and the description aligns by saying 'see.' However, the description adds no additional behavioral context beyond what annotations provide, such as performance characteristics or scope limitations.

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 with no filler. Every word adds value, making it highly concise and structured.

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

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

For a simple read-only status tool with one parameter and no output schema, the description adequately covers purpose and usage. It could mention output format or scope, but the current minimalism is reasonable.

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% for the single parameter, so the description does not need to add parameter info. It adds no extra semantics beyond the schema, earning a 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: to see modified, added, deleted, and untracked files after edits. This distinguishes it from sibling tools like git_diff (which compares commits) and inspect_changed_files (which may show more details).

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

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

The description explicitly says 'Use this after edits,' providing a clear usage context. However, it does not mention when not to use it or suggest alternative tools for different scenarios (e.g., git_diff for staged changes).

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 mentions validation of branch name, expected HEAD, and clean working-tree requirement, adding context beyond annotations. However, it does not specify what happens on failure, how existing branches are handled, or any side effects. Given annotations are all false, the description carries some burden but is incomplete.

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 that front-loads the main purpose and key validations. No redundant 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?

The tool has 6 parameters, no output schema, and low schema description coverage. The description does not explain return values, error behavior, or how the tool interacts with the Git state. It leaves significant gaps for an AI agent to correctly invoke the tool.

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

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

With schema description coverage at 17% (only 'project' described), the description adds minimal meaning for other parameters. It references 'validating the branch name, optional expected HEAD, and clean working-tree requirement' but does not explain 'create', 'dryRun', or 'project' beyond the schema. The description fails to compensate for the low coverage.

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

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

The description clearly states the tool creates or switches Git branches, with specific validation steps. It distinguishes from sibling tools like git_status or git_diff, 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 implies usage for creating or switching branches but does not explicitly state when to use this tool over alternatives like git_status or other Git operations. No when-not-to-use guidance is 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 already declare destructiveHint=true. The description adds constraints on source and destination but does not disclose failure behavior (e.g., if overwrite=false and file exists) or further side effects beyond the copy 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?

Two sentences, no redundancy, front-loaded with key information. Efficient 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?

For a tool with 6 parameters, annotations, and no output schema, the description covers core purpose and constraints but lacks details on optional parameters and error handling. It is adequate but not comprehensive.

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 50%. The description adds context for source_file and destination (constraints), but does not explain overwrite, createParents, or expectedSha256 parameters. It partially compensates but leaves 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 clearly states the tool copies an uploaded file into a project without Base64 conversion, distinguishing it from sibling tools like write_file that write content directly. However, it could be more explicit about when to use this vs other 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 gives context by specifying source must be from an approved mounted-file root and destination restricted to project root, implying when to use it. However, it does not explicitly state when not to use it or name alternatives like write_file.

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=true. The description adds the behavioral note 'without re-scanning the whole project', which is useful but limited. No other traits (e.g., performance on large repos) 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, dense sentence that front-loads the key outputs. It is not verbose but could be more structured (e.g., bullet points) for easier parsing. 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?

Given 4 parameters and no output schema, the description covers the major return items but lacks detail on maxDiffChars. It provides a good overview but is not fully complete for parameter semantics.

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?

With only 25% schema description coverage, the description adds meaning for includeDiff ('optional compact diff') and includeStaged ('staged changes'), but does not explain maxDiffChars. The schema itself is sparse, so the description partially compensates but not fully.

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 returns branch/status, changed file names, diff stats, and more, using the verb 'inspect' with 'changed files'. It distinguishes from sibling tools like git_status and git_diff by being a comprehensive single-call summary.

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 use as a one-call summary but does not explicitly state when to use this tool over alternatives like git_status or git_diff. No when-not or alternative guidance is 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?

Description aligns with annotations (readOnlyHint=true) by stating it is read-only and does not run migrations or write data. It adds behavioral context by naming the specific Laravel commands executed, which annotations do not capture. 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?

Two sentences, front-loaded with the core action. Every sentence adds value: first states what it runs, second clarifies read-only nature. 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?

No output schema exists, and the description does not describe return values or behavior for missing parameters. With 6 parameters and no output spec, the description is too minimal to fully inform an agent about invocation expectations.

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 low (33%, only cwd and project described). The tool description does not explain parameters like table, views, counts, or timeoutSeconds, leaving the agent without guidance beyond the schema. Description should compensate but does not.

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?

Description clearly states action ('Runs') and resource ('Laravel's read-only db:show or db:table command'), explicitly marking it as read-only and distinguishing it from write/migration operations. This specificity differentiates it from sibling tools like run_artisan or laravel_run_artisan.

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?

Implies use for inspecting database schema without writing data, but does not explicitly contrast with the sibling laravel_run_artisan, which could also run db:show/db:table. No when-not-to-use or alternative suggestions are provided, leaving the agent to infer optimal 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?

Annotations already declare readOnlyHint=true, so the description adds minimal extra behavioral context. It doesn't describe error states or limit conditions beyond stating 'status and sanitized output'.

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?

Single, front-loaded sentence with no fluff. Every word is necessary.

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 read-only tool with two parameters, the description is largely complete. Could mention typical error cases or result format but not required.

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%: only 'project' has a description. The tool description adds no parameter details, leaving 'sessionId' undocumented. No compensation for the gap.

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 ('returns') and the resource ('status and sanitized output for a process'), distinguishing it from sibling tools like start_local_process and stop_local_process.

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

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

No explicit guidance on when to use this tool versus alternatives, though it is implicitly for inspecting previously started processes. No mention of when not to use or required preconditions.

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=true, so the read-only nature is known. The description adds the fact that filters are optional, but does not disclose additional behaviors like error handling or output format.

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 that is concise and front-loaded with the action. It contains no unnecessary words, but could be slightly expanded without losing 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?

For a simple read-only tool, the description covers the basic functionality. However, since there is no output schema, it lacks explanation of what the output looks like, and it does not provide context on when to use this tool among many Laravel-related siblings.

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 adds meaning to three of the seven parameters (method, path, name) by indicating they are filters. However, schema description coverage is only 29%, and the description does not cover other parameters like cwd, json, project, or timeoutSeconds.

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

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

The description clearly states it runs route:list with optional method, path, and name filters, making the purpose evident. However, it does not explicitly differentiate from sibling tools like run_artisan that could also run route:list.

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 (e.g., run_artisan). The description does not mention when not to use it or any prerequisites.

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=true, so the description adds value by clarifying 'bounded' (limiting result scope) and 'without accepting raw SQL' (security constraint). No contradictions exist. Minor missing details on assertion failure behavior, but overall adequate.

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 with no filler. Every word serves a purpose, clearly identifying the tool's action and constraints.

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 complexity (8 parameters, nested objects, no output schema), the description is too brief. It does not explain return value format, error handling, or how to interpret assertion results. The agent would need to infer much from the schema alone.

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 only 25%, and the description adds no parameter-specific explanations. It mentions assertion types but does not elaborate on parameters like 'query', 'expected', or 'jsonPath' beyond what is in the schema. The description fails to compensate for low 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 clearly states it evaluates assertions over a read-only Laravel query, listing specific assertion types (count, existence, column, JSON-path). It distinguishes from siblings by emphasizing 'bounded read-only' and 'without accepting raw SQL', which is unique among database-related tools.

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 for assertions but does not explicitly compare to sibling tools like laravel_database_snapshot or provide when-not-to-use guidance. Context suggests it is for verifying database state, but no direct alternatives are mentioned.

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; the description reinforces this by stating 'Reads'. It adds behavioral context: 'model-provided raw SQL is not accepted', which is not present in annotations. 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?

Two sentences with no wasted words. The most critical information (purpose and constraint) is front-loaded, making it easy to parse.

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

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

No output schema exists, so the description should clarify return value structure. It mentions 'count and bounded rows' but does not explain the format or how filters combine. Incomplete for an agent to understand full 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?

Schema coverage is 50%, but the description only lists parameter categories (table, columns, filters, ordering, limit) without explaining their syntax or behavior. It does not compensate for undocumented parameters like cwd or timeoutSeconds, adding little 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 it reads a count and bounded rows via Laravel's query builder, specifying it is structured and does not accept raw SQL. This distinguishes it from siblings like laravel_database_assert (assertions) and inspect_database_schema (schema).

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 for reading data with structured queries, but does not explicitly state when to use this tool over alternatives. No exclusions or prerequisites are mentioned, leaving the agent to infer context from sibling names.

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?

Beyond annotations (destructiveHint=true), the description adds context about the risk classifier and the need for explicit write approval for unknown commands, providing useful behavioral insight.

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 concise, front-loaded sentences effectively convey the core purpose and unique risk handling without 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 complexity (8 parameters, nested objects, no output schema), the description is too sparse; it omits parameter usage, output details, and practical invocation examples.

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?

With only 25% schema description coverage, the description fails to explain any parameters beyond what the schema already provides, leaving the agent without guidance on command, options, or other fields.

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

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

The description clearly states it runs Artisan commands through a risk classifier, distinguishing it from siblings like 'run_artisan' and 'run_command' by focusing on Laravel-specific commands with safety classification.

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 implies usage for Laravel Artisan commands and mentions write approval for unknown custom commands, but does not explicitly compare with sibling tools or specify 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?

Adds specific restrictions (process, filesystem, network, raw-SQL, secret access blocked) beyond annotations' destructiveHint, but doesn't detail return behavior or error handling.

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 front-load purpose and restrictions; no filler 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?

With 8 parameters, no output schema, and complex restrictions, the description fails to explain parameter usage or expected outputs, leaving significant gaps.

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?

Only 2 of 8 parameters have schema descriptions (25% coverage), and the tool description adds no parameter details; key fields like outputMode, transactionMode, allowDatabaseWrite are unexplained.

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?

Description clearly states it runs reviewed PHP code through Laravel Tinker with an ephemeral script, distinguishing it from other tools like run_command or run_artisan.

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?

Description lists blocked operations and approval requirement for database writes, implying safe use cases, but lacks explicit guidance on when to avoid 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?

Annotations already declare readOnlyHint=true; description adds that secret and dependency paths remain blocked, which is useful 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?

Two concise sentences, front-loaded with the tool's action. No unnecessary words.

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

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

With 4 parameters, no output schema, and no error handling details, the description is too sparse. It omits filtering, pagination (maxEntries), hidden files option, and return format beyond basic metadata.

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%; description does not explain any parameters (path, maxEntries, includeHidden) beyond what the schema provides, missing an opportunity to clarify defaults or behavior.

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

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

The description clearly states it lists immediate files and folders with metadata, distinguishing it from sibling tools like list_projects which list projects, not directory contents.

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

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

No explicit guidance on when to use this tool vs. alternatives like get_project_tree or read_file. No exclusions or prerequisites mentioned.

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 reveals that the tool returns not just a list but also details like keys, roots, stacks, and existence status. This adds value beyond the `readOnlyHint` annotation, which only indicates safe read behavior.

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

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

A single, front-loaded sentence efficiently conveys purpose and output details 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 parameterless listing tool, the description sufficiently explains what it returns. While there is no output schema, the description gives enough context for the agent to interpret results.

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?

With zero parameters, the input schema is fully covered (100%). The description compensates by specifying the output fields, providing meaning beyond the empty 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 explicitly states the tool's purpose: to discover project keys, roots, stacks, and root existence. The title 'List configured local projects' reinforces a clear verb-resource pairing. It distinguishes itself from sibling tools like `get_project_info` by offering a broader overview.

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 guides the agent to 'Use this first', providing clear context for when to invoke it as an initial discovery step. It does not explicitly exclude cases or list alternatives, but the primary usage is well-defined.

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=true, confirming no destructive side effects. The description adds that skills include references/templates, but beyond that no additional behavioral disclosure is needed.

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 concise sentences with front-loaded action and immediate usage context; 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?

For a zero-parameter listing tool, the description adequately covers return content (descriptions and references/templates). Could define 'skill' more precisely, but 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?

No parameters exist, and schema coverage is 100%. The description need not add parameter detail; baseline score of 4 is appropriate.

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

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

The description clearly states the tool lists centrally installed skills with descriptions and references/templates, distinguishing it from sibling tools like get_skill and read_skill_reference.

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

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

Explicit guidance 'Use this when the user asks what workflows or skills are available' is provided, though no exclusions or when-not-to-use scenarios are mentioned.

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 basic hints (readOnlyHint=false, destructiveHint=false) but the description adds important behavioral details: redirects are revalidated and sensitive headers are redacted. This goes beyond annotations and helps the agent understand security-related behavior. Some aspects like potential side effects are not fully disclosed, but the description is honest about constraints.

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 word adds value. There is no wasted text. The structure is efficient 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 the complexity (9 parameters, no output schema, low schema coverage), the description is incomplete. It does not explain return values, error handling, or parameter relationships. While it covers security constraints, the agent lacks sufficient guidance to use the tool effectively beyond the basic purpose.

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 for parameters is only 11% (only the 'project' field has a description). The description adds no parameter-specific information; it only describes overall behavior. For a tool with 9 parameters and nested objects, the description does not compensate for the low 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 clearly states the verb ('Sends an HTTP request') and the specific resource/constraint ('only to approved hosts that resolve exclusively to loopback addresses'). It effectively distinguishes from sibling tools, many of which are file/git/command operations; this is the only HTTP request tool.

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

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

The description specifies when to use: 'only to approved hosts that resolve exclusively to loopback addresses.' It strongly implies usage for local HTTP integrations. However, it does not explicitly state when not to use or mention alternatives, so the guidance is slightly less explicit.

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

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

Annotations already mark it as readOnlyHint=true, but the description adds crucial behavioral context: it does not return, log, or expose the secret on the command line. This goes beyond annotations to assure safety, though it doesn't fully detail the HMAC computation steps.

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 dense sentence that packs key information (action, resource, constraints). It is front-loaded with the main action. However, it could be broken into sentences for clarity, but it is not overly verbose.

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?

With 6 parameters (3 required), an enum for operations, and no output schema, the description should provide more context on operation behaviors (e.g., what 'presence_check' does) and output encoding options. It is insufficient for an agent to fully understand tool 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?

Schema coverage is only 33%, and the description adds no parameter-level detail. It fails to explain the meaning of fields like payload, outputEncoding, or the operation enum values. The description must compensate for low schema coverage, but it does not.

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 tool's action ('Checks... or computes a digest/HMAC') and resource (approved Laravel .env key). It distinguishes itself by listing what it does NOT do (returning, logging, placing on command line, writing secret), which differentiates it from sibling tools like read_file or run_command.

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 using this tool for secure secret operations without exposure, but does not explicitly state when to use it over alternatives or when not to use it. Given the sibling list includes many command-execution tools, more direct guidance would be beneficial.

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 destructiveHint=true, so the description adds minimal behavioral context. It mentions auto-detection and no-audit/no-fund defaults, but does not elaborate on what exactly is modified (e.g., node_modules, lock files) or potential side effects like timeouts or script execution.

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

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

The description is a single, well-structured sentence that front-loads the core action and key specifics (auto-detection, defaults). No extraneous words or redundancy.

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

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

Given the destructiveHint, no output schema, and 5 parameters, the description explains core functionality and defaults but omits details like error behavior, output format, or whether it reverts on failure. It is minimally adequate but lacks completeness for a destructive 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 coverage is 40%; description adds value by explaining that project is auto-detected and that default mode is ci, and that no-audit/no-fund flags are applied. However, it does not describe cwd, ignoreScripts, or timeoutSeconds, leaving gaps for those parameters.

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

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

The description clearly states it runs npm ci or install with specific defaults (no-audit/no-fund) inside an auto-detected npm project. It uses a specific verb and resource, and the auto-detection detail distinguishes it from a generic run_npm sibling.

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 run_npm. It does not mention when to avoid it, prerequisites, or exclusions. Usage context is purely 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?

The description adds behavioral constraints (blocking secret/dependency files) and output features (line numbers, hash) beyond annotations. 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?

Three short, front-loaded sentences with no fluff. Every word 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?

With 5 parameters and no output schema, the description omits file size limits, encoding, and detailed return structure beyond line numbers and hash.

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 only 20%, and the description does not explain parameter details like path format, line numbering, or maxLines implications.

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

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

The description clearly states the tool reads a text file, provides line numbers and a SHA-256 version hash, and blocks certain files. It distinguishes from write/delete siblings.

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 for reading a file but does not explicitly differentiate from batch_read_files or provide when-not-to-use 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?

The description adds 'redacts', disclosing that sensitive information is removed, which is a key behavioral trait beyond the readOnlyHint annotation. It also explains it reads the newest log or a selected file, but could further detail redaction behavior or limits.

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, efficient sentence that conveys the core functionality without unnecessary words. It is front-loaded with the key action and resource.

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 5 parameters and no output schema, the description covers purpose and redaction but leaves gaps in parameter semantics and potential nuances (e.g., line limits, filtering via contains). It is minimally adequate but could be more complete.

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?

With only 40% schema coverage (descriptions for cwd and project), the description fails to add meaning for undocumented parameters like file, contains, and maxLines. It hints at a 'selected log file' but does not clarify parameter roles or usage beyond the schema.

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

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

The description clearly states the tool reads and redacts recent Laravel log lines, specifying both the action and the resource. It distinguishes from siblings like read_file or search_files by focusing on Laravel logs with redaction.

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?

While the description implies usage for reading Laravel logs with redaction, it does not explicitly state when to use this tool over alternatives like read_file for non-log files or search_files for pattern matching. No when-not or alternative guidance is 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 already declare readOnlyHint=true. The description adds valuable context that it reads from references/ or templates/ directories and suggests a usage pattern, but 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?

Two sentences, no wasted words. First sentence states purpose, second provides usage guidance. Highly 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?

For a simple read tool with good annotations and schema coverage, the description is complete enough. It could mention return format or error cases, but not necessary given simplicity.

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 both parameters are well described in the schema. The description does not add significant parameter meaning beyond naming the directories, 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 clearly states it reads a supporting file from a skill's references/ or templates/ directory, using specific verb and resource. It distinguishes from siblings like get_skill and read_file by specifying the directory 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?

Explicitly provides progressive disclosure guidance: load main skill first, then read only needed supporting file. This tells when and how to use the tool relative to get_skill.

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 destructiveHint=true and readOnlyHint=false. The description adds that destination overwrite is refused, which is a behavioral constraint. However, it does not disclose other potential side effects, permission requirements, or what happens to the source file after the move. The added context is moderate.

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

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

The description is extremely concise: two sentences with no filler. The first sentence immediately states the primary action, and the second adds key constraints. Every word earns its place, and it is well front-loaded.

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

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

Given the tool has 5 parameters (4 required) and no output schema, the description provides only minimal context. It explains the scope ('inside the same configured project') but omits details about path formats, return values, or error behavior. The annotations cover safety but not completeness. The description is adequate but leaves room for ambiguity.

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 only 20%, with only the 'project' parameter documented. The description mentions 'source hash' (likely referring to expectedSha256) and implies that destination overwrite is refused, which adds some meaning. However, it does not explain the format or meaning of source, destination, or createParents parameters, leaving significant 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 clearly states the action ('moves a file') and the resource ('inside the same configured project'). The title includes 'rename or move', which clarifies the purpose. However, it does not explicitly differentiate from sibling tools like import_file_to_project or write_file, which might also move or create files.

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 mentions specific constraints ('source hash is required' and 'destination overwrite is refused') but provides no guidance on when to use this tool versus alternatives. It does not state any prerequisites, context, or warnings about not using it in certain scenarios.

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?

Description details SHA-256 verification, exact occurrence counting, backup, and no shell execution. Since annotations provide limited behavioral info (readOnlyHint=false, destructiveHint=false), the description fully compensates with valuable safety and execution context.

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

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

A single, well-structured sentence that is front-loaded with the core action and immediately conveys key safety features. 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?

With 6 parameters and no output schema, the description could be more complete. It mentions safety features but does not explain the return value or side effects (e.g., file modification). Basic coverage, but leaves some gaps.

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 only 17%, with only 'project' having a description. The tool description does not explain parameter semantics (e.g., expectedSha256, expectedOccurrences), relying on parameter names which may be ambiguous.

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 title and description clearly state a specific operation: replace exact text in one file with safety features. It distinguishes from sibling tools like write_file or apply_patch by emphasizing precision and verification.

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?

While it mentions 'no shell or script execution', no explicit guidance is given on when to use this tool versus alternatives like apply_patch or write_file. The agent must infer usage from 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?

Annotations already indicate destructiveHint=true, but the description adds that workers restart gracefully after their current job, providing behavioral context beyond the annotations. It does not contradict any 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 concise sentence that front-loads the action and purpose, with no unnecessary words.

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

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

Given the tool's simplicity (no output schema, three parameters with good schema descriptions), the description is sufficient. It covers the core purpose and side effects. Could mention that it sends a signal versus blocking, but overall complete.

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 67% (all three parameters have descriptions in the schema). The tool description does not add further parameter meaning beyond what the schema provides. 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 verb 'restarts' and the resource 'queue workers', and specifies the underlying artisan command. It distinguishes itself from siblings like 'clear_laravel_cache' or 'run_artisan' by being specific to queue worker restarts.

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 when to use it (to restart workers gracefully), but does not provide explicit when-not-to-use guidance or compare to alternatives like 'run_artisan'. The context is clear but lacks exclusions or alternative recommendations.

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 emphasizes the tool is read-only, but annotations set destructiveHint: true and readOnlyHint: false, directly contradicting the description. This is a serious inconsistency that misleads the agent about the tool's safety.

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

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

The description is extremely concise (two sentences) with no filler. It immediately states the tool's purpose and provides the key usage distinction. 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?

Despite having 5 parameters and no output schema, the description omits critical details like error handling for non-allowlisted commands, return format, or clarification of the annotation contradiction. It is incomplete for safe and effective agent 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?

Only 2 out of 5 parameters (cwd, project) have descriptions in the schema. The tool description does not add any parameter-specific guidance, such as valid command names or how to pass arguments. Given low coverage (<50%), the description fails to compensate.

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 title and description clearly state that the tool runs only allowlisted or configured read-only Artisan commands. It explicitly distinguishes from the sibling laravel_run_artisan for write-capable commands, making the purpose specific and 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 provides clear guidance on when to use this tool (for read-only commands) versus laravel_run_artisan (for write-capable commands). However, it does not elaborate on scenarios where the tool should not be used or prerequisites like ensuring the command is allowlisted.

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 destructiveHint=false, but the description adds little behavioral context. It does not mention side effects, return behavior, or error handling, leaving gaps for the agent.

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 extraneous text. It is front-loaded, but the brevity sacrifices completeness.

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 5 parameters and no output schema, the description is too brief. It does not explain when to use this over similar tools, what happens on failure, or expected output, making it incomplete for agent 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?

With 40% schema description coverage, only cwd and project have descriptions in the schema. The tool description does not add any additional parameter meaning, failing to compensate for the low coverage.

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

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

The description clearly states it runs an existing build script, typically 'npm run build', providing a specific verb and resource. It distinguishes from siblings like 'run_command' or 'run_npm' by focusing on build scripts.

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 use for running build scripts but gives no explicit when-to-use or when-not-to-use guidance. No alternatives among siblings are mentioned, so the agent must infer use cases from 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?

Annotations already mark destructiveHint=true; the description adds that commands are 'guarded' and shell operators are blocked, providing some behavioral context. However, it does not explain what 'guarded' entails (e.g., validation, sandboxing) or potential side effects beyond the annotation.

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 front-loades the essential purpose and constraints. However, it could benefit from a more structured format (e.g., bullet points for allowed executables) given the parameter count.

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?

With 5 parameters, no output schema, and many sibling tools, the description lacks crucial details like return format, argument syntax, timeout behavior, and scenario-specific guidance. The agent may struggle to use this tool correctly without additional context.

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

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

Schema description coverage is 40% (only project and cwd have descriptions). The tool description does not add any parameter-specific details beyond the schema, such as how to construct 'args' or the meaning of 'timeoutSeconds'. This leaves significant ambiguity for the agent.

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 runs guarded PHP/Laravel, Composer, npm, or Git commands, and blocks shell operators/arbitrary executables. It identifies the specific verb 'run' and resource 'development commands'. However, it does not explicitly differentiate from sibling tools like run_artisan or run_npm, relying on the executable enum for disambiguation.

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 more specific siblings (e.g., run_artisan, run_npm, git_switch_branch). The description does not mention exclusions, prerequisites, or typical use cases, leaving the agent without decision criteria.

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 the tool is not read-only and not destructive, but the description adds little beyond that. It mentions running an existing script, implying the tool will execute a npm script but does not disclose potential side effects (e.g., modifying files), authentication needs, or error behavior. 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 concise sentence with no fluff. It front-loads the action and is immediately informative.

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 5 parameters and no output schema, the description is too minimal. It does not explain prerequisites (e.g., ESLint must be installed, a lint script must exist), the return value or output format, or behavior on failure. The agent lacks enough context to use the tool confidently.

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?

With only 40% schema coverage, the description adds some value by explaining the 'args' parameter ('optional extra arguments') and implying the 'script' parameter defaults to 'lint' ('normally npm run lint'). However, it does not address 'cwd', 'project', or 'timeoutSeconds', which remain underdocumented.

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

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

The description clearly states it runs an existing lint script, typically 'npm run lint', with optional extra arguments. The verb 'runs' and resource 'lint script' are specific, and the tool name 'run_eslint' reinforces this. It distinguishes from siblings like 'run_command' or 'run_npm' by focusing on linting.

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 'run_command' or 'run_npm'. It does not specify when not to use it, such as when lint is not defined or when a different lint runner is needed. The agent is left to infer usage from the tool name 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 mark destructiveHint: true. The description adds that it runs a script, reinforcing mutation, but doesn't elaborate on specific behaviors (e.g., side effects, environment changes). No contradictions, but minimal extra 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?

A single sentence of 15 words conveys the core purpose and key constraint (auto-detected or specified root). No redundancy; every word 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?

With 5 parameters, no output schema, and destructive hint, the description lacks details on return value (e.g., stdout, exit code), error behavior, or environmental setup. This is insufficient for an agent to fully anticipate tool outcomes.

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 40% (only project and cwd described). The description adds context about auto-detection vs explicit root, relating to cwd and project. However, it does not explain script, args, or timeoutSeconds, leaving gaps for the agent.

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

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

The description clearly states it runs an npm script from package.json, with auto-detection or explicit root. The verb 'runs' and resource 'script declared in package.json' are specific, and the title further clarifies. This distinguishes it from sibling tools like run_command, run_tests, 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 does not explicitly state when to use this tool vs alternatives like run_command. It implies usage for npm scripts, but lacks explicit guidance on context or exclusions. The name helps, but no direct comparison is made.

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 are minimal and description adds no extra behavioral context such as side effects, permissions, or output behavior.

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

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

Single sentence, no redundancy, all words contribute.

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?

With 6 parameters, no output schema, and low schema coverage, the description is too sparse; missing info on output format, error handling, or when to set timeout.

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?

Only 33% of parameters have schema descriptions; the tool description mentions 'optional filter and path' but does not detail their semantics or provide examples.

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

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

The description clearly states it runs vendor/bin/pest with optional filter and path, distinguishing it from sibling tools like run_phpunit and run_tests.

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 on when to use this tool versus alternatives like run_phpunit or run_tests; lacks when-not-to-use or prerequisite 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?

Annotations are minimal (no readOnly, destructive hints). The description does not disclose potential side effects (e.g., output files, report generation), permissions needed, or execution environment details beyond 'auto-detects the relevant app root'. More context on process behavior is needed.

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 of 18 words. Every word is necessary and directly relevant. No fluff or repetition.

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

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

There is no output schema, so the description should explain return values or output format. It does not. Also, the tool runs a command; details about stdout/stderr handling or success/failure signals are absent. With 6 parameters and no output schema, the description is insufficient.

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 adds context for 'filter', 'test suite', and 'path', but schema coverage is only 33% (only 'cwd' and 'project' have descriptions in the schema). The description does not explain 'timeoutSeconds' or 'cwd' behavior comprehensively. It adds some value but does not fully compensate for missing 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 verb ('Runs'), the resource ('vendor/bin/phpunit'), and the context ('from a Laravel/Composer app root'). It effectively distinguishes from siblings like 'run_pest' (another test runner) and 'run_tests' (generic).

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 (e.g., 'run_pest' or 'run_tests'). The description does not specify prerequisites or scenarios where PHPUnit is preferred over other test runners.

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 no safety hints (all false). The description mentions auto-detection but fails to disclose behavioral traits like side effects, output generation, or prerequisites beyond 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 a single concise sentence that front-loads key purpose and parameters, earning its place without 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?

Given 6 parameters, no output schema, and no annotations, the description is too brief. It omits expected outcomes, error behavior, and prerequisites for a test runner tool.

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

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

Schema description coverage is low (33%). The description adds minimal meaning for 'filter' and 'cwd' but doesn't explain 'target', 'compact', or 'timeoutSeconds', which have no 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 title and description clearly state the tool runs tests, auto-detecting Laravel or npm, which distinguishes it from more specific siblings like run_phpunit or run_eslint.

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 for auto-detected test suites but does not explicitly guide when to choose this over alternative test runners like run_phpunit or run_eslint.

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 no safety hints beyond non-destructive. The description adds that it is a local call returning compact summaries, which is helpful. However, it does not disclose behavior on failure, required permissions, or whether it modifies files. Given no annotation burden, the description adds minimal extra context.

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

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

The description is a single sentence of 23 words, efficiently communicating the core functionality without any fluff or repetition.

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

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

Given the complexity of 8 parameters and the combined nature of the tool, the description is too sparse. It does not explain the different validation profiles, what each validation entails, or the format of step summaries. With no output schema, the description should provide more context but fails to.

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 only 25% and the description provides no parameter explanations. It does not help the agent understand parameters like 'profile', 'npmScripts', 'stopOnFailure', etc., which are crucial for correct usage.

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

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

The description clearly states it runs Git diff checks plus selected Composer, Laravel test, and npm script validations in one local call, returning compact step summaries. It distinguishes itself from individual sibling tools like run_tests or run_npm by emphasizing the multi-step aggregation.

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 for efficient multi-step validation ('reduce round-trips'), but does not explicitly state when to use this tool versus running individual validations separately, nor does it mention prerequisites 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?

Annotations already provide readOnlyHint=true. The description adds value by disclosing that generated, dependency, and secret files are ignored, and that ripgrep is used with a fallback. This goes beyond annotations, though performance details (e.g., result limits) are missing.

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, both front-loaded with essential information. The first sentence describes speed and fallback, the second explains exclusions. No redundant or unnecessary 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?

Despite a complex tool with 6 parameters and no output schema, the description lacks details about return format, pagination, or how to interpret results. An agent would need more context to use the tool correctly, especially regarding parameter semantics and output 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?

Schema coverage is only 17% (only 'project' parameter described). The description does not explain the meaning of key parameters like glob, regex, maxResults, or caseSensitive. For example, it doesn't clarify that 'regex' enables regex search or that 'maxResults' limits output. The description fails to compensate for low 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 clearly states the tool's function: high-speed code search using ripgrep with fallback. It also specifies what files are ignored, distinguishing it from siblings like search_files (file name search) and read_file (content reading). The verb+resource (search code) is specific and 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?

No explicit guidance on when to use this tool versus alternatives. The description implies it's for code content search, but doesn't mention scenarios where other tools (like search_files or read_file) would be more appropriate. No when-not or exclusions 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 already declare readOnlyHint=true and openWorldHint=false, and the description adds that it does not read file contents. This is consistent but does not disclose other behavioral aspects like performance limits, error handling, or the definition of 'safe glob'. The description adds modest value beyond 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 a single concise sentence that accurately front-loads the key purpose. It is efficient but could be slightly improved by including parameter hints without increasing length significantly.

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 has 6 parameters, low schema coverage, and no output schema. The description does not explain the return format (e.g., list of file paths), what constitutes a 'safe glob', or how maxResults and includeDirectories affect results. This leaves significant gaps for an AI agent to use correctly.

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

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

Schema description coverage is only 33% (path and project described in schema). The description does not add meaning for the other 4 parameters (query, mode, maxResults, includeDirectories), which are essential for usage. The phrase 'name substring or safe glob' hints at the mode parameter but provides no detail on syntax or constraints.

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 finds files by name substring or safe glob without reading contents. It specifies the verb 'finds', resource 'files', and method 'name substring or safe glob', which distinguishes it from content-searching siblings like search_code and read_file.

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

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

The description implies usage for file discovery only, by contrasting with 'without reading file contents'. While it does not explicitly state when not to use or name alternatives, the context of siblings and the phrase 'without reading file contents' provides clear guidance for when to use this tool over content-search 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?

Annotations indicate destructiveHint=true, and the description adds important behaviors: port 0 selects ephemeral port, occupied explicit ports are refused, and it does not adopt unrelated processes. This goes beyond annotations by detailing side effects and constraints.

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 primary purpose, and each clause adds value. There is 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?

Given the tool has 6 parameters, no output schema, and destructive nature, the description covers the most critical aspect (port behavior) and scope. It could mention what the tool returns (e.g., process ID or URL) but is otherwise adequate for an agent to use 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?

Schema description coverage is only 33%, but the description compensates by explaining the critical port behavior (port 0 = ephemeral, occupied port refused). It adds meaning beyond the raw schema, though it could mention more parameter constraints like host enum or readiness timeout.

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 specific language: 'Starts only a LocalDev-managed Laravel development server on a loopback host.' This clearly identifies the action (start), resource (Laravel development server), and scope (LocalDev-managed, loopback host), effectively distinguishing it from sibling tools like stop_local_process.

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 hints at appropriate usage by stating it only starts 'LocalDev-managed' servers and that 'unrelated processes are never adopted or stopped.' While it doesn't explicitly name alternatives, this provides clear boundaries for when 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?

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds the constraint about same project but does not elaborate on behavior (e.g., error handling, effect on stopped processes). This is acceptable given annotation coverage.

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

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

The description is a single sentence that is concise and front-loaded with the essential purpose. No superfluous 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?

With 3 parameters and no output schema, the description does not explain return values or timeoutSeconds usage. It is functional but minimally complete given the tool's simplicity.

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 only 33% (project has description, sessionId and timeoutSeconds lack). The description does not provide additional meaning for parameters beyond the schema. The sessionId pattern is in schema but not explained.

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 stops a process session created by start_local_process for the same project. It specifies the verb 'Stops' and the resource 'process session', and distinguishes from siblings like start_local_process and inspect_local_process.

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 indicates the tool is used only for process sessions created by start_local_process for the same project. It provides clear context for when to use it, though it does not explicitly mention alternatives or 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?

Annotations already declare idempotentHint=true and destructiveHint=false, so the description adds only the prerequisite context. It does not disclose behavior on missing parent directories or conflict handling, but with annotations covering safety, the bar is lower.

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 no unnecessary words. The usage context is front-loaded, and every sentence adds value. Ideal 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 core usage and prerequisites but lacks details on createParents, content constraints, return value, and error states. With 5 parameters and no output schema, more contextual information is needed for full completeness.

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 only 20% (project described). The description only adds semantics for expectedSha256, but does not explain path, content, createParents, or the format of expectedSha256. Low coverage forces description to compensate, but it only partially does so.

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 replaces files completely and mentions the prerequisite expectedSha256 from read_file. It distinguishes itself from siblings like create_file, apply_patch, and replace_text by specifying when a complete replacement is appropriate.

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 guidance on when to use it (complete replacement) and the prerequisite of expectedSha256 for existing files. It could be improved by explicitly mentioning alternatives like apply_patch for partial updates, but the context is clear enough.

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