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

Annotations declare destructiveHint=true and idempotentHint=false, but the description goes well beyond them: it names exactly what is destroyed (the name only), what survives (the version, still listed and rollback-able), and the reader-visible consequence in both states (newest remaining tagged version, then newest live version once all tags are gone). The 'Reminds no one' clause additionally discloses that no notification is sent.

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?

Front-loaded with the action and its scope, then the consequences in a compact sentence. 'Reminds no one' is terse to the point of being cryptic, but every clause otherwise carries real information and there is no filler.

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 destructive two-parameter mutation with no output schema, the description covers the important post-conditions: version retention, rollback path, and reader-facing fallback. Gaps remain around prerequisites (permissions) and error behavior when the named tag or proposal doesn't exist — relevant given idempotentHint=false.

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 only 50%: 'name' is documented in the schema but 'proposal_id' has no description anywhere. The description adds no parameter-level meaning at all — it never indicates which page/proposal the tag belongs to or that proposal_id identifies the target page, so it does not compensate for the coverage gap.

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?

States a specific verb and resource with explicit scope: 'Delete one tag from a page', then immediately bounds it ('only the name goes, the version stays'). This is clearly distinct from version-destroying siblings like revoke_versions or delete_proposal without needing to open any schema.

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 'version stays (still in list_versions, can be rolled back to)' clause implicitly contrasts this with version-removal tools, which is helpful context. However, no sibling is named and there is no explicit when-not guidance (e.g., when to use revoke_versions instead, or what to do if the tag is the last one).

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