ahk-mcp

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

The description adds valuable behavioral context beyond annotations. While annotations indicate openWorldHint=true and destructiveHint=true, the description elaborates on what validation entails (detecting syntax errors, runtime errors, unset variable references) and explains the watch mode's auto-validation behavior. However, it doesn't address potential side effects of the destructive hint or rate 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 well-structured and efficiently organized with clear sections (Modes, Examples, Error Patterns). Each sentence serves a distinct purpose: establishing the core functionality, explaining modes, providing usage examples, and detailing error detection. There's no redundant information, and the content is front-loaded with the main purpose.

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

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

Given the tool's complexity (6 parameters, two operational modes, no output schema), the description provides substantial context about functionality, usage patterns, and error detection. However, it doesn't explain return values or error formats, which would be helpful since there's no output schema. The annotations cover some behavioral aspects, but more detail on the destructive nature would improve 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?

With 100% schema description coverage, the baseline is 3, but the description adds meaningful context through examples that illustrate parameter interactions (e.g., mode='watch' with enabled=false to stop watching). It clarifies how parameters like 'code' and 'filePath' relate to different modes, providing practical semantics beyond the schema's technical descriptions.

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

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

The description clearly states the tool's purpose: validating AHK v2 code with optional watch mode for auto-validation on save. It specifies the exact action (validate) and resource (AHK v2 code/files), and distinguishes itself from siblings like AHK_Lint or AHK_Analyze by focusing on validation with watch capabilities rather than broader analysis or 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 explicit usage guidelines through the 'Modes' section, clearly differentiating between 'validate' (one-shot validation) and 'watch' (auto-validate on save). The examples section further illustrates when to use each mode with specific parameter combinations, offering practical guidance for different scenarios.

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