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

アノテーションが readOnlyHint・idempotentHint・destructiveHint を既に提供しており、説明は「プリセットと ready のものだけ返す」というフィルタ条件と、API キーが signup 由来である認証前提を追加している。戻り値の細部やページングは説明されていないが、アノテーションが安全プロファイルを補完しているため十分。

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?

2 文に必須情報を集約し、冒頭で返すものの範囲を提示、続けて利用方法と認証要件を簡潔に述べている。無駄な文言がない。

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?

1 パラメータの低複雑度ツールで、認証要件・取得対象・create_session への接続という選択と実行に必要な文脈が揃っている。出力スキーマがないため戻り値の構造は明示されていないが、正しく呼び出すための重大な欠落はない。

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?

api_key はスキーマに必須・型・例が記載されており、スキーマの説明カバレッジは 100%。description は「signup で受け取ったキー」という由来を付け加えるが、パラメータの形式や挙動に関する追加情報は限定的で、ベースラインの 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?

「使えるアバターを返す」と明記され、プリセットとテナント内で作成済みの ready アバターという対象範囲を定義。create_session の avatar_id に使うという文脈により、get_avatar や create_avatar などの兄弟ツールと十分に区別できる。

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?

create_session への id 受け渡しという具体的な利用シーンを示し、このツールをいつ呼ぶべきかが分かる。「api_key が必要」という前提も明記されている。ただし、list_voices など代替ツールとの使い分けや「これを使うべきでない場合」は明示されていない。

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