get_piece

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

readOnlyHint=trueがアノテーションで示されており、このツールが読み取り専用であることは既知。その上で説明文は、返り値のフィールド一覧を提示している。ピースをIDで取得して正式情報を確定するという挙動がはっきりしており、追加文脈として有用。ただし、件が存在しない場合の挙動やエラーについては書かれていない。

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?

「取得する」を冒頭に置き、必要な仕様が簡潔にまとめられている。ArgsとReturnsが明快で、情報も重複せず、無駄なく本質的な内容だけが含まれている。

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パラメータのみの単純な読み取り操作であり、説明文は入れない返り値のフィールドも挙げて、利用のタイミングとパラメータ参照元を提供している。返値の欠落やエラー処理までは触れていないが、このレベルの簡単な取得ツールにしては十分に完結している。

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?

input-schemaのpiece_idはinteger型のみの情報しかなく、パラメータ語法の説明が0%であるため、文章の説明の負荷が高い。しかしDescriptionは「権威に曲辞典のID」「URLの/musics/<ID>の数字」と、パラメーターの由来と意味を補っており、agentが正しいIDを渡すために十分な情報を提供している。

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?

「楽曲IDから詳細を取得する」と具体的な動詞とリソースを示しており、タイトル・作曲家・作品番号・URLなど取得内容も列挙している。「1曲の正式情報を確定する」という用途がsearch_piecesと明確に区別されており、ピアノの楽曲IDが対象であることも一意に分かる。

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?

「search_pieces で見つけた piece_id を渡し」と、利用する際の前提条件が明記され、どのようにIDを入手するかが示されている。一方で、search_piecesやget_composerなどの代替ツールを明示的に「この場合は使わない」と排除していない点はあり、完全な使い分けガイドとは言えない。

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