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

The annotations already declare readOnlyHint=false and destructiveHint=false, so the description does not need to establish the write-operation profile. It adds genuinely non-obvious context: the operation targets the *current* project implicitly (no project parameter exists), and there is no delete-sprint API, so the creation is effectively irreversible through this toolset. The description does not cover whether duplicate names are allowed or what happens if start_date is after end_date.

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?

Three short sentences with no filler: purpose first, then parameter conventions, then the important API limitation. Every sentence carries distinct information and nothing is repeated from the schema or annotations.

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?

Since an output schema exists, return values need not be explained, and the implicit current-project scoping is stated. What remains thin is whether owner_ids must resolve to actual project members and any constraint between start_date and end_date, which matter for a mutation that cannot be deleted afterward.

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?

Schema description coverage is 0%, so the description must carry the load. It does compensate for the two ambiguous parameters: date format YYYY-MM-DD for start_date and end_date, and owner_ids are member account IDs (not names or emails). The name parameter and date ordering or optionality are left implicit, which keeps it from a 5.

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?

The description states a specific verb and resource: "在当前项目创建迭代" (create a sprint in the current project), which clearly distinguishes it from the read-oriented siblings get_sprint and list_sprints. It does not explicitly name those siblings, but the create-vs-read distinction is unambiguous.

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?

The description implies usage: it says the sprint is created in the current project, so the agent knows no project ID is needed, and it notes that Yunxiao has no delete-sprint API. This preempts a pointless search for delete_sprint. However, it never states prerequisites, such as whether owner_ids must be existing project members, or when to prefer creating a sprint over other organization units.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write/non-destructive profile is covered. The description adds one genuinely useful behavioral hint, that custom_fields is for *required* custom fields (implying creation fails without them), but says nothing about validation errors, notifications to assigned_to, or what happens on partial input.

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?

Two short sentences, front-loaded with the action and scope, with no filler. It is efficient, though the brevity comes partly from leaving most parameters undocumented.

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?

An output schema exists, so return values need not be described. However, for a 12-parameter creation tool with zero schema description coverage, the description leaves too much unexplained, notably where workitem_type_id comes from, what description_format defaults to in practice, and how participants/trackers/verifier identifiers are sourced.

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?

Schema description coverage is 0% across 12 parameters, so the description should compensate. It adds real meaning for two of them: assigned_to expects a member account ID (not a display name) and custom_fields maps names to values for required fields. The remaining ten parameters, including the required workitem_type_id, are left entirely to the bare schema.

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?

The description states a specific verb and resource: '创建工作项' (create a workitem) scoped to '当前项目' (the current project). This lets an agent distinguish it from update_workitem and create_workitem_comment, though the siblings are never named explicitly.

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?

Usage is only implied: 'in the current project' tells the agent not to pass a project id, but there is no guidance on prerequisites such as obtaining workitem_type_id from list_workitem_types or checking list_workitem_fields for required custom fields. No alternatives or exclusions are mentioned.

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

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

注解已声明 readOnlyHint=false、destructiveHint=false，描述补充了“当前项目内”的范围和默认 Markdown 格式。但未说明权限要求、是否支持线程回复、创建后可见性等额外行为，且与注解不矛盾。

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?

单句描述，动作和默认格式前置，没有冗余措辞。但信息量偏少，导致关键参数语义缺失；这更影响完整性而非简洁性。

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?

工具包含 4 个参数且 schema 无参数描述，parent_id 的回复语义和 content 格式要求均未说明。虽然已有 output schema 和注解，描述对于正确调用仍不够完整。

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?

Schema 参数描述覆盖率为 0%，描述仅补充了 format_type 的默认值为 Markdown。workitem_id、content、parent_id 的语义均未解释，尤其 parent_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?

明确说明动词和资源：向当前项目内的工作项添加评论，并注明默认 Markdown 格式。但未明确区分 list_workitem_comments、update_workitem_comment、delete_workitem_comment 等兄弟工具。

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?

隐含用于创建评论，但没有说明何时应使用本工具而非更新、删除或列出评论工具。也未说明 parent_id 用于回复评论等使用场景。

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the danger profile is covered. The description adds useful scoping context (only workitems within the current project) and reinforces the confirmation gate, but says nothing about whether the delete cascades to comments/files, whether it is recoverable, or what errors occur for out-of-project ids.

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?

