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

With no annotations provided, the description carries full behavioral burden. It discloses useful details like validation of mode name format and prevention of duplicate mode names. However, it omits potential side effects (e.g., file overwriting, permissions) and error behaviors, which are important for a mutation tool.

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-organized with 'When to use', 'Features', and 'Example' sections. It is front-loaded with the main purpose and remains reasonably sized. The examples are useful but could be trimmed slightly without losing value.

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?

The tool has 6 parameters and no output schema. The description explains the main use cases and features, but it does not clarify more complex aspects like the output_mode parameter (full/diff/none) or the exact relationship between from_file and grammar_content. For a moderately complex tool, this leaves some gaps.

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 baseline is 3. The description adds examples and mentions optional positioning, but it does not significantly enhance the existing parameter descriptions. The examples clarify parameter combinations but do not add new semantic meaning beyond 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 begins with a specific verb and resource: 'Add a new lexer mode declaration to an ANTLR4 grammar.' This clearly distinguishes it from sibling tools like add-rule or add-parser-rules, which operate on rules rather than mode declarations.

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 'When to use' section explicitly states the intended context: 'Creating new modes for context-sensitive tokenization.' It provides clear guidance on when to invoke this tool, though it does not name alternative tools or explicit exclusion criteria.

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, the description carries the full burden and does excellently: it discloses alphabetical insertion, duplicate prevention, partial success with per-rule reporting, atomic per-rule operations, and file write confirmation. This is exemplary for a mutation tool.

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-organized with headers and bullets, and each section (summary, when-to-use, example, features, returns) earns its place. It's longer than minimal, but the extra length is used for genuinely useful detail like the example and return format.

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 5 params and no output schema, the description covers return values (summary, per-rule results, modified grammar, file confirmation), key behaviors (partial success, duplicate prevention), and an illustrative example. This gives an agent everything needed to select and invoke the tool correctly.

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%, so the baseline is 3. The description adds a concrete example showing the rules array structure (name, pattern, skip, channel) and clarifies the relationship between from_file and write_to_file. This goes beyond the schema and earns a 4.

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 starts with a clear verb-resource statement: 'Add multiple lexer rules to a grammar in a single operation (bulk add).' It explicitly specifies 'lexer' and 'multiple', which distinguishes it from single-rule tools like add-rule and parser-rule tools like add-parser-rules.

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 'When to use' section gives three concrete scenarios: initial grammar structure, adding multiple related tokens, and importing rules. It doesn't explicitly name alternative tools or say when not to use this tool, but the context is clear enough for an agent to choose it appropriately for bulk lexer additions.

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, the description fully discloses important behaviors: alphabetical insertion, duplicate prevention, partial success, per-rule reporting, and atomic per-rule operations. This is detailed transparency for a mutation tool.

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-organized with clear sections: intro, when-to-use, example, features, returns. Every sentence contributes value, with no fluff or repetition.

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 no output schema, the description explicitly describes return values (summary, per-rule results, modified grammar, file confirmation). The example and feature list cover the key use cases, making this complete for a bulk operation 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?

Schema coverage is 100%, but the description adds a rich example showing the rules array structure and write_to_file usage, which clarifies the relationship between parameters and expected behavior beyond the schema alone.

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 function: 'Add multiple parser rules to a grammar in a single operation (bulk add).' This distinguishes it from single-rule tools like add-rule and other sibling tools. The phrase 'bulk add' and the detailed example reinforce the specific scope.

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?

Provides an explicit 'When to use' section mentioning setup, adding multiple related rules, and prototyping. It does not explicitly mention when not to use or alternatives, but the context is clear and actionable.

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, the description carries full burden and excels: it discloses automatic type detection, default alphabetical sorting, custom positioning with insert_after/insert_before, duplicate prevention, optional file persistence, diff output mode, and return behavior. This goes far beyond a generic action statement.

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 a core summary, examples, and feature list. However, the Features section partially repeats the examples and the examples are numerous, making it longer than strictly necessary. Still, the content is valuable and front-loaded with the primary 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?

For a 13-parameter tool with no output schema, the description is remarkably complete: it covers return values, output modes, all parameter categories, file persistence, and provides a variety of examples covering lexer, parser, fragment, skip, channel, positioning, and return types. It leaves no major ambiguity.

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?

Although schema coverage is 100%, the description adds substantial practical meaning by explaining naming conventions for rule_name, giving per-parameter examples (skip, channel, fragment, return_type, positioning), and illustrating lexer vs parser usage. This transforms abstract schema fields into actionable guidance.

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 'Add a new lexer or parser rule with automatic type detection and positioning.' The verb 'Add' plus resource 'lexer or parser rule' makes purpose explicit, and the auto-detection and positioning details distinguish it from specialized siblings like add-parser-rules and add-rule-to-mode.

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?

Includes an explicit 'When to use' section: 'Add any rule to your grammar - lexer tokens or parser rules.' This provides clear context but does not mention alternatives or cases where specialized tools like add-parser-rules should be preferred, so it lacks explicit when-not guidance.

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 fully discloses key behaviors: alphabetical sorting, duplicate prevention, partial success, atomic per-rule operations, and per-rule reporting. Also explains return values and file write behavior, exceeding what annotations would typically convey.

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 for when to use, an example, features, and returns. Although lengthy, every sentence contributes value and there is no redundancy or fluff.

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 complex bulk operation with mixed rule types and partial success, the description covers usage context, behavioral details, return format, and a concrete example. Without an output schema, it still explains what the caller receives, making the description 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?

Since schema description coverage is 100%, the schema already documents all parameters. The description adds an example demonstrating the rules array structure, but no additional parameter semantics beyond what the schema provides, so the baseline 3 is appropriate.

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?

States clearly that it adds multiple mixed lexer and parser rules in a single operation, distinguishing it from singular add-rule sibling. The verb 'Add' and resource 'multiple mixed parser and lexer rules' are specific and unambiguous.

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?

Provides explicit 'When to use' scenarios such as setting up complete grammar structure or prototyping, but does not explicitly name alternatives or state when not to use the tool. Clear context without exclusions.

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?

No annotations are provided, so the description carries the full burden. It discloses useful behaviors: places rule in correct mode, validates mode exists, supports all lexer rule options, and auto-sorts within the mode. It also shows example usages with action. It does not mention potential error behavior or return format, but the key behavioral traits are covered.

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 a clear opening statement, a 'When to use' section, a bulleted feature list, and two illustrative examples. It is not overly verbose, and the front-loaded purpose makes it easy to grasp quickly. The examples add useful detail but could be seen as slightly redundant.

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 complexity of the tool (11 parameters, no annotations, no output schema), the description does a good job of covering the essential usage context. It explains what the tool does, when to use it, and provides examples. It doesn't fully explain edge cases like the relationship between from_file and grammar_content, or the meaning of output_mode, but the schema covers these and the description is reasonably complete for practical use.

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 already provides 100% coverage of parameter descriptions, so the baseline is 3. The description adds value by providing concrete examples that show how rule_name, pattern, mode_name, action, and write_to_file are used together. This clarifies the intended semantics beyond individual schema 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: 'Add a lexer rule to a specific mode in an ANTLR4 grammar.' It uses a specific verb (add) and resource (lexer rule to a mode), and this distinguishes it from siblings like add-rule (general) and move-rule-to-mode (moving existing rules).

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 a 'When to use' section: 'Adding tokens that only apply in specific lexical contexts.' This gives clear guidance on when this tool is appropriate, and the examples illustrate usage. It doesn't explicitly state when not to use it or mention alternatives, but the context strongly implies it's for mode-specific rules rather than global rules.

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 transparency burden. It discloses core behaviors: automatic uppercase/underscore naming, {NAME} placeholder support, reliance on 'existing bulk add infrastructure', and a clear return summary including per-rule status and modified grammar. It lacks specifics on failure handling but is adequate for an additive tool.

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 longer than minimal, but every section (when-to-use, examples, features, returns) earns its place. It's front-loaded with the main purpose, uses headers for scannability, and avoids filler. Slightly verbose but 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?

