Generate typed event constants

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

Annotations already indicate the tool is read-only, and the description adds determinism ('Regenerating produces an identical file') and explains the exactness of event matching. The instruction 'Write it into the repo' could cause slight ambiguity about whether the tool writes or the agent writes, but it does not contradict the readOnlyHint.

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 with three sentences that front-load the main purpose. The middle sentence is an actionable usage instruction, and the third provides useful determinism context. The phrasing is slightly run-on but each sentence earns its place.

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 code generation tool without an output schema, the description adequately explains the output is a file and highlights determinism. However, it does not detail the output format or explicitly clarify that the tool generates content while the agent writes it, leaving a minor completeness 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?

Schema description coverage is 100%, so the baseline is 3. The description only adds meaning to the platform parameter ('the language you ask for') and does not elaborate on the events or packageName parameters 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 description clearly states the tool generates typed event constants for the project's events in a specified language. The verb 'generate' and resource 'constants file' are specific, and it distinguishes itself from sibling tools that list or mark events rather than generate code.

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

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

The description implies usage by instructing to write the file and use constants instead of string literals, and it notes idempotent regeneration. However, it does not explicitly mention when to use this tool over alternatives like list_expected_events or mark_events_declared, nor any exclusions.

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