Two short sentences, zero filler, with the destructive action and its hard requirement front-loaded in that order. Nothing is wasted or buried.

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?

An output schema exists, so return values need no explanation, and the destructive nature is covered by annotations. Still, for an irreversible delete tool the description omits side effects on dependent objects and permission requirements, leaving an agent to guess at the blast radius.

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?

Schema description coverage is 0%, so the description must carry param meaning; it does explain that confirm must be explicitly true, which is the non-obvious parameter. However, workitem_id's format constraint (pattern ^[A-Za-z0-9._-]{1,64}$) and whether it must belong to the current project are left entirely undocumented.

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?

The description states a specific verb (删除) and resource (工作项) plus a scope constraint (当前项目内), which lets an agent distinguish it from list/get/update workitem siblings. It does not explicitly name delete_workitem_comment as the alternative for comments, so it stops short of full sibling differentiation.

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?

The only guidance is the mechanical requirement to pass confirm=true, which merely restates what the required field in the schema already enforces. There is no indication of when deletion is appropriate versus update_workitem, no prerequisites (permissions/ownership), and no warning about irreversibility or impact on related data.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is known without the prose. The description's one addition is the mandatory confirm=true gate, which is genuinely useful behavior, but it says nothing about permissions required, whether deletion is permanent, or what happens when confirm is false or the comment does not exist.

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?

Two short sentences with zero filler: the action comes first and the hard prerequisite second. Nothing is redundant or padded.

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?

The output schema and destructive annotations relieve the description of explaining return values and risk, and the current-project scope is stated. Still, for a destructive mutation with three fully required, undescribed parameters, the definition should clarify what confirm=false produces and any permission requirements.

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?

Schema description coverage is 0%, so the description must carry parameter meaning, yet it only glosses confirm (a boolean whose failure semantics remain unstated). workitem_id and comment_id have no meaning beyond their titles and type constraints, and the phrase 'current project' hints at an implicit context the schema never exposes.

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?

Names a specific verb and resource in one clause – deleting a single comment belonging to a workitem, explicitly scoped to the current project – which cleanly separates it from create_workitem_comment, update_workitem_comment and list_workitem_comments. It stops short of naming those siblings, so differentiation is implicit rather than stated.

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?

The confirm=true prerequisite is a concrete call requirement, but the description offers no guidance on when to prefer this over update_workitem_comment or on any preconditions beyond confirmation. Usage is inferred from the tool name and resource.

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

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

Beyond readOnlyHint=true, the description discloses that identity is derived from the AccessKey rather than a parameter, and that setting YUNXIAO_USER_NAME triggers strict validation — an important failure mode an agent would otherwise not anticipate. It does not discuss scoping to the 'current project' beyond mentioning it, but the added context is substantive.

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?

Two compact sentences front-load the core purpose and then add the comparison hint and validation caveat. Every clause carries information, though the YUNXIAO_USER_NAME clause is terse enough to be slightly opaque.

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?

With an output schema present and no parameters, the description only needed to explain what identity is resolved and how the result is used, which it does. The only gap is the absence of guidance on the 'current project' context and how that scope is determined.

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?

The tool takes zero parameters, so the baseline is 4, but the description spends words on 'identifier' and 'assignedTo,' which are return/comparison fields rather than inputs. It adds no parameter meaning because there are none to clarify.

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?

States a specific verb and resource: retrieve the Yunxiao user bound to the current AccessKey plus that user's member ID in the current project. This clearly separates it from siblings like list_project_members (which enumerates members) and get_project, though it never names an alternative explicitly.

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?

Implies the usage context by saying the returned identifier can be compared against assignedTo, which points at filtering work items by current user, but it never states when to call this versus list_project_members or get_project. The YUNXIAO_USER_NAME note hints at a validation mode but is not framed as a precondition for choosing the tool.

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

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

The readOnlyHint annotation already declares this is a safe read, so the description's obligation is to add information beyond that, and it adds almost none. "Basic information" is unspecified — no indication of which project attributes are returned, whether anything is cached or scoped to the auth context, or any failure mode when no project is configured.

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?