For a 9-parameter tool with no output schema, the description covers the what, when, and returns sufficiently. It illustrates usage with multiple examples and lists return values. It doesn't address edge cases like error handling or file I/O interactions, but given schema coverage and the additive nature, it's 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?

Schema coverage is 100%, so baseline is 3. The description adds value beyond schema by explaining the {NAME} placeholder convention, providing concrete examples for base_names and preceding_tokens, and noting default pattern behavior. It doesn't detail every parameter but compensates for the core ones.

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 opens with a specific verb+resource phrase: 'Add multiple similar lexer tokens at once using template-based generation.' It clearly distinguishes from sibling tools like add-rule or generate-tokens-from-pattern by emphasizing batch template-based creation.

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 'When to use' section provides explicit contexts (e.g., 'Add multiple tokens that follow a similar pattern', 'Generate tokens for command sequences'). However, it does not name alternatives or provide when-not-to-use guidance, so it's clear but without exclusions.

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, the description carries full burden, and it does well: it details detection capabilities by severity (ERROR vs WARNING), lists return contents (issues with severity, type, rule name, line number), and mentions suggestions and summary counts. It doesn't explicitly state that the tool is read-only or describe side effects, but its 'Analyze' and 'Detects' phrasing implies non-mutating behavior.

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 lengthy but well-structured with clear headers, numbered detection capabilities, options, returns, and an example. Every section adds necessary information and directly supports tool usage. It is front-loaded with purpose and when-to-use, ensuring the most critical details are immediately visible.

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 (8 params, no output schema, no annotations), the description is remarkably complete. It covers purpose, use cases, detection patterns, configurable options, return values, and an example invocation. It doesn't leave major gaps for the agent to infer, and the lack of an output schema is mitigated by a textual description of the return structure.

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?

Even though schema coverage is 100% with parameter descriptions, the description adds significant semantic value. For example, it explains what each check does (e.g., 'Identical Alternatives' detects duplicate alternatives) and clarifies 'minPrefixLength' as a threshold. The example usage reinforces parameter names and default behaviors, going beyond the schema's one-line 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 a specific action: 'Analyze grammar for common ambiguity patterns that may cause conflicts at runtime.' This sets it apart from sibling tools like analyze-grammar (general analysis) and validate-grammar (validation). The scope is precise, focusing on ambiguity detection.

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 an explicit 'When to use' section: 'Before compiling grammar, after making changes, or when diagnosing parser warnings.' This gives clear usage context. However, it does not explicitly mention when not to use it or direct users to alternative tools (e.g., detect-redos for regex-specific issues), so it falls short of a perfect 5.

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 delivers by enumerating six specific detection categories (high-branching rules, tilde negation, lexer mode opportunities, greedy loops, deep recursion, token prefix collisions) and four return elements including severity levels. It lacks side-effect/permission details, but these are largely irrelevant for a read-only analysis tool.

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?

Well-structured markdown with clear sections (purpose, when to use, detects, returns, example). The key purpose is front-loaded in the first sentence, and each bullet list provides specific, actionable detail without redundancy or filler.

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?

The description covers the full context: what it does, when to use it, what issues it detects, what it returns (important given the absence of an output schema), and how to invoke it with an example. Minor gap: since both parameters are optional, it is unclear how the tool obtains the grammar when neither is provided.

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% — both parameters are fully described in the schema — so the baseline is 3. The description adds only an example showing from_file usage ('from_file: "MyGrammar.g4"'), which marginally demonstrates invocation format but adds no semantic meaning beyond what the schema already provides.

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 first sentence states a specific action ('Analyze grammar') with a clear scope ('performance bottlenecks and optimization opportunities'). This clearly distinguishes it from sibling tools like analyze-ambiguities, analyze-lexer-modes, and detect-redos, which target different aspects of grammar analysis.

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 naming three use cases: performance optimization, grammar refactoring, and large grammar analysis. However, it does not name alternative tools or state when not to use it, so it falls short of the 'explicit when/when-not/alternatives' bar.

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?

Since annotations are not provided, the description carries the full burden of behavioral transparency. It details the return types such as 'All parser rules with definitions and line numbers' and 'Validation issues,' and explicitly describes the effect of load_imports on merging rules. It does not mention any side effects or error behavior, but for a read-only analysis tool this is sufficient – no contradictions.

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 structured in sections (goal, when to use, multi-file support, examples, returns) and is front-loaded with the core purpose. It is somewhat lengthy but each section contains useful information; the returns list is particularly informative. It earns a 4 rather than 5 because it could be tightened without losing meaning.

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?

With no output schema, the description compensates by enumerating the categories of results (grammar name/type, parser rules, lexer rules, references, imports, options, validation issues) and noting behavioral flags like load_imports. It also provides concrete example usage for file-based and multi-file workflows. However, it does not specify the exact output structure (e.g., field names), leaving some ambiguity for the agent, so a 4 is appropriate.

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 all five parameters already documented in the schema. The description adds an example of using from_file and base_path together and notes that load_imports=true resolves imported grammars, but this does not go beyond the schema's explanation of 'automatically load and merge imported grammars.' Thus it provides only marginal additional 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 it 'Analyze an ANTLR4 grammar file and extract its complete structure,' using a specific verb and resource. It further distinguishes itself as the 'First step when exploring an unfamiliar grammar,' which sets it apart from siblings like list-rules or validate-grammar by emphasizing complete structural extraction.

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 'When to use' section explicitly positions this as the first step for exploring unfamiliar grammars, understanding architecture, or extracting metadata. However, it does not name specific alternative tools or exclusion conditions, so it lacks explicit when-not-to-use guidance, making it clear context but no exclusions.

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?

No annotations are provided, so the description must carry the transparency burden. It describes what the tool does (lists, identifies, detects) and its return structure, but it does not explicitly state that it is read-only or mention any side effects, limitations, or error behavior. This is a partial disclosure.

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 headers and bullet points, and the main purpose is front-loaded. However, it includes a lengthy background explanation of lexer modes that is not strictly necessary for using the tool. It could be tightened without losing value.

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?

With no output schema, the 'Returns' section is helpful and describes the main output fields. However, it does not cover edge cases like invalid grammar input, missing parameters, or how the tool behaves when both from_file and grammar_content are used. The description is adequate but not fully complete for all usage scenarios.

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% since both parameters have descriptions. The description adds an example usage for from_file but does not clarify the relationship or precedence between the two parameters (e.g., which is used if both are supplied, or what happens if neither is provided). This leaves some ambiguity beyond 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 opens with a clear, specific statement: 'Analyze lexer mode structure in ANTLR4 grammars.' It distinguishes itself from siblings by listing features (lists all modes, entry/exit points, detects issues) that go beyond what analyze-mode-transitions or list-mode-rules might offer.

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?

Provides an explicit 'When to use' section with concrete scenarios: understanding mode-based tokenization, debugging mode transitions, documenting mode structure. It does not explicitly compare to alternative tools or state when not to use, but the context is clear enough.

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?

