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

Beyond the destructive and non-idempotent annotations, the description discloses omitted fields are retained while intent/dueAt=null clears them, and archiving removes the goal from the default todo. It also warns that there is no persistent request deduplication key, so retries must be preceded by a query. This is substantial operational context beyond the annotations.

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 dense but every clause adds value: auth requirement, target fields, status enum, retention/clearing semantics, archive side-effect, and retry guidance. It is front-loaded with the main action and places operational caveats at the end. No filler or redundant phrasing.

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, non-idempotent mutation with no output schema, the description covers who may call, what fields may change, side-effects of archiving, and how to handle ambiguous results by querying get_collaboration_goal. The only minor gap is the lack of an explicit success response shape, but the verification guidance mitigates this absence.

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?

With schema description coverage at only 20%, the description compensates by enumerating updateable fields and clarifying the omitted-vs-null distinction for intent and dueAt. The status enum values are repeated, reinforcing allowed values. goalId's role as identifier is implicit from the schema's required field, so it does not need further explanation.

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 action: the initiator updates the goal's title, intent, deadline, or status, and lists the exact statuses (ACTIVE/COMPLETED/ARCHIVED). It clearly differentiates from create_collaboration_goal (creation) and get_collaboration_goal (reading) among siblings. The editable fields and actor are explicit.

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 gives clear context: login is required, only the initiator may call it, and the post-update behavior (query current value, do not auto-resend, no dedup key) is specified. It does not explicitly compare this tool to update_collaboration_task or create_collaboration_goal, but it does name get_collaboration_goal for verification, providing partially explicit routing.

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