Server Quality Checklist

Tool Scores

• az_pr_showB
  3.2/5.0
  Behavior2/5

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

  No annotations are provided (no readOnlyHint, destructiveHint), so the description carries the full burden. It states it fetches via REST API and lists returned fields, which signals a read operation, but it doesn't disclose behaviors like auth requirements, rate limits, or what happens with invalid PR numbers. For a read tool with zero annotation coverage, the disclosure is minimal.

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

  Conciseness4/5

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

  The description is a single efficient sentence that conveys the resource, fields returned, and default scoping. It front-loads the core purpose and adds defaults compactly. Minimal waste, though it could be more explicit about usage guidance.

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

  Completeness3/5

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

  For a simple read tool with only 3 params and no output schema, the description provides core purpose, returned fields, and defaults. However, with no annotations and no output schema, it doesn't disclose the actual fields/types returned beyond a few examples or error/edge-case behavior, which is a modest gap for such a tool.

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

  Parameters3/5

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

  Schema coverage is 100%, with each parameter already described (prNumber, project override, repository override). The description adds the default values for organization/project/repository, which the schema lacks, providing useful context. Baseline 3 is appropriate since the schema already documents parameters and the description adds default-value enrichment but no syntax/format details.

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

  Purpose4/5

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

  The description has a specific verb ('取得'/'fetch') and resource ('PR 完整資訊'), listing the retrieved fields (title, sourceRefName, targetRefName, status). It names defaults for organization/project/repository which helps scoping. However, it doesn't differentiate from siblings like az_pr_changes or az_pr_workitems which retrieve different PR sub-information, though the resource (full PR info) is reasonably distinguishable by implication.

  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 this is for fetching full/complete PR details and mentions defaults, giving some context. But there is no explicit when-to-use vs alternatives guidance, nor doestate intended use cases beyond presenting details. No exclusions or comparison with sibling tools like az_pr_changes are provided.

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

• az_pr_workitemsB
  3.3/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries full burden. It states it uses REST API and returns id/url, which reveals read-only intent implicitly, but does not document pagination, rate limits, authentication requirements, error behavior, or what the response format looks like. Since this is clearly a read-only data-fetching operation with zero annotation coverage, more behavioral disclosure is expected.

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

  Conciseness4/5

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

  The description is two sentences and wastes no words. It covers core purpose, output scope, and default inheritance in minimal space. The only minor gap is the lack of behavioral details, but structurally it is well-formed and front-loaded.

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

  Completeness3/5

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

  For a read-only list tool with good schema coverage, the description is adequate but thin. It explains purpose, output format (id/url), and inheritance from az_pr_show, but lacks authentication notes, pagination behavior, output structure, and explicit read-only confirmation. Given that no annotations and no output schema exist, the description should carry more weight for these behavioral facts.

  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 100%, so all three parameters are documented in the schema itself. The description does not repeat parameter details but references the az_pr_show defaults, which adds contextual meaning beyond the schema (explaining that project/repository override the same defaults as a sibling tool). Even with high schema coverage, the default-inheritance note adds genuine value.

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

  Purpose4/5

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

  The description clearly states the tool fetches PR-associated work items (id and url) via REST API. It specifies the verb (get/list), the resource (PR work items), and the scope (id与url). It distinguishes from siblings by being PR-specific and noting the output is id/url, differentiating from az_pr_show (PR details) and az_pr_changes (file changes). Missing explicit sibling differentiation but the purpose is clear.

  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 notes that default organization/project/repository are the same as az_pr_show, which implicitly suggests consistent usage context, but does not explicitly state when to use this vs alternatives. No when-not guidance or exclusion conditions. The inheritance-from-az_pr_show note is helpful context but doesn't provide operational boundaries.

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

