validate-grammar

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

With no annotations provided, the description takes on the full burden of behavioral disclosure. It transparently lists the types of issues detected (undefined rules, unused rules, left recursion, fragment misuse, naming issues) and the return format (severity, descriptions, line numbers, rule names). The read-only nature of validation is implied, though not explicitly stated, but the disclosure is sufficient for safe 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?

The description is well-structured with clear sections ('When to use', example, detected issues, return format) and uses bullet points for readability. It is slightly longer than necessary but every part contributes to understanding, with no repetitive or filler content.

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 absence of an output schema, the description compensates by describing the return value (list of issues with severity, line numbers, etc.). It covers usage context, an example, and detailed detection categories. However, it does not elaborate on how parameters interact (e.g., whether grammar_content and from_file are mutually exclusive) or when base_path becomes necessary beyond a single mention. For a 5-parameter tool, this is solid but not exhaustive.

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% per context signals, so the baseline is 3. The description adds minimal parameter-specific meaning beyond the schema; it shows an example using from_file but does not explain relationships or trade-offs between grammar_content, from_file, and base_path. The schema descriptions themselves already document each parameter, so the description adds little extra value.

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 'Validates ANTLR4 grammar syntax and detect common issues', pairing a specific verb with a concrete resource. It distinguishes itself from siblings like compile-grammar and analyze-grammar by enumerating the exact validation checks performed (undefined rules, unused rules, left recursion, 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 includes an explicit 'When to use' section, recommending use after changes or for diagnosing problems in existing grammars. While it gives clear context, it does not mention when to avoid this tool or explicitly compare against sibling tools like analyze-grammar or smart-validate, missing the 'when not to use' part for a top score.

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