grammar-metrics

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.