A single short sentence with no filler, and the key qualifier ("currently configured") is front-loaded. It is concise to the point of under-specification, but nothing in the text is wasted.

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?

An output schema exists, so the returned fields need not be spelled out, and with zero parameters there are no inputs to cover. Still, for a tool whose only value is the shape of the project object, the description could have noted what scope of information (settings vs. membership vs. metadata) it returns to help an agent decide to call it.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate, and the baseline for a no-parameter tool applies. The implicit point that the project is resolved from the current configuration rather than supplied by the caller is a small useful addition.

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?

The description states a specific verb and resource ("get ... basic information" of the "currently configured project"), so the agent knows exactly what entity is returned. It does not, however, distinguish itself from siblings like get_current_user or list_project_members, relying on the tool name alone for that separation.

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?

There is no guidance on when to call this versus the sibling tools that also expose project/context data (get_current_user, list_project_members). The phrase "当前配置" implies no identifier is needed, which is a weak usage hint but not an explicit when-to-use rule.

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

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

The readOnlyHint annotation already establishes this is a safe read, so the bar is lower. The description adds a genuinely useful scoping fact — the sprint is resolved within the current project, explaining why no project parameter exists — but says nothing about behavior when the ID is unknown or belongs to another project.

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?

One short sentence with no filler, and the scoping constraint is front-loaded. Nothing is redundant, though there is also very little content to structure.

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?

An output schema exists, so return values need not be described, and with a single self-explanatory identifier parameter this is close to the minimum an agent needs. The remaining gaps (not-found behavior, ID provenance) are minor for a one-parameter read tool.

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?

Schema description coverage is 0%, so the description carries the burden for the single parameter, and it only partially does: 'current project' clarifies that no project identifier is needed, but it never explains what a sprint_id looks like or where to obtain one. The schema's pattern constraint does some of that work, keeping this at a minimum-viable level.

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?