Since no annotations are provided, the description carries the full burden. It discloses the tool's analysis behavior in detail: builds a complete transition graph, detects circular transitions, checks balanced push/pop, identifies modes without exit points, and suggests improvements. It also clearly describes the return structure, making the tool's behavior transparent. However, it doesn't explicitly state that it is read-only (non-destructive), though this is implied by its analytical nature.

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-organized with clear sections: purpose, when-to-use, features, returns, and example. Every sentence contributes meaningful information, and the bulleted features improve scannability without unnecessary verbosity.

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?

The description fully covers the tool's context: it explains what it does, when to use it, its key features, the structure of its return values (transitions, issues, suggestions), and provides a usage example. With no output schema present, the description adequately compensates by detailing the return fields. No important aspects appear missing.

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 already provides 100% coverage, with both parameters (from_file and grammar_content) having descriptions. The tool description adds an example usage with from_file, but does not introduce new semantic meaning beyond the schema. Thus, the baseline of 3 applies.

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 a specific verb ('Analyze') and resource ('mode transition graph'), and further specifies it detects issues in ANTLR4 lexer modes. This distinguishes it from siblings like analyze-grammar or list-mode-rules, and the 'When to use' section reinforces the specific function.

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 'When to use' section explicitly lists concrete use cases: debugging mode switching logic, ensuring balanced push/pop, detecting circular transitions. This provides clear context for when this tool is appropriate, though it does not explicitly mention alternatives or when-not-to-use, which would elevate it to a 5.

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, the description carries the full burden and does so thoroughly. It discloses warmup iterations for JIT, multiple iterations for statistical accuracy, a performance rating framework, and optimization suggestions—giving the agent a comprehensive behavioral model.

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 sections for when-to-use, measures, features, parameters, and an example. Every section earns its place, and the format makes it easy for an agent to parse quickly.

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?

Without an output schema, the 'Measures' section clearly explains expected return values (tokens, parse times, throughput, rating). The features and example make this a complete standalone description for a complex benchmarking 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?

Schema coverage is 100%, but the description adds meaningful relationships: it clarifies that grammar_content and from_file are alternatives, and provides a concrete example combining from_file with input. This goes beyond the schema's flat property list.

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 opens with a specific verb+resource: 'Benchmark grammar parsing performance with sample input.' This clearly distinguishes the tool from siblings like compare-grammars or native-benchmark, and the 'Measures' section further clarifies its scope.

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 'When to use' section explicitly lists performance testing, grammar version comparison, and optimization validation. It provides clear usage context but does not explicitly exclude overlapping tools like profile-parsing or analyze-bottlenecks, so it stops short of a full 5.

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, the description carries the full transparency burden. It discloses the types of checks performed, the return structure (issues with severity, score, suggestions), and provides an example. It does not explicitly state it is read-only, but the nature of 'check-style' implies no side effects. The description gives sufficient insight into behavior.

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, Checks, Returns, Example) and bullet-pointed check items. It is concise, front-loaded with the core purpose, and every sentence adds value without redundancy.

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?

The description provides a comprehensive overview: purpose, when to use, what checks are performed, what is returned, and an example. There is no output schema, so the description appropriately explains return values. It could mention that grammar can also be provided via grammar_content, but the schema covers that, so the description remains 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 covers both parameters (from_file and grammar_content) at 100%, so the schema already documents them. The description adds an example using from_file, which is helpful, but it does not explain when to use one parameter over the other. Since schema coverage is high, a baseline of 3 is appropriate.

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 'Check grammar style and best practices with quality scoring', which uses a specific verb (check) and resource (grammar style and best practices) and distinguishes it from sibling tools. It also lists concrete checks (naming conventions, best practices, maintainability) that further clarify its unique role.

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 a 'When to use' section listing clear contexts: 'Code review, maintaining grammar quality, enforcing conventions.' However, it does not explicitly mention alternatives or when not to use this tool, so it lacks exclusions and direct sibling comparisons.

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?

No annotations are provided, so the description must carry the full burden. It clearly discloses the output behavior by listing the returned categories (common, unique, modified rules, statistical summary) and implies a read-only operation through the verb 'compare.' It does not mention potential error conditions or side effects, but for a comparison tool this is acceptable.

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 a clear first sentence, a 'When to use' section, an example, and a bulleted output list. It is slightly longer than necessary, but every section adds value and the information is easy to scan.

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?

The tool has four parameters with a logical mutual exclusivity (file path vs. content), but the description does not explicitly state that users must provide either from_file1/from_file2 or grammar1_content/grammar2_content. The output schema is absent, so the description's output list helps, but the missing requirement explanation leaves a notable gap.

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 covers all four parameters descriptively (e.g., 'overrides grammar1_content'), so the baseline is 3. The description adds an example usage with actual file paths, which helps clarify parameter format, but it does not introduce new semantic details beyond 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 tool's function: 'Compare two ANTLR4 grammars side-by-side to identify differences.' It uses a specific verb ('compare') and resource ('two ANTLR4 grammars'), which distinguishes it from sibling tools like compare-profiles, which compares profiles rather than grammars.

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 use cases: 'Understand changes between versions, merge grammars, or analyze variations.' It also includes an example invocation. However, it does not explicitly mention alternatives or state when not to use this tool, so it falls short of a 5.

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, the description carries full responsibility. It discloses return values (metrics, verdict, differences, recommendations) and provides a detailed example output, giving agents a clear behavioral picture. It doesn't mention error handling or assumptions, preventing a 5.

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-organized into clear sections (purpose, when-to-use, parameters, returns, example). The example is illustrative but makes it somewhat long. Each section earns its place, though brevity could be improved.

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 moderate complexity (two nested objects, no output schema), the description compensates well by listing return categories and giving a concrete example. It could be more exhaustive about edge cases but largely covers necessary context.

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 already covers both parameters (baseline/optimized) with descriptions, giving a baseline of 3. The tool description adds value by specifying the source (from profile-parsing) and showing a concrete example of how profiles are structured, pushing it to 4.

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 opens with a clear action: 'Compare two parsing profiles to measure optimization impact.' This specific verb+resource phrase distinguishes it from siblings like compare-grammars and ties to the profile-parsing workflow.

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?

A dedicated 'When to use' section lists concrete scenarios: validating optimizations, A/B testing, and regression testing. However, it does not explicitly state when not to use it or name alternative tools, so it falls just short of a 5.

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, the description must carry the full behavioral burden. It discloses the nature of diagnostics (error/warning with line/column), import/tokenVocab loading behavior, compile timing, and return contents. It does not explicitly state whether the operation is read-only, but 'checks' implies no mutation, so the transparency is strong.

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 a bold 'When to use' section, bulleted supports, an example, and a returns line. It is slightly verbose, but every section earns its place, and the key verb is front-loaded. Minor redundancy with schema details prevents a 5.

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?

