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

Annotations only declare destructive/openWorld/non-idempotent; the description adds the facts an agent actually needs: the change is PUBLIC on the status page even with publish=false, publish=true triggers paid SMS/notification delivery to named channels, and passed fields overwrite prior values. This is exactly the kind of consequence disclosure the annotation set cannot carry.

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 'WRITE:' and the field list; every clause is substantive. Slight redundancy — the 'still public' point is restated in the publish and additional_comment areas — and the trailing 'Sorry: PATCH /v1/...' vendor/HTTP noise is unnecessary.

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 an 11-parameter destructive mutation with no output schema, the description covers the decisive risks: audience exposure, subscriber delivery and charges, overwrite behavior, and the confirm requirement. Return shape is not explained, but with full schema coverage and strong annotations that is not needed for correct invocation.

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 baseline is 3; the description still adds value by explaining that publish controls broadcast only (not visibility) and that supplied fields overwrite previous values, i.e. PATCH-style partial semantics. It does not discuss state enum choices or schedule pairing (begins_at_date/time with duration) beyond what the schema says.

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 ('change a notice') and enumerates exactly which fields are mutable (subject, state, components, schedule, timeline comment). It is clearly a write counterpart to get_notice/list_notices, but it does not disambiguate itself from the close siblings sorryapp_create_notice_update and sorryapp_edit_notice_update, which its 'add a comment (an update)' clause overlaps with.

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?

Gives concrete conditions for the risky flag: publish=false still makes the change public but suppresses broadcast, publish=true additionally notifies subscribers/integrations and may incur SMS charges, plus 'Confirm the content and audience first.' It never says when to prefer create_notice_update / edit_notice_update instead, so the overlap with siblings is left unresolved.

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