The description names a specific verb and resource ('获取...单个迭代的信息' — get a single sprint's information) and scopes it to the current project, which separates it from the sibling list_sprints by cardinality. It stops short of naming that sibling explicitly, so the differentiation is implied rather than stated.

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?

The phrase '单个迭代' (single sprint) hints that this is the detail-lookup counterpart to list_sprints, but there is no explicit when-to-use or when-not-to-use guidance, and no alternative is named. An agent must infer the list-vs-get routing from the sibling names alone.

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

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

The readOnlyHint=true annotation already tells the agent this is a safe read, so the description's burden is lower. It adds a scoping fact (the item must be in the current project) and explains the meaning of the isMine field, but says nothing about failure behavior for unknown or out-of-project IDs.

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?

A single front-loaded sentence with the scope stated first and no filler. The trailing isMine clause is short but largely restates information the output schema already carries.

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?

For a simple one-parameter read with an output schema and readOnlyHint, the description is minimally sufficient. It still leaves open what 'complete information' includes and how missing or cross-project IDs are handled, which an agent would need before relying on it.

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?

Schema description coverage is 0% and the description never mentions workitem_id — no format, no source (e.g. from list_workitems), no scope constraint. The name is self-explanatory and the schema supplies a regex pattern, but the description adds no meaning beyond the schema.

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?

The description states a specific verb and resource: retrieve the complete information of a single work item inside the current project. The singular 'single work item' clearly contrasts with the sibling list_workitems and get_workitem_file, though no sibling is named explicitly.

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?

Usage is only implied: an agent can infer it should call this when it already has a workitem_id and needs full detail rather than a list. There is no explicit when-to-use/when-not guidance, no mention of alternatives such as list_workitems, and no prerequisites stated.

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

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

Goes well beyond the readOnlyHint annotation: states authentication is required, that images are returned as content while other files come back Base64, that save_to writes to a local directory or full path and returns a usable path, and that the 10 MiB cap applies. It also discloses the input-source restriction (fileIdentifier from rich text). Note that the local write implied by save_to is a side effect the annotation does not capture, but it does not modify remote project data, so this is not a contradiction.

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?

Four short clauses, front-loaded with the core action, then return format, then save_to behavior, then the input/size constraints. Dense but every sentence carries information; nothing is redundant with the schema.

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?

With no output schema, the description correctly spells out the two return shapes (image content vs Base64) and the path returned when save_to is used, plus the size ceiling. Remaining gaps are minor: what happens when a file exceeds 10 MiB, and whether the project is implicit from session context.

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?

Schema coverage is only 33% (workitem_id and file_id are bare patterned strings), so the description must compensate, and it does for file_id by tying it to the fileIdentifier embedded in rich text. save_to semantics (directory vs full filename, omitting it returns content inline) are stated in both places. workitem_id's relationship to the containing work item is only implied.

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?

Uses a specific verb+resource: '认证下载当前项目工作项中的文件或图片', and immediately says what comes back (image content vs Base64). No sibling tool returns files, so differentiation is implicit rather than stated, which keeps it just short of a 5.

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?

Clear context for when to call it: only when you have a fileIdentifier taken from rich text such as a work-item description, and only for files under 10 MiB. No alternative-tool routing is needed here because nothing else in the sibling list fetches files, but the description never states that explicitly.

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

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

With readOnlyHint=true already declaring safety, the description adds that results are scoped to the 'current project' and that the IDs are meant to feed assigned_to, which is useful context. However, it never explains how the 'current project' is determined given there are zero parameters, which is the one real behavioural question an agent would have.

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?

A single compact sentence that front-loads the action and closes with the practical payoff, the assigned_to-ready account IDs. Nothing is redundant or padded.

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?

For a parameterless read with an output schema already documenting return values, the description covers purpose, scope, and intended downstream use. The only gap is the unresolved question of how 'current project' is established, which is a minor omission at this complexity level.

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?

The tool takes no parameters, so there is nothing for the description to disambiguate beyond what the empty schema shows. The baseline of 4 applies; the description implicitly confirms the no-argument nature by describing project scope as 'current' rather than parameterized.

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?

The description gives a specific verb+resource (list current project members) plus what is returned (members and their roles). It stops short of naming how it differs from siblings like get_current_user, but no sibling competes for the same listing job, so the purpose is unambiguous.

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?

The clause 'returns account IDs usable for assigned_to' tells the agent the exact situation that calls for this tool — resolving a user identifier before create_workitem or update_workitem. It gives no explicit exclusions or alternative sources, but the positive context is clear.

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

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

The readOnlyHint annotation already establishes the safety profile, so the description only needs to add context. It does disclose that results are paginated, which is a genuine behavioral trait beyond the annotations, but it does not explain page-token lifetime, ordering, or what happens when the token expires.

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?

A single short sentence with no filler and the action front-loaded. The brevity is efficient, though it shades into under-specification rather than optimal density.

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?

An output schema exists, so return values need not be explained, but for a paginated list tool the description leaves out how iteration terminates and what 'current project' means operationally. The complexity is modest, yet the description still omits the pagination contract an agent must follow.

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?

Schema description coverage is 0%, so the description bears full responsibility for the two parameters, yet it only hints at pagination without explaining that next_token is the continuation token or what max_results controls. An agent must infer both from parameter names alone.

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?

The description names a specific verb and resource with scope: paginated listing of sprints for the current project. It is clearly distinguishable from get_sprint and create_sprint by the listing action, though it never explicitly contrasts with those siblings.

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?

There is no guidance on when to call this versus get_sprint for a single sprint, nor any prerequisite about how the 'current project' is resolved. The only implicit cue is the verb 'list'.

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

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

The readOnlyHint annotation already covers the safety profile, and an output schema exists, so the description only needs to add context. It does add one meaningful trait — that the project is implicit rather than a parameter — but says nothing about ordering, pagination, or behavior when the workitem has no comments or does not exist.

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?

One short sentence with no wasted wording, and the scope qualifier is front-loaded. It is efficient but so terse that it drops information an agent would benefit from.

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?

For a single-parameter, read-only list tool with an output schema, the description is minimally adequate: it identifies the resource and the implicit project scope. It omits result limits, empty-result behavior, and error conditions, which leaves gaps for anything beyond the simplest call.

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?

Schema description coverage is 0% for the single required workitem_id, so the description must carry the burden. It indicates the value identifies 'a certain workitem' but adds no format, source (e.g. from list_workitems/get_workitem), or constraint detail beyond the pattern already in the schema.

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?

The description states a specific verb and resource (list the comments of a workitem) and scopes it to the current project, which separates it cleanly from the create/update/delete_workitem_comment siblings. It stops short of naming any sibling explicitly, so it is clear but not fully differentiated.

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?

There is no statement of when to call this versus e.g. get_workitem or the comment-mutation tools, and no note about prerequisites such as needing an active project context (only implicitly hinted by 'current project'). The usage condition is left entirely to inference from the tool name.

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

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

readOnlyHint=true already tells the agent this is a safe, non-mutating read, so the description's job is lighter. It does add that results include required-ness and option lists, which is genuine behavioral context about what comes back, but it says nothing about ordering, pagination, or whether custom fields are included.

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?

A single compact sentence with the subject and scope front-loaded and zero filler. It is efficient but so terse that useful guidance was dropped rather than trimmed.

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?

The tool is simple (one required param) and an output schema exists, so return values need no explanation here, and the annotations cover safety. The remaining meaningful gap is that an agent is not told how to source a valid workitem_type_id, which is the only way this single-parameter call can fail.

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?

Schema description coverage is 0%, so the description carries the burden; it does clarify that the single parameter identifies a workitem type, which the bare schema (type string + regex pattern) does not state. However, it adds no guidance on where to obtain the ID or what happens if the ID is unknown.

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?

The description gives a specific verb (列出/list) tied to a specific resource (指定工作项类型的字段定义/field definitions of a given workitem type) and even names the payload contents (required flag, options). An agent can tell it apart from list_workitem_types because the object being listed is field metadata, not types. It stops short of 5 only because it never explicitly contrasts itself with the sibling listing tools.

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?

There is no when-to-use guidance, no prerequisite (the caller must already know a valid workitem_type_id, presumably from list_workitem_types), and no mention of alternatives or when not to call it. Usage can only be inferred from the purpose sentence itself.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: results are paginated, multiple status values are treated as alternatives under one condition, assigned_to_me scopes to the current AccessKey user, and each result carries an isMine flag.

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?

Two dense sentences with the core action front-loaded and filter semantics packed efficiently. Nothing is redundant, though the multi-clause second sentence is slightly heavy to parse.

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?

With an output schema present, return values need no explanation, and the description covers pagination, filtering, and the isMine flag. The main gap is that it never explains how next_token drives pagination or what max_results bounds, which matters for an 8-parameter list tool.

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?

Schema description coverage is only 13%, so the description must compensate, and it does for most filters: subject_contains (title), status_ids (multi-value OR semantics), assigned_to, sprint_id, and assigned_to_me. It leaves category (required), next_token, and max_results unexplained, though category's enum and max_results' bounds are self-documenting in the schema.

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?

The description opens with a specific verb and resource: '分页查询当前项目的工作项' (paginated query of work items in the current project), which clearly separates it from the singular get_workitem sibling. It does not explicitly name any sibling tool, so it stops short of a 5.

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?

It lists the available filters (title, status, assignee, sprint) and explains the assigned_to_me shortcut, which implies when to reach for this tool. However, it never states when to prefer get_workitem, list_workitem_statuses, or other siblings, and gives no exclusions or prerequisites.

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

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

The readOnlyHint=true annotation already establishes that this is a safe read, so the description must add behavioral context. It does not say whether results are ordered, whether status flows are complete or partial, or what 'status flow' means operationally. Apart from the phrase '状态流', it adds almost nothing beyond the purpose statement and the annotation.

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?

A single front-loaded sentence with no filler, stating the action and scope immediately. Nothing in it is redundant or padded.

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?

The tool is simple and an output schema exists, so return values need not be explained. However, with 0% schema description coverage on two parameters and the ambiguous 'or' between category and type, the description leaves a real gap about how the parameters combine and which one is mandatory.

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?

Schema description coverage is 0%, so the description must carry the parameter burden. It does hint at a hierarchy by saying '大类或类型' (category or type), which loosely maps to the category and workitem_type_id parameters, but the connective '或' (or) suggests either/or while the schema always requires category and treats workitem_type_id as optional. It never explains the ID format or how the two parameters interact.

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?

The description states a specific verb (列出/list) and a clearly bounded resource (可用状态流/available status flows) scoped to a work item category or type. This is distinguishable from siblings such as list_workitem_types and list_workitem_fields. It stops short of naming an alternative or explicitly contrasting itself with those siblings.

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?

Use context is only implied: an agent infers it should call this when it needs the status flow for a given category or type. There is no explicit when-to-use or when-not guidance, and no mention of prerequisites such as whether the work item type must already exist.

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

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

The readOnlyHint=true annotation already establishes this is a safe read. The description adds useful scope context (results are limited to the current project), but it does not say whether inactive or custom types are included, or anything about ordering or volume.

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?

One short sentence, front-loaded with the verb and scope, with no filler. It is efficient, though its brevity leaves some behavioral detail unstated.

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?

For a one-parameter, read-only listing tool with an output schema and readOnlyHint annotation, the description covers what is needed to invoke it correctly. Only the definition of 'current project' and whether disabled types appear is left implicit.

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?

The single parameter is an enum (Req/Bug/Task), so it is largely self-documenting. The description restates the enum values, which duplicates the schema, and it does not clarify whether 'category' maps to a top-level type grouping in the project.

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?

The description states a specific verb and resource (list work item types) and scopes it to the current project and a category (Req/Bug/Task). An agent can understand the purpose without opening the schema, though it does not distinguish itself from siblings like list_workitem_fields or list_workitem_statuses.

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?

Usage is only implied: the agent can infer this belongs to a discovery step for work item types, but the description never says when to pick this over list_workitem_fields or list_workitem_statuses, nor does it state prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=true, so the safety profile is covered. The description adds the non-obvious constraint that description cannot travel inside fields, which is real value. What is missing is whether fields is a merge or a full replace, and what happens to fields not listed — critical for a tool the annotations flag as destructive and idempotent.

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?

Two sentences, front-loaded with the action, then the parameter rule. There is no filler or restatement of the tool name, though the description is thin enough that brevity is partly a symptom of under-specification rather than discipline.

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?

An output schema exists, so return values need not be described. But for a destructive four-parameter mutation with zero schema description coverage, an agent still lacks merge-vs-replace semantics, permission requirements, and any hint about the description_format enum. Adequate to attempt a call, not adequate to call it safely.

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?

Schema description coverage is 0%, so the schema supplies only types, defaults, and a pattern. The description partially compensates by explaining that fields maps field identifiers to new values and excludes description, and that description has its own parameter. workitem_id and description_format (MARKDOWN/RICHTEXT) are left entirely to inference, and no example field identifiers are given.

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?

The description uses a specific verb and resource ('更新...工作项') and scopes it to the current project, so the agent knows exactly which entity is being mutated. It does not explicitly contrast itself with siblings like create_workitem or update_workitem_comment, but the resource is distinctive enough that confusion is unlikely.

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?

The second sentence gives a concrete rule for splitting input between the fields map and the description parameter, which is genuinely useful operational guidance. However, there is no statement of when to prefer this tool over siblings, no preconditions (permissions, workitem state), and no warning about the destructive nature of the call despite destructiveHint=true.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known from structured data. The description adds nothing beyond them: it does not say whether the update replaces the entire comment body or merges, whether the previous text is recoverable, or whether ownership is required — all material for a destructive mutation.

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?

It is one short, front-loaded sentence with no wasted words, but the brevity is under-specification rather than economy — the only sentence present conveys little beyond the tool name.

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?

An output schema exists, so return values need no explanation, but for a destructive mutation of a comment in a shared project the definition should cover replacement semantics, permissions, and the enumeration parameter. With 0% schema coverage and no behavioral detail, the definition is incomplete for its complexity.

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?

Schema description coverage is 0%, so the description carries the full burden for four parameters, yet it mentions none of them. It does not explain the format_type enum (MARKDOWN vs RICHTEXT), the workitem_id pattern, or the fact that content is a full replacement of the comment body.

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?

The single sentence gives a specific verb and resource (修改...一条评论 = modify one comment) scoped to the current project, which separates it from create_workitem_comment and delete_workitem_comment. It stops short of naming those siblings or any distinguishing scope detail, so it is clear but undifferentiated beyond the verb.

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?

There is no guidance on when to use this tool versus the sibling comment tools, no prerequisite or permission conditions, and no statement about what it takes to edit someone else's comment. The agent must infer everything from the verb alone.

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