ahk-mcp

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

The annotations include destructiveHint: true, indicating potential data modification. The description adds valuable context beyond this by specifying the workflow steps (analyze, fix, verify, run) and the purpose of dryRun and summaryOnly parameters, which help the agent understand operational behavior. However, it does not mention rate limits, authentication needs, or detailed 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?

The description is highly concise and front-loaded, with two sentences that efficiently convey the core functionality and key usage tips. Every sentence adds value without redundancy, making it easy for an agent to quickly grasp the tool's purpose and important parameters.

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 (multi-step workflow with 6 parameters) and the presence of annotations (destructiveHint: true) but no output schema, the description is reasonably complete. It covers the workflow, fix types, and key parameters, though it could benefit from more detail on output format or error cases to fully compensate for the lack of output schema.

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

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

Schema description coverage is 100%, so the schema fully documents all 6 parameters. The description adds minimal semantics by mentioning dryRun and summaryOnly, but does not provide additional meaning beyond what the schema already describes (e.g., it doesn't explain interactions between parameters like autoFix and dryRun). Baseline 3 is appropriate as the schema handles most of the documentation burden.

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 performs an 'Analyze→fix→verify→run workflow in one call' with specific fix types (syntax, style, performance, all), distinguishing it from simpler analysis or editing tools in the sibling list like AHK_Analyze or AHK_File_Edit. It specifies a multi-step automated process rather than single 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 explicitly provides usage guidance with 'Use dryRun to preview, summaryOnly for minimal tokens,' indicating when to use these parameters for specific outcomes. It distinguishes this comprehensive workflow tool from alternatives like AHK_Lint (likely for linting only) or AHK_File_Edit (for manual edits).

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