create_announcement

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

アノテーションが一切提供されていないため説明が負うべき責任は大きいが、「APIトークンが必要です」という認証要件の開示はスキーマには存在しない有用な行動情報である。一方で、作成後の即時公開の有無、成功時の戻り値、冪等性などの副作用については触れられておらず、開示は部分的な水準に留まる。

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?

核となる動作（作成）が最初の文に先頭配置され、続く文で必要な前提条件（APIトークン）を補足する2文構成で、一切の冗長表現がない。1語の無駄もなく、簡潔さの観点では模範的である。

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?

パラメータはスキーマが100%カバーしデフォルト値まで明記されているため、その分の欠落はない。しかし、アノテーションも出力スキーマも無い中で、APIトークンの具体的な渡し方（ヘッダーかパラメータか）、成功時の応答内容、作成後の公開状態という実行完了に必要な情報が説明から欠けている。最低限は満たすが明確なギャップがある。

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?

スキーマの説明カバー率は100%で、level のデフォルト値（info）、is_active のデフォルト値（true）、title の最大200文字、starts_at/ends_at のISO 8601形式、link_url のhttp/https制限まで個別パラメータに記載が完備している。説明文はパラメータ情報を追加しておらず、カバー率80%超のベースラインである3が妥当。

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?

「新しいお知らせを作成します」は具体的な動詞（作成）とリソース（お知らせ）を示しており、操作レベルでは list/update/delete_announcement と明確に区別できる。ただし、同じ「作成」系統の create_release_note との違い（お知らせ vs リリースノート）には言及がなく、sibling との差別化は暗黙的な範囲に留まる。

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?

いつ使うべきか、あるいは代替ツール（既存のお知らせの変更なら update_announcement、リリースノートの作成なら create_release_note）を使うべき条件についてのガイダンスが一切ない。「APIトークンが必要です」は前提条件の提示であり、利用判断の指針にはならない。

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