Despite no output schema and no annotations, the description covers the tool's purpose, usage guidance, supported features, an example, and explicit return values (success/failure, diagnostics, timing, generated artifacts). This is fully sufficient for an agent to select and invoke the tool correctly.

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%, so the baseline is 3. The description adds relational meaning by linking load_imports=true and from_file to multi-file imports/tokenVocab, and the example usage clarifies the recommended parameter combination. This goes beyond the raw schema definitions.

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 opens with 'Run native ANTLR4 compilation checks for grammar syntax/tooling errors,' which uses a specific verb and resource. It distinguishes this tool from the sibling validate-grammar by emphasizing 'native' and 'tooling errors,' making the purpose clear and unique.

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 includes an explicit 'When to use' section that names validate-grammar as an alternative and specifies the condition: 'when validate-grammar looks clean but ANTLR toolchain still fails.' This directly tells the agent when to prefer this tool over a sibling.

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, the description carries the full burden but only partially discloses behavior. It mentions creating lexer/parser/combined grammars, including boilerplate rules, and adding modes with placeholder comments, which is useful. However, it does not explain what the tool returns (e.g., a string of grammar text), whether it writes to files, or any side effects. The examples show inputs but not output format, so an agent might be uncertain about the result.

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 a purpose line, when-to-use, features, and examples. It is longer than the two-sentence ideal, but the extra length is justified for a tool with multiple options. The front-loaded purpose and clear section headings make it easy to scan. Every section contributes, though the 'Features' section partly restates the 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 no output schema and no annotations, the description provides a solid overall picture: purpose, usage scenarios, features, and examples. It does miss explicit mention of the return value or output format, which would be helpful for an agent. However, the examples strongly imply the generated grammar template is the output, and the tool is relatively simple. The description is complete enough for basic selection and invocation.

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 already documents each parameter. The description adds value by providing three concrete examples that show how parameters combine (e.g., modes array, include_boilerplate). These examples clarify usage beyond the schema's field descriptions, especially for the modes parameter. This goes beyond the baseline 3 but doesn't add syntax-level details.

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 opens with a specific verb+resource: 'Create a new ANTLR4 grammar from scratch with optional mode structure.' It clearly distinguishes this tool from siblings like add-rule or validate-grammar by focusing on whole-grammar creation. The 'When to use' section reinforces the purpose with explicit use cases.

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 'When to use' section explicitly lists three appropriate scenarios, providing clear context for when to choose this tool. It does not explicitly name alternatives or say when NOT to use it, but the examples cover the main variation (types and modes). This earns a 4, not 5, because exclusions are only implied by the sibling list.

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, the description carries the burden of behavioral disclosure. It explains the anti-patterns detected, provides real-world impact, and states the return type ('List of incomplete parsing patterns with suggestions'). It does not mention side effects, permissions, or error behavior, but for a non-mutating analysis tool this is strong coverage.

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 structured with clear headings (when to use, anti-patterns, impact, recommendations) and front-loaded with the core purpose. It is longer than necessary but each section adds value, and the use of bullet points and examples improves readability.

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?

The tool has only two optional parameters and no output schema. The description provides enough context for usage: it explains what the tool does, when to use it, and what it returns. It could be slightly more detailed about return structure or edge cases, but for the tool's complexity it is sufficiently 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 input schema already describes both parameters ('from_file' and 'grammar_content') with 100% coverage. The description does not add new parameter-specific semantics beyond the schema, so the baseline of 3 applies.

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 opens with a specific verb and resource: 'Detect incomplete parsing patterns (anti-patterns that discard content).' It clearly distinguishes this from sibling tools like validate-grammar or detect-redos by focusing on anti-patterns that discard content, with concrete examples.

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?

Provides a clear 'When to use' section stating it is for grammars that parse configs but don't capture structure, or use placeholder patterns. It gives clear context but does not explicitly name sibling tools as alternatives or state when not to use it, so it falls short of a 5.

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 discloses the return format ('List of suspicious patterns with suggestions and reasoning') and provides illustrative examples of detected patterns. It does not explicitly state whether it modifies the grammar, but given the verb 'detect' and the return description, the read-only nature is implied. It could benefit from a non-destructive statement but currently offers good transparency.

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 structured with clear sections (When to use, Common patterns detected, Real-world example, Returns). While it is longer than a typical two-sentence description, every section adds value by providing concrete examples and reasoning. The front-loaded purpose sentence is strong. It is well-organized and not unnecessarily verbose.

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?

