Patch a changelog fragment

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

Annotations declare readOnlyHint=false (it's a write), idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond annotations: the optimistic-concurrency mechanism and the release-boundary constraint ('afterwards the text belongs to that release'). This directly explains what happens in the concurrent-edit case and the lifecycle boundary.

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?

Two crisp, front-loaded sentences with zero wasted words. The first sentence states the purpose plus the key concurrency mechanism; the second sentence nails the critical lifecycle boundary. Every clause 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?

Given the moderately complex signature (a nested object parameter, an optional concurrency-check param) and the presence of an output schema, the description covers the essential operational semantics. It leaves details of the output schema to the schema itself. Could mention what fields are valid in 'changes' or error behavior, but the schema covers field names and the description covers the partial-update and concurrency semantics.

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, but the description's first sentence adds lifecycle semantics for the id parameter context and explains the concurrency-check behavior of expectedRevision. The 'Only the keys present are touched' note clarifies partial-update semantics for the changes object beyond what the schema states, which is valuable for an object parameter.

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 verb+resource ('Patch an unreleased changelog fragment') with clear scoping — it operates on 'unreleased' fragments only and explicitly distinguishes itself from the release-related lifecycle ('Only works before a release consumes the fragment'). It differentiates from sibling tools like project_changelog_add, project_changelog_list, and project_changelog_release which are lifecycle peers.

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 clearly states when the tool works ('before a release consumes the fragment') and its optimistic-concurrency behavior. It could be strengthened with an explicit alternative mention (e.g., adding vs patching a fragment), but the lifecycle constraint provides clear operational guidance.

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