Server Quality Checklist

Tool Scores

• get_composerA
  4.3/5.0
  Behavior4/5

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

  Annotations already provide readOnlyHint and openWorldHint. The description adds useful behavioral detail by specifying the exact return shape, including the works array structure and profile summary, and clarifies that the ID comes from the URL /persons/<ID>. No contradiction with annotations.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is compact and well-structured, with a clear one-line purpose followed by Args and Returns sections. Every part adds necessary information with no redundancy.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a single-parameter read-only lookup, the description provides the input format and a complete return shape, which is sufficient despite the absence of an output schema. It does not mention pagination or limits, but those are not strongly implied for this operation.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 0%, so the description must fully explain the parameter. It does: composer_id is identified as the Pitina composer encyclopedia ID and tied to the URL /persons/<ID> number format, which is precise and actionable.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states a specific verb (取得する/retrieve) and resource (profile summary and work list for a composer by ID). It distinguishes itself from sibling tools like search_composers and search_pieces by focusing on lookup by a known composer ID rather than search.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description implies use when the caller already has a composer_id, especially given the URL pattern hint. However, it does not explicitly state when to prefer this over search_composers or mention any alternative/exclusion conditions.

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

• get_pieceA
  4.5/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters5/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• search_piecesA
  4.5/5.0
  Behavior4/5

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

  The annotations already signal read-only and open-world behavior, so the bar is lower. The description adds meaningful context: it returns a candidate list of official titles, composer names, opus numbers, durations, and piece IDs, which would have been missing without an output schema. Some details like pagination or rate limits are omitted, but these are not essential here.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is efficiently structured with a one-line purpose, a short usage scenario, and clear Args/Returns sections. Every sentence earns its place, and the output format is explicitly described.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a two-parameter read-only search tool with no output schema, the description is complete: it explains what input it expects, what the output looks like, and the intended use case. There are no significant missing details an agent would need to select and call this tool.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 0%, so the description must explain parameters, and it does. It clarifies 'keyword' as a piece title, composer name, or fragment, which is more semantically meaningful than the schema property alone, and it defines 'limit' as the maximum number of returned items.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states a specific verb and resource: searching ピティナ曲事典 pieces by keyword in the title or composer name, and clearly frames that this is the 'center tool' for normalizing orthographic variants. The scope on 楽曲 makes it distinct from sibling tools like get_piece or search_composers.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description gives a clear usage scenario: it is the central tool for 表記揺れ correction, and you should pass an ambiguous piece name to get official candidates. It does not explicitly name alternatives or exclusion criteria, though the sibling list and the scope statement make those inferable.

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

• search_composersA
  4.6/5.0
  Behavior4/5

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

  The description adds useful behavioral context beyond the readOnlyHint annotation: it explains that results are extracted uniquely from piece search results and that this is for spelling-variant verification. No contradiction with annotations is present.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is well-organized with a clear purpose statement, usage context, and structured Args/Returns sections. Every sentence adds value, and the key use case is front-loaded.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given two simple parameters, no output schema, and readOnly annotations, the description covers purpose, parameters, return format, and usage rationale. Nothing essential for an agent to call the tool correctly is missing.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  With 0% schema description coverage, the description fully explains both parameters: name as 'composer name or fragment' and limit as 'max results returned, default 20'. This meaning is entirely absent from the schema, which only holds type and default.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's function: searching by composer name and returning official name, composer ID, and URL candidates. It also specifies its intended use case (correcting orthographic variations) with an example, which distinguishes it from the sibling tools that target pieces or specific composers.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description provides a concrete usage context (notation variation correction) and implicitly separates this from piece-search tools. However, it does not explicitly mention when to prefer get_composer over this or when not to use the tool, leaving some routing to inference.

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