Delimit Semver

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

Annotations already cover read-only/idempotent/non-destructive behavior, and the description reinforces this with 'Side effects: read-only' while adding new context: it calls backends.gateway_core.run_semver and is deterministic on top of the diff engine output. This goes beyond the annotation metadata without contradicting it.

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?

Every section earns its place: core purpose, usage guidance, sibling contrast, and side effects are all compact and front-loaded. The use of short headings makes it easy to scan without any padding 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?

For a tool with full parameter documentation and an output schema, the description covers all selection-relevant context: what it returns, when to use it, when not to, how it relates to siblings, and side-effect behavior. Nothing an agent needs to pick or invoke this tool correctly 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?

Schema description coverage is 100%, so the schema already documents old_spec/new_spec as required paths and current_version as optional. The description's mention of 'optionally computing the next version string' mirrors the schema and adds no new parameter-level detail. Baseline 3 is appropriate when the schema does the heavy lifting.

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?

Opens with a specific verb-resource pair—'Classify a spec change's semver bump'—and names the exact output enum (MAJOR/MINOR/PATCH/NONE), so an agent knows exactly what the tool produces. It also explicitly contrasts itself with delimit_diff and delimit_lint, making sibling differentiation clear.

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?

Has explicit 'When to use' and 'When NOT to use' sections that name delimit_lint and delimit_diff as alternatives. The sibling contrast line further clarifies the boundary: this maps a diff to a semver verdict only, while siblings list changes or add policy.

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