Vale MCP Server

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

With no annotations provided, the description carries full burden and does well by disclosing key behaviors: it returns issues with locations/severity, and handles the error case when Vale is not installed with guidance. It doesn't mention rate limits, authentication needs, or whether this is read-only vs destructive, but provides useful operational 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?

Two efficient sentences with zero waste. First sentence states purpose and output, second handles error case. Every sentence earns its place with important operational 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?

For a single-parameter tool with no annotations and no output schema, the description provides good completeness: purpose, behavior, error handling. It could benefit from more detail about the return format (structure of issues) and whether this is a read-only operation, but covers the essential context well.

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

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

Schema description coverage is 100% with the single 'path' parameter well-documented in the schema. The description adds minimal value beyond the schema by mentioning 'specific path' and 'file to check', but doesn't provide additional syntax, format details, or constraints beyond what's already 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?

The description clearly states the specific action ('lint a file'), target resource ('file at a specific path'), and purpose ('against Vale style rules'). It distinguishes from sibling tools by focusing on file checking rather than status or synchronization operations.

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

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

The description implies usage context through the mention of Vale style rules and installation requirements, but doesn't explicitly state when to use this tool versus the 'vale_status' or 'vale_sync' siblings. No explicit alternatives 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?

With no annotations provided, the description carries the full burden and effectively discloses behavioral traits: it describes what the tool returns ('installation status, version if available, and installation instructions for the current platform'), including output format and context for missing installations. It doesn't mention error handling or performance aspects, but covers core behavior well.

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 front-loaded with the main purpose, followed by usage guidance and return details in two concise sentences. Every sentence adds value without waste, making it efficient 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 low complexity (0 parameters, no output schema, no annotations), the description is complete enough: it explains the tool's purpose, usage context, and return values. It could slightly improve by specifying error cases or platform details, but it adequately covers the essential context for this simple diagnostic 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?

Since there are 0 parameters and schema description coverage is 100%, the baseline is 4. The description adds no parameter information, which is appropriate given the lack of parameters, so it meets expectations without redundancy.

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 with specific verbs ('Check if Vale is installed and accessible') and resource ('Vale (vale.sh)'), distinguishing it from sibling tools like 'check_file' and 'vale_sync' by focusing on installation status rather than file validation or synchronization.

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 provides explicit usage guidance: 'Use this first if other Vale tools fail' indicates when to use this tool versus alternatives, and it implies a troubleshooting context, offering clear direction for the agent.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains that the tool downloads packages based on configuration and mentions it reads '.vale.ini', which is useful context. However, it doesn't disclose important behavioral aspects like whether this requires network access, what happens if downloads fail, or if there are any side effects on existing files.

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 perfectly concise with three sentences that each serve a distinct purpose: stating what the tool does, when to use it, and how it works. There's no redundancy or wasted words, and the information is front-loaded with the most important details first.

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 (single optional parameter, no output schema, no annotations), the description provides good contextual coverage. It explains the purpose, usage scenario, and basic operation. The main gap is the lack of output information or error handling details, but for a configuration-based download tool, this is reasonably 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?

The schema description coverage is 100%, so the schema already documents the single parameter completely. The description doesn't add any additional parameter semantics beyond what's in the schema - it mentions the configuration file but doesn't provide additional context about the parameter's usage or implications. This meets the baseline expectation when schema coverage is high.

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 specific action ('Download Vale styles and packages') and the method ('by running "vale sync"'), distinguishing it from sibling tools like 'check_file' and 'vale_status'. It provides a concrete verb+resource combination that leaves no ambiguity about what the tool does.

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 states when to use this tool ('Use this when you see errors about missing styles directories (E100 errors like "The path does not exist")'). It provides a clear trigger condition and distinguishes it from alternatives by specifying the specific error scenario it addresses.

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