ahk-mcp

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

The annotations indicate readOnlyHint=true, which the description aligns with by describing a listing operation. The description adds behavioral context about scanning configured directories and overriding A_ScriptDir, but doesn't detail aspects like performance, error handling, or how 'most recent' is determined (e.g., by modification time). With annotations covering safety, this provides moderate additional value.

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 brief and front-loaded with the core purpose, followed by a note on A_ScriptDir and a reference to another tool. It avoids unnecessary details, though the emoji and formatting slightly distract from pure conciseness. Overall, it's efficient with minimal waste.

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 moderate complexity (5 parameters, no output schema), the description covers the basic purpose and some context but lacks details on return format, sorting criteria for 'most recent,' or error scenarios. With annotations providing safety info, it's adequate but leaves gaps for full agent understanding.

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

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

The input schema has 100% description coverage, so parameters are well-documented there. The description mentions 'Supports overriding A_ScriptDir,' which loosely relates to the 'scriptDir' parameter, but doesn't add significant meaning beyond the schema. This meets the baseline for high 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 purpose: 'List the most recent AutoHotkey scripts from configured directories.' It specifies the verb ('List') and resource ('AutoHotkey scripts'), and mentions scanning directories. However, it doesn't explicitly differentiate from sibling tools like AHK_File_List or AHK_File_Active beyond a brief note about the latter.

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 context by mentioning 'Supports overriding A_ScriptDir' and referencing AHK_File_Active for setting a target file, implying this tool is for listing recent scripts rather than active file operations. However, it lacks explicit guidance on when to use this tool versus alternatives like AHK_File_List or AHK_File_View, leaving usage somewhat implied.

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