No output schema exists, but the description provides a clear return description. For a detection tool with two simple parameters, the description covers purpose, usage context, common patterns, an example, and return behavior. It lacks explicit edge-case or error-handling information, but given the tool's complexity, it 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 input schema already provides descriptions for both parameters (from_file and grammar_content), achieving 100% coverage. The tool description does not add additional parameter semantics or mention how the parameters are used. According to the rubric, a baseline of 3 is appropriate when schema coverage is high and the description does not compensate further.

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 function: 'Detect suspicious quantifier patterns that may prevent parsing real configs.' It specifies a specific verb, resource, and scope, and distinguishes itself from sibling tools like fix-quantifier-issues by focusing on detection rather than fixing. The concrete patterns and examples reinforce a distinct purpose.

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 ('After seeing "unrecognized syntax" warnings or when rules don't match multi-line configs'), providing clear context for usage. However, it does not explicitly mention alternatives or cases where this tool should not be used, such as referencing fix-quantifier-issues as the follow-up step.

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, the description carries the full burden. It clearly discloses what is detected and what is returned (list with severity, line numbers, suggestions). It does not explicitly state whether the tool is read-only or whether grammar must be valid, but the analysis nature implies no side effects. The detailed output description adds transparency.

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: purpose, when to use, detections, returns, and an example. It is informative without being verbose, each sentence adds value, and it is front-loaded with the core 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 (multiple detection patterns) and no output schema, the description adequately explains return values and usage context. It includes an example and covers when to use. It could be slightly improved by explicitly stating it works on ANTLR lexer grammars, but the .g4 example implies this.

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 baseline is 3. The description provides a usage example with from_file, but does not elaborate on grammar_content beyond the schema. It adds marginal value with the example but does not significantly enhance parameter understanding.

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 states 'Detect ReDoS vulnerabilities in lexer patterns' with a specific verb and resource. It lists concrete detection patterns (nested quantifiers, overlapping alternatives) and includes an example, distinguishing it from sibling analysis tools like validate-grammar or detect-quantifier-issues.

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?

Provides explicit 'When to use' with three scenarios: security audit, performance optimization, validating lexer patterns. However, it does not mention when not to use or explicitly compare to alternatives like detect-quantifier-issues, so it falls short of a full 5.

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, the description carries the full burden. It discloses key behaviors: copies all rules, optional prefix, and automatic creation of a new mode declaration. Examples illustrate naming behavior. However, it does not mention side effects like file writing or output modes, which are left to the schema.

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-organized with sections for purpose, when-to-use, features, and examples. Every sentence serves a purpose, and the examples are concise but informative. No fluff or redundancy.

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 has 7 parameters and no output schema, the description covers the core functionality thoroughly with examples. It does not explain all parameter interactions (e.g., grammar_content vs from_file, output_mode behavior), but the schema provides descriptions for those, so the overall context is sufficient for an agent to select and invoke the 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?

Schema coverage is 100%, giving a baseline of 3. The description adds meaning through examples that clarify the relationship between source_mode, new_mode, and prefix_rules, including how prefixed rule names are generated. Other parameters are adequately described in the schema itself.

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 opens with 'Duplicate a lexer mode with all its rules,' using a specific verb and resource. It clearly differentiates from siblings like add-lexer-mode or move-rule-to-mode, which handle single modes or rules.

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 a 'When to use' section listing concrete scenarios: 'Creating similar modes, refactoring mode structure, creating mode templates.' It does not explicitly mention when not to use or alternative tools, but the context is clear.

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, the description carries the full burden of behavioral disclosure. It describes the output format (complete Markdown document), enumerates the sections included (overview, parser rules, lexer rules, etc.), and provides an example usage. While it doesn't explicitly state side-effect-free behavior, the nature of 'generate' plus the focus on documentation implies a non-destructive 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 bolded sections and bullet lists, making it scannable. Every sentence adds value: purpose, when-to-use, example, output contents, and output format. It's appropriately sized for the tool's complexity.

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?

The description addresses the tool's purpose, usage context, example, output format, and the content included in the generated documentation. Since there is no output schema, this textual explanation adequately covers what the tool returns. It provides enough context for an agent to select and invoke the tool correctly.

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 already provides descriptions for both parameters, giving 100% coverage, so the baseline is 3. The description adds a concrete example using 'from_file' but doesn't clarify the relationship between the two optional parameters or handling when both/neither are provided.

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 opens with a specific verb ('Generate') and resource ('comprehensive Markdown documentation for your grammar'), clearly stating the tool's function. It distinguishes itself from sibling tools by focusing on Markdown export, while also listing explicit use cases like README creation and reference docs.

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 'When to use' section explicitly lists four concrete scenarios: creating README files, generating reference documentation, documenting grammar structure, and sharing grammar specs. It provides clear context for when to choose this tool, though it doesn't name alternatives or state when not to use it.

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. It discloses key behavioral traits: the original pattern is preserved in existing rules, fragments are not tokens, and the return value is a modified grammar. It doesn't cover edge cases like duplicate fragment names or interaction between grammar_content and from_file, but overall it provides solid transparency.

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 structured with clear sections ('When to use', 'Example', 'Benefits', 'Returns') and is not excessively long. Each section contributes meaning, though the 'Benefits' bullet list could be condensed without losing much value.

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?

The tool has a simple function (extract a fragment) and the description covers its use cases, examples, and return value. It doesn't mention potential parameter conflicts (e.g., providing both grammar_content and from_file), but given the simplicity and the existence of an output-free design, this is acceptable.

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?

Although the input schema already has 100% coverage with descriptions, the tool description adds value by showing concrete examples of how fragment_name and pattern are used (DIGIT, LETTER) and demonstrating the resulting rule usage. This goes beyond the schema's basic parameter definitions.

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 a specific verb ('Extract a reusable fragment rule from a pattern') and resource (lexer fragments). It also differentiates from sibling tools by clarifying that fragments are helper patterns, not tokens, which distinguishes it from generic rule-addition tools like add-rule.

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 listing three concrete scenarios: share common patterns, improve maintainability, reduce duplication. However, it does not provide when-not-to-use guidance or explicitly name alternative tools, so it falls short of a 5.

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 the default matching mode, the different behavior for exact vs. pattern matches, and the return data (rule definition, fan-in/fan-out, usage count). It lacks an explicit statement that this is a read-only operation, which would push it to 5.

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 a clear summary, 'When to use' section, labeled matching modes with examples, and a 'Returns' section. It is moderately sized but every sentence earns its place, and the use of bullet points enhances scannability.

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?

There is no output schema, so the description must explain return values, and it does: it details what is returned for exact matches (definition, type, line number, fan-in/fan-out, usage count) and for pattern matches (matching rules, match count). Combined with thorough coverage of matching modes, this makes the tool context complete for an agent.

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% (baseline 3), but the description adds significant value by giving concrete examples for each matching mode and explaining how rule_name is interpreted differently in each mode (e.g., regex syntax, wildcard characters, case-insensitive partial). This goes beyond the schema's simple parameter 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 opens with a specific verb and resource: 'Find rules with multiple matching modes' and clearly distinguishes itself from siblings like list-rules and find-rule-usages by emphasizing pattern matching. It explicitly names four matching modes, leaving no ambiguity about the tool's purpose.

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 'When to use' section provides clear context: 'Locate specific rules, understand rule relationships, or discover rules matching a pattern.' However, it does not explicitly mention when not to use it or name alternative sibling tools, so it stops short of a 5.

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 behavioral burden. It discloses the return payload (total usage count, per-usage details, complete report) and the multi-file behavior via load_imports. It does not state error behaviors or prerequisites, but for a read-only tool the core actions and outputs are clearly conveyed.

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-organized with clear sections (When to use, Example usage, Returns, Multi-file support, Use before). It is slightly longer than necessary, and the 'Use before' section partially repeats the 'When to use' content, but every section contributes to practical usage. Overall it is effective and not bloated.

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 has 5 parameters, no output schema, and no annotations, the description covers the key aspects: what it does, when to use it, what it returns, and a notable multi-file option. It could be more complete with error handling or prerequisites, but it is sufficient for an agent to select and invoke the tool correctly in most situations.

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%, so the baseline is 3. The description adds some context beyond the schema, such as the example usage for rule_name and the purpose of load_imports for cross-file dependencies. However, it does not significantly enrich the understanding of base_path, from_file, or grammar_content, which are already well described 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 opens with a specific verb and resource: 'Find all locations where a specific rule is referenced with line numbers and context.' This clearly distinguishes it from siblings like find-rule (which locates a rule definition) and impact-analysis (which assesses impact). The purpose is unambiguous and actionable.

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 'When to use' and 'Use before' sections, listing concrete scenarios like renaming, removing, and refactoring rules. However, it does not explicitly mention when not to use the tool or name alternatives, so it falls short of the 5-level criteria but is still strong guidance.

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, the description carries the full burden. It discloses key behaviors: the transformation performed, selective fixing via rule_names, preview capability with dry_run, and the return format (list of changes with line numbers and reasoning). It does not fully explain the interplay between write_to_file, output_mode, and grammar_content, but it is not misleading and provides substantial behavioral context beyond a bare minimum.

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 headings, a workflow list, code examples, and a real-world anecdote. Every section serves a purpose: summary, when to use, workflow, what it fixes, examples, and return info. It is somewhat long but avoids fluff, and the structure makes it easy to scan. The real-world paragraph adds credibility but is slightly tangential.

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 (6 optional parameters, no output schema), the description is quite complete. It covers when to use, exactly what it fixes, how to select rules, preview behavior, and return details. The only noticeable gap is not explaining how grammar_content relates to from_file or how write_to_file and output_mode behave together, but the examples and workflow cover the main usage scenarios.

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 baseline is 3. The description adds meaningful usage examples (e.g., from_file, rule_names, dry_run) and clarifies that omitting rule_names fixes all suspicious patterns. It does not add detail on grammar_content, but the workflow focuses on from_file, and the examples illustrate the intended usage patterns effectively.

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: 'Selectively fix suspicious quantifier patterns - change )? to )* for specific rules.' This is a specific verb (fix) and resource (quantifier patterns in grammar rules), and it distinguishes itself from the sibling tool detect-quantifier-issues by framing it as the follow-up action. The 'What it fixes' section adds concrete pattern examples, making the purpose unmistakable.

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 says 'When to use: After detect-quantifier-issues identifies problems' and provides a clear workflow (detect → review → fix). It gives examples for fixing specific rules, fixing all, and previewing with dry_run, which clarify when to include rule_names and when to omit it. This is strong guidance with explicit alternatives and exclusions.

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, the description carries the burden of behavior. It discloses the tool's output in detail (grammar name/type, rule list, imports, options, issue summary with counts). The verb 'Display' implies a read-only operation, providing implicit transparency. It does not, however, explicitly state that no modifications are made or discuss any edge cases.

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 concise and well-structured, opening with the main purpose, then 'When to use,' then a bulleted list of returned items. Every sentence earns its place; no redundant 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?

For a display tool with two optional parameters and no output schema, the description is fairly complete: it covers purpose, usage context, and return values. Minor gap is not specifying input requirements (e.g., at least one of from_file or grammar_content) or how the tool handles missing input, but overall it's sufficient for an agent to decide and invoke.

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%, so the baseline is 3. The description adds no additional parameter semantics beyond the schema; it does not explain when to use from_file vs grammar_content or relationship between them.

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 'Displays a structured summary of the grammar with proper formatting,' which is a specific verb-resource combination. However, it does not explicitly distinguish this from sibling tools like generate-summary or export-as-markdown, which may also produce grammar summaries.

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 a 'When to use' section saying to use it for a high-level overview of grammar organization and structure. This gives clear context, though it does not explicitly exclude alternatives or reference sibling tools.

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?

No annotations are provided, so the description carries full burden. It discloses generation strategies, expected returns, and that warnings are produced if the grammar can't support a strategy. It does not mention potential performance/resource implications of stress testing or side effects, but the core behavior is well-covered.

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-organized with clear sections (When to use, Generation strategies, Parameters, Returns, Example). Each section adds value: the example illustrates usage, the strategy list clarifies options, and the returns section sets expectations. No fluff.

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?

With 6 parameters and no output schema, the description covers most essentials: strategies, returns, example. It misses mentioning 'from_file' in the parameter list, but the schema covers it. The example and returns section help complete the picture, slightly imperfect but adequate.

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%, so baseline is 3. The description repeats parameter names and defaults, adding minimal extra meaning. It also omits 'from_file' from the parameter list, but the schema describes it. No additional syntax or semantics beyond 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 starts with 'Generate stress test inputs for grammar performance testing' - a specific verb and resource, clearly distinguishing it from sibling tools like test-parser-rule or benchmark-parsing. The scope is well-defined.

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?

An explicit 'When to use' section states: 'Testing grammar robustness, identifying performance issues, benchmarking.' This gives clear context. However, it does not mention when not to use or compare with alternatives, so a deduction from 5.

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, the description carries the burden of behavioral disclosure. It discloses the return structure with a detailed list of expected outputs, which is helpful, but it does not explicitly state that the operation is non-mutating or describe behavior when input parameters are omitted or both provided. The read-only nature is implied but not stated.

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-organized with clear sections and is front-loaded with the purpose. It includes an example and a concise return list, though there is some redundancy between the 'When to use' and 'Perfect for' sections, making it slightly longer than necessary.

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 thoroughly enumerates all return values, covering grammar name, rule counts, imports, top rules, issue summary, health assessment, and complexity indicators. It also provides usage context and an example, making it adequate for an agent to understand the tool's function and expected output.

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 provides full descriptions for both parameters (100% coverage), so the baseline is 3. The description adds a concrete example using 'from_file', but does not clarify the relationship between the two parameters (e.g., whether they are alternatives or additive) or what occurs if none are provided.

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 'Generate a concise summary of grammar structure and health metrics,' which identifies the verb and resource. It distinguishes itself as a summary tool rather than a detailed analysis or validation tool, though it does not explicitly compare with sibling tools like 'grammar-metrics'.

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 a dedicated 'When to use' section listing quick health checks, progress tracking, overview reports, and grammar comparisons. It also adds a 'Perfect for' line with status reports and tracking changes, giving clear context for when this tool is appropriate, though it lacks explicit exclusions or alternative tool references.

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?

No annotations are provided, so the description carries the full burden. It discloses key behavioral traits: automatic tokenization, intelligent name generation, optional prefix support, support for token options (skip, channel, fragment), and generation of ANTLR4 string literal patterns. It also lists return values (list of tokens, per-rule status, modified grammar, summary). It does not explicitly warn about potential file mutation via write_to_file, but that is disclosed in the schema. The description provides substantial behavioral detail beyond the schema.

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 structured with clear sections (When to use, Examples, Features, Returns) and uses bold headers. While it is relatively long (~200 words), every section contributes useful information. The examples are concrete and aid comprehension. It is not overly verbose, but could be slightly trimmed without losing value.

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?

The tool has 9 parameters and no output schema, so the description must cover return values and behavior. It does so by listing output categories and providing examples. It also covers most relevant scenarios (tokenization, prefixing, token options). It does not fully explain the interplay between from_file and write_to_file, but that is available in the parameter descriptions. Overall, it is quite complete for a complex 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?

Schema description coverage is 100%, so baseline is 3. The description adds value beyond the schema through concrete examples illustrating how to use input_pattern, tokenize, and prefix. The features section also explains the tokenization behavior that parameters like tokenize control. This enhances understanding of parameter semantics without duplicating schema text.

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 opens with a clear verb+resource: 'Generate lexer tokens automatically from natural language input patterns.' The examples further clarify the exact functionality, and this is distinct from sibling tools like 'preview-tokens' (which likely previews tokens) or 'add-tokens-with-template' (which uses templates). The purpose is unambiguous and well-differentiated.

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 'When to use' section lists specific scenarios (quick token generation, converting configuration snippets, generating tokens from command examples, prototyping grammars). This provides clear context for when the tool is appropriate. It does not explicitly mention alternatives or exclusions relative to sibling tools, which would push it to a 5, but the guidance is sufficient for selecting it in common cases.

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, the description carries the full burden and does a good job: it lists what the tool analyzes (naming, complexity, unused rules, etc.) and states it returns 'categorized suggestions with specific recommendations.' It does not explicitly say 'does not modify the grammar,' but the use of 'Analyzes' and 'Returns' implies a read-only operation, though a direct statement would have been ideal.

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: it opens with a one-sentence purpose, includes a clear 'When to use' inset, uses a tight bullet list for analysis categories, and closes with a one-line return summary. Every word earns its place; it is informative without being verbose.

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, the description covers the main aspects: what it does, when to use it, what it analyzes, and the general nature of its return value. However, the 'Returns' line is somewhat vague ('Categorized suggestions') without an output schema, and it doesn't clarify parameter interaction (e.g., precedence between `from_file` and `grammar_content`). Overall, it is sufficient for most use cases but has minor gaps.

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% with both `from_file` and `grammar_content` fully described. The description itself adds no additional parameter semantics, such as precedence rules when both are provided or behavior when neither is given. The baseline of 3 applies because the schema already documents parameter meanings thoroughly.

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 'Get actionable improvement suggestions for an ANTLR4 grammar' with a specific verb and resource. It lists six concrete analysis categories (naming conventions, complexity, unused rules, etc.), which both clarifies scope and differentiates it from sibling tools like validate-grammar or check-style.

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 'When to use' section explicitly says 'Optimize grammar quality, identify issues, get best practice recommendations,' providing clear context for when this tool is appropriate. However, it does not mention when not to use it or name alternative tools, so it stops short of full exclusion guidance.

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?

No annotations are provided, so the description carries the full burden. The verb 'Calculate' strongly implies a read-only operation, and the description thoroughly details the metrics returned, giving the agent a good sense of the output behavior. It does not mention explicit side-effect safety (e.g., 'modifies nothing'), but for a calculation tool this is adequate. It also does not disclose handling of invalid input or file-reading errors, but that's a minor gap given the metric richness.

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 moderately long but well-structured with clear headers and bullet points. It front-loads the primary purpose and usage context before diving into metrics. Each metric category is listed concisely, and the example is useful. It could be slightly trimmed, but the structure makes it easily scannable for an agent.

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?

The tool has a moderate complexity with a simple parameter schema (2 optional params) and no output schema. The description compensates by enumerating all metric categories in detail, giving an agent a clear picture of expected results. It includes an example invocation. The main gap is not describing the exact return format (e.g., JSON keys), but the metric breakdown serves as a sufficient surrogate. Overall, the description is complete enough for a knowledgeable agent to invoke correctly.

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% and both parameters are described individually: 'Optional: path to a grammar file to read' and 'The ANTLR4 grammar file content'. The description adds an example using from_file, which is helpful but does not add new semantic nuance beyond the schema. There is no mention of mutual exclusivity or precedence between the two parameters, so the description does not significantly elevate parameter understanding beyond 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 opens with a specific verb-object phrase: 'Calculate comprehensive grammar metrics including branching estimation, complexity, and dependencies.' This clearly distinguishes it from sibling tools like analyze-grammar or rule-statistics by specifying the exact metric categories. The detailed breakdown of metrics further reinforces the unique scope of this tool.

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?

A dedicated 'When to use:' section provides explicit context: 'Understanding grammar complexity, identifying optimization opportunities, estimating parsing performance.' This gives an agent clear scenarios for invocation. However, it does not explicitly state when not to use the tool or mention alternative sibling tools, so it misses a full exclusion/alternative guidance.

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 full responsibility for disclosing behavior. It clearly explains that the tool returns "Comprehensive documentation for the requested topic" and lists what each topic covers. It does not explicitly state side-effect-free behavior, but for a help tool this is largely implied.

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 appropriately sized and highly structured: a bold usage directive, a compact bulleted list of topics, and a one-line return statement. Every sentence earns its place, and key guidance is front-loaded.

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 that this is a simple one-parameter help tool with no output schema, the description is complete. It tells the agent when to use it, what topics are available, and what to expect in return. No critical information is missing.

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 already describes the parameter and its enum, so baseline is 3. The description adds value by explaining what each enum value represents, such as "overview: Summary of all 27 available tools by category" and "workflows: Common multi-step workflows for typical tasks," going beyond the bare enum names.

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: "Get comprehensive help about ANTLR4 MCP tools, common workflows, and usage examples." It uses a specific verb (get help) and resource (ANTLR4 MCP tools), effectively distinguishing this meta-tool from the many grammar-manipulation sibling tools.

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 gives explicit usage guidance: "USE THIS TOOL FIRST when starting work with ANTLR4 grammars." It also enumerates the available topics and suggests "overview" for a general introduction, which helps the agent choose the correct starting point.

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?

No annotations are provided, so the description carries the full burden. It discloses the return values (dependencies, dependents, usage count, recursion status, entry-rule detection, risk level, summary), which conveys behavioral traits. It doesn't explicitly state read-only behavior or clarify side effects, but 'analyze' implies a safe read 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 a summary line, a when-to-use callout, and a bullet list of returns. It is concise, front-loaded, and every sentence adds valuable context.

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 no output schema, the description lists the key output categories, covering what the tool returns. The when-to-use guidance and clear purpose make it complete enough for an agent to select and invoke the tool correctly. Minor gaps exist around parameter precedence and edge cases, but these are not critical for basic usage.

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%, with each parameter having a description. The tool description doesn't add additional parameter semantics beyond what the schema provides, so the baseline of 3 applies.

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 explicitly states the tool analyzes change impact for a specific rule, listing dependencies, dependents, and risk. This is a specific verb+resource+scope that distinguishes it from siblings like find-rule-usages by focusing on impact analysis.

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 a clear 'When to use' instruction: before renaming, deleting, or heavily modifying a rule. It doesn't mention alternatives or when not to use, so it gives clear context without explicit exclusions.

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, the description carries the full burden. It discloses exactly what is analyzed (colon/semicolon placement, spacing, indentation, blank lines) and that it returns a formatting style object. The 'Note' about other tools using this inference adds useful behavioral context. It doesn't discuss edge cases or error behavior, but coverage is solid.

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?

Well-structured with bold headings and bullet points. The description is appropriately sized—every section earns its place, including the example usage and the note about automatic usage. No fluff.

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 read-only analysis tool with no output schema, the description adequately covers parameters, usage context, analyzed aspects, and return type. It doesn't provide a detailed breakdown of the returned style object, but that's not critical for invocation. The note about sibling tools adds 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?

Schema coverage is 100%, with both parameters (from_file and grammar_content) having descriptions in the schema. The description adds an example usage for from_file but doesn't significantly expand on parameter semantics beyond what the schema provides. Baseline 3 is appropriate.

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 analyzes an ANTLR4 grammar and infers its formatting style. It specifies the resource (grammar) and the action (infer formatting), and lists the specific formatting aspects analyzed, distinguishing it from siblings like format-grammar or check-style.

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 an explicit 'When to use' section: understand formatting conventions or verify preservation. It also notes that update-rule and add-rule tools automatically use this inference, giving context on related tool behavior. It doesn't explicitly state when not to use, but the guidance is clear.

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 it excels. It details validation steps (no circular refs, not recursive, actually used), the replacement process including parenthesization, and deletion of the original rule. It also mentions dry-run mode and statistics, giving a thorough picture of side effects.

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 headers, bullet points, and concrete examples. It front-loads the core purpose, then flows into usage, behavior, and return values. Every section provides distinct value and nothing is redundant or verbose.

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 has 6 parameters and no output schema, the description covers all necessary context: what it does, when to use, how it works internally, validation checks, return values, and examples. The agent can confidently invoke this tool and interpret its effects without additional information.

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%, giving a baseline of 3. The description adds context beyond the schema: it explains the effect of preserve_parentheses ('Smart parenthesization', 'adds parentheses if needed'), the dry-run concept, and the relationship between from_file and write_to_file through usage examples. It doesn't deeply explain every parameter but adds meaningful nuance.

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 first sentence precisely explains the operation: 'Inline a rule by replacing all references with its definition, then delete the original rule.' This names a specific verb and resource, and the description differentiates it from siblings like extract-fragment by labeling itself as the inverse. No ambiguity.

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 'When to use' section explicitly lists scenarios (pass-through rules, simplifying structure, reducing indirection) and states it is the inverse of extract-fragment. This directly guides the agent on when to choose this tool over alternatives.

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 clearly explains the return format (list of rules with names, patterns, line numbers, and total count), which is essential. It does not discuss side effects, but for a read-only list operation this is adequate.

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, bullet points, and examples. Every sentence serves a purpose, and the examples are informative without being redundant. It is appropriately sized for the tool's complexity.

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 has only one required parameter, no output schema, and no annotations, the description covers the key aspects: purpose, when to use, return values, and usage examples. It does not address potential errors or the source of grammar content, but the schema covers those details. Overall, it is nearly 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?

Schema coverage is 100%, so the baseline is 3. The description adds value by providing concrete examples for the mode_name parameter (e.g., 'STRING_MODE', 'DEFAULT_MODE'), which helps the agent understand acceptable values beyond the schema's generic name description.

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 function: 'List all lexer rules in a specific mode.' This is a specific verb+resource+scope combination that distinguishes it from sibling tools like list-rules, which likely lists rules globally rather than per mode.

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 a 'When to use' section with concrete scenarios (quick inspection, debugging mode issues, understanding structure). However, it does not explicitly mention alternatives or when not to use this tool, so it falls short of a perfect 5.

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. It discloses the output format (alphabetically sorted list, rule names, types, definitions, line numbers) and explains filter_type behavior with examples. However, it does not explain what happens if both from_file and grammar_content are provided or if neither is provided, leaving minor ambiguity.

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: main action, when to use, example, and returns. It is somewhat lengthy but each part provides useful information, with no redundant filler.

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?

The tool is a read-only listing operation with no output schema, so the description adequately covers purpose, usage, and return format. Gaps remain around input source precedence and handling of multiple input parameters, but overall it is complete enough for an agent to invoke the tool correctly.

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%, so the baseline is 3. The description adds value by providing example usage for filter_type, including the semantic detail that lexer rules are uppercase and parser rules are lowercase. This goes beyond the schema's basic 'Filter rules by type'.

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 lists all rules in an ANTLR4 grammar with optional filtering. It is specific ('List all rules') and identifies the resource ('ANTLR4 grammar'), but does not explicitly differentiate from the sibling tool 'list-mode-rules'.

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 'When to use' section provides context: getting a quick overview or filtering by lexer/parser. It does not mention exclusions or mention alternative tools, so it stops short of explicit when-not guidance.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It explicitly states that original rules are removed, references need manual updates, and the return value is a modified grammar. This fully discloses the side effects and output behavior.

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: core action, when to use, example, benefits, and a note on side effects. It is front-loaded with the essential purpose and usage, and every sentence adds value. The length is appropriate for the tool's complexity.

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 moderate complexity (5 parameters, no output schema), the description fully covers the needed context: what the tool does, when to use it, an example, side effects, and return value. The schema and description together provide complete information for correct invocation.

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 each parameter already described in the input schema. The description adds context about the merge behavior (originals removed) and includes an example, but it does not significantly enhance parameter semantics beyond what the schema provides. Baseline 3 is appropriate.

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 function: 'Merge two related rules into one rule with alternatives.' This is a specific verb+resource combination that distinguishes it from sibling tools like add-rule, remove-rule, and rename-rule. The example with intLiteral/floatLiteral/numericLiteral further clarifies the intended operation.

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?

An explicit 'When to use' section lists concrete scenarios: consolidate similar rules, reduce rule count, group related alternatives. It also mentions 'or use rename-rule first' for updating references, providing an alternative strategy. This gives clear guidance for when to select this tool over siblings.

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, the description carries the full burden. It discloses preservation of formatting, blank line maintenance, validation of rule and anchor existence, and detection of already-in-position. This is useful behavioral context, though it doesn't specify error handling or return behavior.

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?

Well-structured with sections (When to use, Use cases, Features, Example, Note). It is longer than a single sentence but each section adds value. Front-loaded with a clear one-liner purpose. Slightly verbose but appropriate for the tool's complexity.

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 schema covers all parameters and no output schema, the description still explains when to use, features, examples, and alternatives. It does not describe return values or in-memory vs file write behavior beyond the write_to_file param, but overall it is sufficiently complete for an AI agent.

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 baseline is 3. The description adds example usage for rule_name, position, anchor_rule, and write_to_file, but does not add new semantic meaning beyond the schema's parameter descriptions. The examples clarify relationships but the schema already defines them.

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 moves an existing rule to a new position relative to another rule. It distinguishes from siblings like sort-rules and move-rule-to-mode by specifying it reorganizes within the same context, and explicitly contrasts with add-rule for new rules.

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?

Provides explicit 'When to use' section listing reorganization scenarios, plus concrete use cases. It also gives a clear exclusion: 'This moves EXISTING rules. To insert NEW rules... use add-parser-rule or add-lexer-rule' — good alternative guidance.

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?

Features list discloses validation behaviors and preservation of the rule definition. However, it does not explain side effects like whether the source rule is removed, default write behavior, or what the output modes ('full', 'diff', 'none') produce. With no annotations, these gaps leave important behavioral aspects unexplained.

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?

Well-structured with clear sections: purpose, when-to-use, features, example, and note. Every section earns its place, the example is minimal, and the overall length is appropriate for the tool's complexity.

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?

The description covers purpose, usage, and validation but omits output behavior and how the tool interacts with the file (e.g., whether write_to_file is required for persistence). Since there is no output schema, the description should explain return values or output modes, which it currently does not.

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% and descriptions are already in the schema. The example adds a concrete usage pattern but does not add meaning beyond the schema fields. It serves as an illustration rather than additional explanation.

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 opening sentence 'Move an existing lexer rule to a different mode' uses a specific verb and resource, and the scope is clearly distinguished from siblings like move-rule (generic) and add-rule-to-mode (create new). The note about parser rules further narrows the purpose to lexer rules only.

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?

Provides a 'When to use' section with three concrete scenarios and an explicit exclusion (parser rules cannot be moved). However, it does not name alternative tools such as 'add-rule-to-mode' or 'move-rule', which could help an agent choose between them.

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, the description carries full responsibility for behavioral disclosure. It reveals meaningful details such as auto-downloading the ANTLR JAR to ~/.local/lib/, using a low-overhead Java driver, and performing warmup iterations. This goes well beyond a simple 'benchmark' label.

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-organized into clear sections (When to use, Requirements, Features, Parameters, Returns). The parameter section somewhat redundantly repeats schema descriptions, but the overall structure is scannable and each section contributes useful context.

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?

Although there is no output schema, the description explicitly lists return values (avg/min/max, throughput, performance rating), requirements, and an example. This makes the tool's behavior and results understandable without needing additional documentation. It is comprehensive given the tool's complexity.

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%, so the schema already documents all parameters. The description duplicates this information but adds a concrete example of grammar_files and start_rule usage. This provides marginal value beyond the schema, matching 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 benchmarks grammars using the actual ANTLR4 Java runtime, which is a specific and distinct action. It emphasizes 'most accurate' and differentiates from sibling benchmarking tools by highlighting the real runtime.

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 'When to use' section explicitly names final performance testing, comparing grammars, and production validation. It provides clear context but does not explicitly list exclusions or alternative tools, so it falls just short of a 5.

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, the description carries full behavioral burden. It clearly explains native ANTLR4 mode versus simulation fallback, details simulation limitations (lexer modes, predicates, actions), and describes return values including feature warnings and mode indicators. No contradictions.

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 and front-loaded purpose, but it is verbose with emojis, repeated limitations, and extensive setup instructions. It could be trimmed by ~30% without losing essential 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?

The description covers behavior, setup, examples, return format, limitations, and alternatives. Since there is no output schema, the detailed Returns section is essential and fully compensates for that gap.

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 covers 100% of parameters, so baseline is 3. The description adds rich examples for input, from_file, and rules_to_test, clarifying usage beyond dry schema definitions. However, one example references 'load_imports: true', which is not an actual parameter, creating minor confusion.

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 opens with a specific verb and resource: 'Preview how input text would be tokenized by lexer rules.' It also explicitly distinguishes itself from the sibling tool test-parser-rule, stating it tests parser rules without full lexer simulation.

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?

A dedicated 'When to use' section lists concrete scenarios such as testing rule matches, debugging tokenization, verifying grammar changes, and learning ANTLR4. It also provides an explicit alternative: 'For complex grammars, use test-parser-rule.'

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, the description carries the full burden of behavioral disclosure. It adds rich context through the 'Measures' and 'Interpretation' sections, explaining exactly what gets analyzed and how to interpret the results (e.g., ambiguityCount > 0 means ambiguous alternatives). It doesn't mention side effects or permissions, but the profiling nature is clear and the description goes beyond a bare 'Profile parsing' statement.

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, Measures, Parameters, Returns, Example, Interpretation). Every section provides necessary information, and the content is front-loaded with the core purpose. No redundant or filler sentences.

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 (3 params, no output schema, no annotations), the description is very complete. It explains the return values explicitly (profile metrics, frequent rules, optimization suggestions) and provides interpretation thresholds for key metrics, which is critical for an AI agent to understand the output without a 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 baseline is 3. The description restates the parameters with concise meanings and adds a concrete example showing expected values for grammar_files, start_rule, and input. This example adds practical meaning beyond the schema definitions.

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 states a specific action: 'Profile grammar parsing with detailed performance metrics.' It clearly identifies the resource (grammar parsing) and the goal (performance analysis), and distinguishes itself from sibling tools by listing concrete measures like parse time, ambiguity count, and context sensitivity.

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 'When to use' section explicitly says 'Deep performance analysis, debugging slow parsing, optimizing grammars,' providing clear context for when to invoke this tool. However, it doesn't explicitly mention when not to use it or name alternative tools, so it stops short of full exclusionary guidance.

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, the description carries the burden of disclosing side effects. It warns that 'Does not update references to this rule in other rules,' which is a critical behavioral trait. It also mentions the return value (modified grammar, success message, file write confirmation). However, it doesn't address edge cases like missing rule or error handling, so a 4 is appropriate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.