• az_workitem_relationsB
  3.4/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the burden of behavioral disclosure. It states this is a read operation via REST API with $expand=relations and discloses the default organization context. However, it doesn't describe return format, error behavior, or whether any side effects exist, and doesn't explicitly confirm read-only semantics despite being a GET-style operation.

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

  Conciseness4/5

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

  The description is a single, focused sentence that packs in purpose, technique, and a use case. It is front-loaded with the main action and includes practical detail about the API expansion and default org. No wasted words.

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

  Completeness3/5

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

  For a simple single-parameter read tool, the description is reasonably complete. It explains what it retrieves, how (REST with $expand), and a common use. With no output schema, it doesn't describe the returned structure in detail, which for a relations tool could be worthwhile, but the schema and simplicity keep this adequate.

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

  Parameters3/5

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

  Schema coverage is 100% (workItemId fully documented). The description adds the default organization value (https://dev.azure.com/SKMHHIS) which is genuinely useful context beyond the schema. Baseline 3 applies since schema covers the single parameter well; description adds mild supplementary value.

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

  Purpose4/5

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

  The description states a clear verb+resource: retrieves work item complete info including relations via REST API with $expand=relations. It also names a specific use case (checking if attachments exist). It doesn't explicitly differentiate itself from siblings, though the use case hint and tool name do provide some distinction from attach/update tools.

  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 states a concrete usage scenario (checking whether attachments exist), which is helpful context. However, it doesn't explicitly say when not to use this vs alternatives like az_workitem_attach or az_devops_help, nor does it mention when to prefer sibling tools for related operations.

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

• az_pr_changesA
  3.6/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full burden. It reveals one useful behavioral trait — that unspecified iterationId auto-selects latest and the output will note this. However, it doesn't disclose what the return format looks like, pagination behavior, error conditions, or whether this is read-only operations-wise.

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

  Conciseness4/5

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

  The description is compact — two sentences covering purpose and key default behavior. It's front-loaded with the core action. Minor redundancy exists in restating defaults already present in schema descriptions, but overall it's efficient.

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

  Completeness3/5

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

  For a read-oriented list tool with a 100%-covered schema and no output schema, the description covers the essential purpose and a notable default behavior. However, it doesn't describe the output structure (what fields appear in the changes list), which given no output schema would be useful. It's adequate but not rich.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema documents all 4 parameters. The description adds the default-iteration behavior context that enriches understanding of iterationId. However, it repeats parameter-level defaults (project MS, repository MS-Web) already in the schema and adds no additional semantic depth beyond the iteration behavior.

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

  Purpose4/5

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

  The description clearly states '以 REST API 取得 PR 的異動檔案清單（iteration changes）' — a specific verb (取得/list changes) applied to a resource (PR files/iteration changes). It distinguishes itself from siblings like az_pr_show and az_pr_workitems by specifying it returns file change lists for iterations, but doesn't explicitly name the alternative sibling for differentiation.

  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 explains the default behavior when iterationId is omitted (uses latest iteration and notes it in output), which gives clear context for when to call without a parameter. However, it doesn't explicitly state when NOT to use this tool versus alternatives like az_pr_show, az_rest, or az_git_fetch, so it lacks exclusions or alternative naming.

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

• az_git_ls_remoteA
  3.9/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the burden. It does disclose that it queries host-side without downloading objects and runs on the host machine ('主機端'). However, it doesn't describe network behavior, failure modes, or what happens on nonexistent branches/refs, though for a read-only ls-remote type tool the risk profile is lower.

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

  Conciseness4/5

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

  Two concise sentences in Traditional Chinese that are front-loaded with the core purpose and usage context. The example is useful and illustrative. Slight opportunity to be more compact, but no wasted words.

  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 read-only inspection tool with 100% schema coverage and 6 well-documented parameters, the description adequately covers purpose and usage. No output schema exists, but for ls-remote the output format is well-known git output. The host-side emphasis and pre-fetch use case provide sufficient context given the tool's low complexity.

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

  Parameters3/5

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

  Schema coverage is 100%, so every parameter (tags, heads, remote, pattern, timeout, repoPath) is documented in the schema. The description adds the '主機端絕對路徑' and remote-name-only constraint context, but mostly reinforces what the schema already states. Baseline 3 is appropriate given full coverage.

  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?

  Specific verb+resource+mode: '查詢本機 repo 的遠端 refs（git ls-remote，不下載物件）'. Clearly distinguishes from az_git_fetch (which downloads objects) by explicitly stating '不下載物件' and framing it as a pre-fetch confirmation tool. The example '確認 releases/s116/rc-092 存在於 origin' reinforces the precise purpose.

  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?

  Explicitly states when to use: '適合在 fetch 前快速確認遠端分支是否存在'. This clearly implies its role relative to az_git_fetch. However, it doesn't explicitly name the alternative tool or state when not to use it, though sibling context makes this reasonably clear.

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

• az_workitem_updateA
  4/5.0
  Behavior4/5

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

  There are no annotations provided, so the description carries the full burden. It discloses that this is a mutation operation (updates via REST), that json-patch is assembled server-side and restricted to /fields/*, and that historyComment persists to System.History. This is meaningful behavioral disclosure. Minor gaps: no mention of API version, auth requirements, or what the response looks like, but the core mutation semantics and server-side patch assembly are transparently stated.

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

  Conciseness4/5

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

  The description is a single dense paragraph that covers purpose, field format, historyComment behavior, the at-least-one constraint, and the default organization. Every clause serves a purpose and there's no filler. It loses the full 5 only because it's slightly packed/undifferentiated as one long sentence flow rather than clearly front-loaded with the most critical info first, but it is still efficient with zero waste.

  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 straightforward mutation tool with 3 parameters and full schema coverage, the description covers the essentials: field format, historyComment behavior, validation constraint, and default organization. No output schema exists, so describing the return format would be desirable but is a minor gap. Overall it's adequate-to-strong for a filtered mutation tool, though it could mention what the response contains and permission requirements.

  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 100%, so the schema already documents all three parameters. The description adds value beyond this by explaining the field key format ({System.State: 'Resolved'}), that a historyComment writes to System.History, and that at least one of fields/historyComment is required. This enriches the otherwise generic schema descriptions. Would be a 5 if it added more depth on value validation or response behavior.

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

  Purpose4/5

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

  Description clearly states verb+resource (updates work item fields via REST API) and specifies the field reference-name format with an example. It differentiates from siblings by noting it updates only /fields/* and that fields and historyComment are required-or-one. However, it doesn't explicitly contrast with sibling tools like az_workitem_attach or az_workitem_relations, so it loses the full 5 which requires explicit sibling distinction.

  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 clear usage context: how to specify fields using reference names, that a historyComment writes to System.History (Discussion), and the constraint that at least one of fields/historyComment must be provided. It also states the default organization. However, it does not explicitly say when NOT to use this tool or name alternative siblings for other work item operations (attach, relations), so it misses the exclusions that would earn a 5.

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

• az_devopsA
  4.2/5.0
  Behavior4/5

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

  No annotations provided, so description carries the burden. It discloses key behaviors: the 'az' prefix is auto-appended, defaults for organization/project/repository, and auto-fallback to --output json when not specified. It does not cover error behavior, return formats, or permission requirements, but for a generic CLI pass-through tool the disclosed defaults are the most crucial behavioral traits.

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

  Conciseness4/5

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

  Reasonably concise, all in a compact Chinese block. Every sentence earns its place: scope, defaults, output behavior, examples, and fallback instruction. Slightly dense but no wasted words. The example separation and final tip about az_devops_help are valuable additions.

  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 generic CLI tool with no output schema, the description covers scope, defaults, output format, and error fallback. It could mention timeouts, pagination, or authentication requirements, but the essentials are all present. The sibling name az_devops_help provides a natural complement for unknown syntax.

  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 coverage is 100%, so baseline is 3. The description adds meaningful value beyond schema: the 'command' parameter is explained with format expectation (no 'az' prefix) and a concrete example ('repos pr list --status active'). The timeout parameter is documented in schema. Description enriches understanding of how commands map to the parameter.

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

  Purpose4/5

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

  Description clearly states it executes Azure DevOps CLI commands with a specific verb (run 'az' commands), lists allowed command groups (devops, repos, boards, pipelines, artifacts), and the prefix is auto-added. It differentiates from siblings by defining itself as the general CLI executor vs. the specific wrappers like az_pr_show and az_workitem_update.

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

  Usage Guidelines5/5

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

  Excellent guidance: explicitly says to use az_devops_help when syntax is uncertain, specifies default org/project/repo values so users don't need to pass them, and provides concrete examples. This gives clear when-to-use and a fallback path to the sibling az_devops_help tool.

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

• az_workitem_attachA
  4.2/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full burden. It discloses the 100MB size limit, file type support, default org/project, and auth ordering - all useful behavioral details. However, it doesn't mention side effects like whether the upload modifies the work item's state, triggers notifications, or what the response format looks like. It adds reasonable context despite gaps.

  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?

  Two sentences, zero waste. First sentence states purpose, file types, and size limit; second sentence covers defaults and auth. Every clause earns its place and the most important information is front-loaded.

  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?

  The tool has 4 params (all documented), no output schema, and no annotations. The description covers purpose, file limits, defaults, and auth flow - fairly complete for an attachment tool. Minor gap: no mention of behavior on failure or whether attachments replace existing ones, but these are edge concerns for a straightforward upload 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 100%, so all 4 parameters already have property descriptions. The description adds value by clarifying the fileName parameter's default behavior (falls back to filePath's basename) and that filePath requires an absolute path. The defaults for org/project organization context are also helpful beyond the schema.

  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?

  Description clearly states the verb (upload), resource (Azure DevOps work item attachment), and purpose (create link, plain text and binary files, 100MB limit). It distinguishes itself from sibling tools like az_workitem_update and az_workitem_relations by focusing specifically on file attachment.

  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 useful context by stating default organization/project values (SKMHHIS, MS) and authentication precedence (AZURE_DEVOPS_EXT_PAT env var before az login credentials). It doesn't explicitly state when NOT to use it versus alternatives, but the attachment-specific purpose is clear enough given the sibling tools listed.

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

• az_git_fetchA
  4.3/5.0
  Behavior4/5

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

  無 annotations 提供，描述承擔全部責任。描述清楚揭露這是唯讀網路操作、不會動工作目錄、且在 host 端執行。雖未說明授權需求或失敗行為細節，但對這個工具而言已屬充分，僅略遜於完整揭露。

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

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of 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?

  無 output schema、無 annotations，但描述已涵蓋目的、使用情境、不做之事、remote 名稱限制。雖未說明返回格式或錯誤處理，但對一個 fetch 工具而言，該提供的上下文已足夠。

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

  Parameters3/5

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

  schema description coverage 為 100%，所有 5 個參數皆有 schema 內描述。描述本身未再補充參數細節，但說明了 remote 只接受名稱不接受 URL 的約束（此點 schema 也有）。依據高覆蓋率基準，給 3 分合理。

  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?

  清楚說明在主機端對本機 repo 執行 git fetch（唯讀網路操作），並明確指出不動工作目錄。區分了與 sandbox 內 git fetch 的差異，且與其他 sibling（如 az_git_ls_remote、az_devops）有別。

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

  Usage Guidelines5/5

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

  明確說明典型使用情境（Cowork sandbox 內 git fetch 被 proxy 擋 403 時），並說明完成後的效果。也主動排除 push/pull 等寫入操作，提供清晰的 when-to-use 及 when-not-to-use 指引。

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

• az_pr_commentA
  4.4/5.0
  Behavior4/5

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

  No annotations provided, so the description carries full burden. It discloses that filePath auto-prepends '/', that filePath/line/status are ignored when threadId is set, and the default status is 'active'. This covers key behavioral nuances beyond schema. Could add mutation warnings or required permissions, but the disclosed behavior is solid.

  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?

  Two concise sentences covering purpose, dual modes, parameter interactions, and default override behavior. Zero wasted words, front-loaded with the core verb+object. Very efficient.

  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 tool with dual modes (create vs reply) and parameter interdependencies, the description adequately covers mode selection and exclusion rules. It also notes default organization/project/repository inheritance from az_pr_show, aiding cross-tool understanding. Missing: output/return value description, but no output schema exists and the tool's return format is likely obvious. Mutation safety warnings absent but not critical given context.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the baseline is 3. The description adds context about the relationship between filePath/line/status and threadId (that they're ignored when replying), which goes slightly beyond schema. However, it doesn't add syntactic detail beyond what's already in the schema descriptions.

  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 two distinct behaviors: create a new thread (with optional file path/line anchoring) or reply to an existing thread (given threadId). It uses specific verbs (留言/建立/回覆) and differentiates the two primary modes explicitly.

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

  Usage Guidelines5/5

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

  The description explicitly states when to use each mode: '未指定 threadId 時建立新的討論串' vs '指定 threadId 時回覆該討論串', and clearly documents behavioral exclusion ('此時忽略 filePath/line/status'). This is explicit when/alternatives guidance.

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

• az_restA
  4.4/5.0
  Behavior3/5

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

  With no annotations provided, the description carries full behavioral burden. It discloses the auto api-version injection, path base, and overload semantics, which is useful. However, it doesn't disclose auth requirements, error/rate-limit behavior, response format, or consequences of mutations, leaving meaningful gaps for a generic REST tool.

  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?

  Three efficient sentences carry all key information: purpose+preference order, path base+auto version, and required params. No redundancy with the schema, no filler — every clause earns its place.

  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 5-param generic HTTP tool with no output schema and no annotations, the description covers the critical decisions: path construction, api-version default, method constraints, and sibling alternatives. It omits authentication and response-shape details, but given it's an open-ended 'any endpoint' tool, the coverage is appropriately pragmatic for the complexity.

  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 coverage is 100% with descriptions for every parameter. The description adds meaningful context by showing an example path ('MS/_apis/git/repositories/MS-Web/pullRequests/1/threads'), explaining the relative-path convention relative to the organization URL, and clarifying that GET cannot carry a body and api-version defaults to 7.1 — going beyond what the schema enumerates.

  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?

  Description clearly states it sends arbitrary REST requests (GET/POST/PATCH) to Azure DevOps, names the specific path format (relative path after organization), and explicitly enumerates covered sibling endpoints it should yield to. This distinguishes it sharply from the specialized PR/workitem tools while precisely scoping its generic purpose.

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

  Usage Guidelines5/5

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

  Explicitly lists seven specialized tools (az_pr_show, az_pr_changes, etc.) that should be used in preference, and states this tool is only for uncovered endpoints. Also explains path base (https://dev.azure.com/SKMHHIS) and the auto api-version=7.1 behavior — strong when/where-to-use guidance.

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

• az_devops_helpA
  4.5/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the burden of behavioral disclosure. It does disclose the tool behaves identically to `az <command> --help` (a read-only help lookup), which is the key behavioral trait. However, it doesn't describe what happens on invalid commands, output format, or whether it requires authentication — but given the tool's simplicity (a help query), this is adequate but not exhaustive.

  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?

  Description is compact — three sentences that each earn their place: what it does (equivalence to --help), when to use it (before az_devops), and a concrete example. Zero wasted words, front-loaded with the primary purpose.

  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 simple help-query tool with one documented parameter at 100% schema coverage, the description is complete. It explains the tool's role relative to the sibling executor (az_devops), shows usage, and clarifies parameter format. No output schema exists, but since the tool mirrors `az --help` behavior, the return value is self-explanatory.

  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 100% — the single 'command' parameter is already well documented ('命令群組或子命令，不含 az 前綴'). The description adds valuable context beyond the schema by giving a concrete example ('boards work-item update') and explaining the input format expectation, which reinforces the no-'az'-prefix rule. This compensates nicely for the single parameter.

  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 queries official Azure DevOps CLI help (equivalent to `az <command> --help`), with a specific verb (查詢/query), resource (Azure DevOps CLI 命令說明), and a concrete example showing command usage like 'boards work-item update' returning full parameter documentation. It distinguishes itself from the sibling az_devops executor.

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

  Usage Guidelines5/5

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

  Description explicitly states '在不確定子命令或參數語法時先用這個工具，再用 az_devops 執行' — use this tool first when unsure about subcommand or parameter syntax, then execute with az_devops. This is a clear when-to-use directive that names the alternative (az_devops), and shows a working example.

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