delimit_changelog

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

With no annotations, the description fully carries the transparency burden. It describes what each mode does (reads git log, categorizes commits, pulls ledger items, compares specs) and mentions file output ('prepends entry' if output_file is CHANGELOG.md). It does not explicitly state side effects (e.g., whether it modifies the repo), but the file writing is disclosed. The description could be more explicit about write operations, but it is generally transparent.

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 header line, numbered/bulleted mode details, and a list of formats. Every sentence adds value; there is no fluff. It is appropriately sized for the complexity of the tool.

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 two modes, 8 parameters, and an output schema, the description covers modes, param groupings, formats, and the output_file behavior. It does not specify the exact return structure (but output schema exists), and it lacks examples or edge cases, but it is complete enough for an agent to use 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 schema already documents all parameters. The description adds value by grouping parameters into modes (e.g., repo_path for git mode, old_spec/new_spec for spec mode) and explaining the output_file behavior (prepends entry). 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 clearly states that the tool generates a changelog from two distinct sources: git commits plus ledger or API spec changes. It distinguishes the two modes ('git mode' and 'spec mode'), and there are no sibling tools that overlap, so the purpose is 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?

The description provides clear guidance on when to use each mode by specifying the required parameters (e.g., repo_path for git mode, old_spec+new_spec for spec mode). It does not explicitly state when not to use the tool or mention alternatives, but the context is sufficient for an agent to decide.

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