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

Annotations declare readOnlyHint=false and destructiveHint=false, so the agent already knows this is a non-destructive write. The description adds nothing beyond that: no note on where the item is appended, whether it requires issue edit permissions, what happens with an invalid issueId, or whether the call is 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?

A single front-loaded sentence with zero filler. It is efficient, though arguably thin rather than fully earning its brevity given the tool's five parameters.

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?

There is no output schema and the schema covers parameters, so the main gap is behavioral: a mutation tool with no indication of permissions, ordering, or side effects. The description is minimally viable but leaves the agent to infer everything about the write's consequences.

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 100%, so all five parameters (issueId, text, checked, assignee, deadlineDate) are already documented in the schema, including the deadline format. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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 (add) and resource (checklist item) scoped to an issue, which distinguishes it somewhat from the generic plural sibling add_entity_checklist_items. However it never explains how it differs from that entity-level sibling or from edit_checklist_item/delete_checklist_item, so the differentiation is only implicit.

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?

No when-to-use guidance, no prerequisites, and no mention of alternatives such as add_entity_checklist_items or edit_checklist_item. The agent must infer applicability from the name 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?

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write-but-not-destructive profile is known. The description adds the useful detail that comment text supports Yandex Flavored Markdown, but says nothing about permissions, whether the comment is returned, or how edits differ.

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 core action front-loaded ahead of the formatting note. Nothing 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?

For a two-parameter tool with full schema coverage, annotations covering safety, and no output schema, the description is nearly sufficient — it names the action and the supported markup format. The only gap is the lack of any routing hint against the many comment-related siblings.

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 100% (both text and issueId are documented in-schema), so the baseline is 3. The description adds no parameter-level detail such as the issue key format or text length limits beyond what the schema provides.

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 ('Add a comment to an issue'), which is unambiguous. However, it does not distinguish itself from near-identical siblings such as add_entity_comment and add_entity_comment, so an agent cannot tell from the description which entity scope applies.

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?

No guidance on when to use this versus add_entity_comment, edit_comment, or import_issue_comment, and no stated prerequisites (e.g. needing an existing issueId). Usage must be inferred entirely from the 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?

Annotations tell the agent this is a non-read-only, non-destructive mutation, but the description adds nothing beyond that. It does not say whether adding a duplicate reaction is idempotent or an error, whether reactions can be removed, who may react, or what happens on success — all meaningful for a mutation tool.

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?

The single sentence is front-loaded and waste-free, but it is under-specified rather than optimally concise — it omits information that would make the sentence earn more of its place.

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 three-parameter tool with full schema coverage and annotations, the essentials are present across structured fields. Still, the description leaves behavioral questions (idempotency, error on duplicate, return behavior) unanswered, and there is no output schema to compensate.

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 100%, so issueId, commentId, and the reaction enum are fully documented in the schema, which sets the baseline at 3. The description contributes no additional parameter meaning (e.g., whether reaction must match the exact enum casing, or that commentId accepts a longId form).

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 ("Add a reaction to a comment"), which is unambiguous about the operation. However, it offers no differentiation from related siblings like add_comment or add_entity_comment, so an agent must rely on the name alone to route correctly.

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 mention of prerequisites (e.g., needing an existing comment), and no routing to alternatives such as add_comment or the entity-comment equivalents. The agent must infer all usage context 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?

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write/safety profile is covered structurally. The word "temporary" hints that the temp file is consumed or promoted by this call, but the description never states what happens to tempFileId afterwards or that notify triggers notifications, leaving real behavioral gaps against a low annotation bar.

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 that states action, prerequisite, and scope with zero filler. 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?

For a mutation tool with no output schema and 4 parameters, the description covers the core action but omits what notify does, what happens to the temp file after attaching, and whether permissions on the target entity are required. Adequate but with clear gaps.

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 50%: entityType and tempFileId are documented in the schema, and the description redundantly reinforces the temp-file source and entity types. The two undocumented parameters, entityId and especially notify, get no meaning from the description at all. Baseline 3 is appropriate.

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 ("Attach a temporary file") and enumerates the exact entity scope (project, portfolio, goal), which separates it from the many other attachment siblings like upload_issue_attachment and list_entity_attachments. It stops short of explicitly contrasting itself with the closest siblings, so it is clear but not fully differentiating.

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 names the prerequisite source of the file ("from upload_temp_attachment"), which tells the agent this tool must be preceded by the upload step. There are no explicit when-not conditions or alternative routing, so it is clear context without 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 declare readOnlyHint=false and destructiveHint=false, so the safety profile is known, but the description adds almost nothing beyond that. It doesn't explain whether a missing checklist is auto-created, what the notify flag triggers, or how duplicate items are handled — meaningful behavioral gaps for a write tool.

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 compact sentence with the resource front-loaded and no filler. It is efficient, though the brevity is partly what leaves the semantics underspecified.

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?

A 4-parameter mutation tool with low schema coverage and no output schema needs far more than one sentence. Key facts — create-versus-append semantics, notify behavior, item field meanings — are absent, leaving the agent to guess before invoking.

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 25%, so the description must compensate, and it largely doesn't. It conveys the project/portfolio scope but says nothing about notify, about the per-item fields (checked, assignee, deadline), or about ordering/deduplication of appended items.

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+resource: creating a checklist or appending items to a project/portfolio checklist, which is more than a tautology. However, it does not distinguish this from the many checklist siblings (add_checklist_item, update_entity_checklist, update_entity_checklist_item), and it leaves the create-vs-append behavior ambiguous enough that an agent can't tell which path it will take.

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?

No when-to-use guidance, no mention of alternatives, and no conditions selecting this over add_checklist_item or update_entity_checklist. The only hint is the entityType field's scope note in the schema, not the description.

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 the target-entity scope but says nothing about notification behavior, permissions, or the created comment's shape; adequate but thin given annotations carry the safety signal.

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 verb first and no wasted words. It is appropriately sized for a simple create tool, though its brevity contributes to the missing usage and behavioral detail elsewhere.

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 3-param, fully documented create tool with annotations and no output schema, the description is minimally sufficient. It omits when to prefer it over add_comment and any post-write behavior, leaving gaps an agent might need.

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 100% and all three required params are documented, including the entityType enum. The description's mention of the three entity types echoes the enum but adds no syntax, format, or constraint detail beyond the schema, so baseline 3 applies.

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+resource ("Add a comment") and scopes it to three entity types (project, portfolio, goal). This scope implicitly distinguishes it from the sibling add_comment, which targets issues, so an agent can route correctly without opening either schema.

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?

No when-to-use or when-not-to-use guidance is given, and no alternative tool is named. The agent must infer that this applies to non-issue entities and that add_comment handles issues, but nothing in the text states this.

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 agent knows this is a non-destructive write. The description adds genuinely useful behavioral context about how the tracker interprets duration (5-day weeks, 8-hour days). It omits side effects such as whether the worklog affects remaining estimate or logged-time totals.

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 tight sentences with the core action front-loaded and no filler. The duration-interpretation note is a slightly niche detail but still earns its place given the schema's ISO 8601 examples.

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 four-parameter mutation tool with a fully documented schema and annotations covering the safety profile, the description is largely complete. Missing pieces are permission requirements and whether creating a worklog mutates derived time-tracking fields.

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 100%, so all four parameters are documented in the schema itself, setting the baseline at 3. The description's explanation of P5D = 1 week meaningfully supplements the duration parameter's ISO 8601 format, but adds nothing for start, comment, or issueId.

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 ('Add') and resource ('time tracking record to an issue'), so an agent knows it creates a worklog entry. It does not distinguish itself from siblings such as import_worklog_record, edit_worklog_record, or find_worklog_records, leaving the add-vs-import boundary to inference.

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?

No when-to-use guidance is given. The description never mentions alternatives like import_worklog_record (bulk) or edit_worklog_record (modify), nor any prerequisites such as required issue permissions or whether the issue must be open.

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 agent knows this is a non-destructive mutation. The description adds the 'finished sprint' precondition but says nothing about reversibility, whether the sprint disappears from boards, or permission requirements. Adequate given annotations, but thin.

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, which is appropriate for a two-parameter tool. The parenthetical is slightly cryptic but costs almost nothing.

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 low-complexity two-parameter mutation with no output schema, the description covers the core action and precondition. It omits any post-archive behavior and leaves one required parameter undocumented, so it is only minimally sufficient.

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 50%: 'version' is documented as 'Current sprint version' while 'sprintId' has no description. The parenthetical '(version = sprint version)' only restates what the schema already says and does not compensate for the undocumented sprintId.

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+resource ('Archive a sprint') plus a precondition ('finished'), which distinguishes it from generic state changes. It does not explicitly name siblings like delete_sprint or update_sprint, so the differentiation is only implicit.

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?

'Finished sprint' implies when the tool is applicable, but there is no explicit when-not guidance and no routing to alternatives such as delete_sprint or start_sprint. Usage is inferred rather than 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?

Annotations declare destructiveHint=false, but the description says Components, versions and projects are 'cleared by default' — irreversible data loss — and the schema's confirm parameter is itself labeled 'this destructive/bulk operation.' The description's disclosure of data-clearing directly conflicts with the non-destructive annotation, which triggers the Annotation Contradiction rule.

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 tight sentences, front-loaded with the action and followed by the most consequential caveat (default field clearing). Every sentence earns its place; there is no filler or repetition.

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 bulk mutation with 4 documented params but no output schema, the description covers the core action and the key side effect. It omits the confirm requirement, notification behavior, and routing to sibling tools, leaving gaps an agent must close from the 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 description coverage is 100% (queue key, issues list-or-filter syntax with 10000 limit, notify, confirm are all documented in the schema). The description adds no parameter-level meaning beyond the schema, so the baseline 3 for fully-covered schemas applies.

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 ('Bulk move issues to another queue'), and the 'Bulk' qualifier distinguishes it from the single-issue move_issue. It does not, however, name or contrast with the closest siblings (move_issue, bulk_update_issues, bulk_transition_issues), so an agent still has to infer the boundary.

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 gives no when-to-use guidance, no alternatives, and no prerequisites. It never mentions that confirm=true is required to execute, nor when to prefer this over move_issue or bulk_transition_issues. The clearing statement is behavioral context, not usage guidance.

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 declare readOnlyHint=false and destructiveHint=false, and the description adds genuinely useful non-schema context: the dependency on get_issue_transitions and the resolution requirement for 'closed' transitions. It omits operational caveats such as the async/bulk-tracking behavior (get_bulk_operation_info) and the 10,000-issue cap, which live only in the schema.

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 tight sentences, front-loaded with the core action, each adding a distinct actionable fact (mechanism, prerequisite tool, edge-case requirement). No filler or restatement of 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?

For a 5-parameter bulk mutation with nested objects and no output schema, the description covers the key gotchas (transition ids, resolution requirement). It is only slightly incomplete in not signaling that this is a large-scale operation worth tracking via get_bulk_operation_info.

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?

With 100% schema coverage the baseline is 3, but the description adds meaning beyond the schema by explaining that statuses like 'closed' may require a 'resolution' entry in values and that transition ids come from get_issue_transitions. It does not document notify, confirm, or the filter-string form of issues, which the schema already covers.

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+resource+mechanism ('Bulk move issues to a new status via a workflow transition'), which distinguishes it from single-issue execute_transition. It does not explicitly distinguish itself from the sibling bulk_move_issues or bulk_update_issues, so the agent must infer the difference, keeping it below 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?

Gives a clear prerequisite/navigation hint ('Get available transition ids via get_issue_transitions') and a conditional rule about resolution for closed statuses. It stops short of naming when NOT to use this versus bulk_move_issues or execute_transition, so no explicit exclusion is provided.

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 declare readOnlyHint=false and destructiveHint=false, so the write nature is known, but the description adds nothing beyond that: it does not explain that a `confirm: true` acknowledgement is required, whether per-entity failures abort the whole batch, or whether `fields` merges into or replaces existing values. Note the schema's `confirm` text calls this a 'destructive/bulk operation', which conflicts with destructiveHint=false – a tension the description does nothing to resolve.

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 verb and target resources first and the modified attributes after the colon; there is no filler. It is slightly cramped but appropriately sized for the tool.

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 six parameters (including nested objects), two required fields, and no output schema, the description is too thin: it omits the confirmation requirement, batching limits, failure semantics, and which entity types/ids go where. An agent would have to infer the safe invocation pattern entirely from the 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 description coverage is 83%, so the schema already carries most parameter meaning. The description's enumeration of 'fields, comment and links' loosely maps to three of the six parameters but adds no syntax, format, or constraint detail beyond what the schema provides – the baseline 3 for high coverage.

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 (bulk update) and the three resource types it operates on (projects, portfolios, goals), plus what is changed (fields, comment, links). This implicitly separates it from siblings like bulk_update_issues and bulk_move_issues, but it never names an alternative tool 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?

There is no when-to-use or when-not-to-use guidance, no mention of prerequisites, and nothing about the required `confirm` flag or any cap on how many entities can be updated in one call. 'At once' only hints at the efficiency motivation without stating conditions.

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 establish this is a non-read-only, non-destructive write, so the description's added burden is lighter. It usefully explains that values follow the issue edit format and that array fields support add/set/replace merge commands, but it stays silent on permissions, reversibility of overwrites, and what the call returns. Note the tension worth surfacing to the agent: the schema's confirm parameter calls this a 'destructive/bulk operation' while destructiveHint is false.

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 operation and its limit, followed by exactly one concrete syntax example. No filler, and the compact inline JSON example is the most efficient way to convey the command 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?

For a high-impact bulk mutation tool with nested objects and no output schema, the description covers scale and value syntax but omits what the agent gets back (a bulk operation id?), whether confirm=true is required to proceed, and what permission level is needed. The sibling get_bulk_operation_info hints at an async result the description never mentions.

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 100%, so a baseline of 3 applies, but the description goes beyond the schema by documenting merge semantics for array fields ('add'/'set'/'replace'), which the schema's generic 'Fields to set' wording does not convey. It does not elaborate on the issues/filter string or notify parameters, but those are already well covered 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?

States a specific verb and resource ('Bulk edit many issues at once') plus a hard scope limit (max 10000), so an agent immediately knows this is a multi-issue write. It does not, however, distinguish itself from nearby siblings such as bulk_update_entities, bulk_move_issues, or bulk_transition_issues, leaving the agent to infer the boundary.

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 explicit when-to-use statement, no prerequisites, and no named alternative (single edit_issue, or the more specific bulk_move/bulk_transition tools). The only implicit signal is the bulk scope plus the 10000 cap, which is a constraint rather than routing guidance.

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 as a safe, non-mutating read. The description adds little beyond that: it doesn't say whether counts are exact or approximate, whether the query language can be passed alongside filter, or how results are bounded. Essentially no behavioral context beyond 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?

One short, front-loaded sentence with zero padding. Nothing to trim and the key noun ('number of issues') appears immediately.

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 does at least state the return is a count, which covers the essentials for a trivial aggregation tool. What's missing is how the three optional, non-required parameters interact when several are supplied.

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 100%, so the schema already documents query ('Tracker query language string'), queue ('Queue key'), and filter. The description echoes 'filter or query' and omits queue and any precedence rules, so the baseline 3 is appropriate.

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+resource pair ('Get the number of issues') and the scoping dimension ('matching a filter or query'). It is clearly distinguishable from find_issues by being a count rather than a listing, though it never names that sibling 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?

No guidance on when to use this instead of find_issues or search_entities, and no statement about what happens if query, queue, and filter are combined. The agent must infer that this is the cheap 'how many?' alternative to a full search.

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 establish that this is a write operation that is not destructive. The description adds genuine value beyond them by disclosing the API routing quirk ('the legacy POST /boards ignores body parameters') and the status-key mapping semantics, but it omits permission requirements, default behavior, and failure modes.

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 tightly packed sentences with the core action front-loaded and no filler. The mid-sentence parenthetical about the legacy endpoint is useful but slightly interrupts the flow.

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 7-parameter create tool with a nested object and no output schema, the description covers purpose, one param nuance, and an API caveat. It leaves unaddressed the default-columns behavior, permission implications of boardPermissionsTemplate, and expected outcome, keeping it at minimum-viable.

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?

With 100% schema description coverage, the baseline is 3. The line 'Columns map board columns to issue status keys' slightly reinforces the nested columns parameter, but most parameter meaning is already carried by 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 ('Create a new task board'), which is unambiguous and distinct from sibling mutation tools like update_board or create_board_column. It does not explicitly name a sibling it replaces, 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?

There is no guidance on when to use this versus alternatives such as checking existing boards with get_boards, nor any exclusions or prerequisites. Usage is only implied by the verb 'Create'.

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 real operational context beyond that: the version field drives an If-Match lock and must be sourced from get_board, which hints at optimistic concurrency behavior.

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 terse sentences, front-loaded with the action and followed by the one non-obvious prerequisite. 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.

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

For a four-required-parameter create mutation with no output schema, the description plus annotations and schema cover what an agent needs to invoke it. Minor gaps remain on column semantics (ordering, statuses meaning), but nothing critical is missing.

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 50% (version and statuses documented). The description uniquely clarifies the version parameter's role as an If-Match lock and tells the agent where to obtain it, adding meaning the schema's terse 'Current board version' does not. name and boardId remain undocumented but are self-evident.

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 column on a board'), which cleanly separates it from create_board, update_board_column and get_board_column. It does not name a sibling explicitly, so it falls 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 gives one concrete prerequisite for the version parameter (get it from get_board), which is genuinely useful. However, it offers no when/when-not guidance against alternatives like update_board_column or create_board, and no note on when to use this versus other column operations.

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 safety is covered structurally. The description adds nothing beyond that: no permission requirements, no uniqueness/duplicate-name behavior, no indication of what is returned or whether the component is auto-assigned.

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 grammatical, front-loaded sentence with zero filler. It is terse rather than padded, though its brevity borders on under-specification for a mutation tool.

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 create/mutation tool with no output schema and only safety annotations, the description omits what an agent would want: required permissions, what happens on a duplicate component, and whether the created object is returned. The rich schema covers inputs but the behavioral picture is incomplete.

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 100%, so all five parameters (lead, name, queue, assignAuto, description) are already documented in the schema. The description adds no syntax, format, or constraint detail beyond that, so the baseline 3 applies.

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 ('Create a component in a queue'), which cleanly separates it from the get_component/update_component/delete_component siblings. It does not name any alternative or explain its relationship to get_queue_components, but the verb alone is discriminating enough for selection.

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 prerequisites (e.g. the queue must exist), and no mention of alternatives such as create_queue_components flows. The agent gets only the bare action.

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 mutation and safety profile is covered. The description adds that it targets an existing dashboard and creates a cycle-time chart, but does not disclose permissions, failure behavior, or return values; with annotations present, this is adequate but not rich.

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?

The description is two sentences: a front-loaded purpose statement followed by a critical source-priority rule. There is no filler, and every sentence earns its place.

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 15-parameter creation tool with no output schema, the description plus the rich schema and annotations provide enough to invoke it correctly. It covers the purpose and key parameter precedence, though minor gaps remain around return values and permissions.

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 100%, so the schema already documents each parameter and the baseline is 3. The description adds non-obvious precedence among filterId, query, and filter, which is not stated in the schema and directly affects how issue sources should be supplied.

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: "Add a 'Cycle time' chart widget to an existing dashboard." It clearly distinguishes this widget-creation tool from sibling tools such as create_dashboard or create_board.

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 gives clear context that the dashboard must already exist and provides an explicit precedence rule for issue sources: filterId > query > filter. It does not name alternative tools or when not to use this tool, but the usage context and parameter-selection guidance are actionable.

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 safety is covered externally. The description adds nothing beyond that: it does not say whether a project/context is required, what happens to defaults like owner and layout, or what is returned on success.

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, front-loaded and free of filler. Its brevity is efficient rather than bloated, though it borders on under-specification for a create tool with three parameters.

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 a fully documented schema and annotations covering the safety profile, the minimum an agent needs is present. However, for a creation tool with no output schema, the description omits prerequisites (permissions, owning context) and any indication of the result, leaving gaps that neither annotations nor schema fill.

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 100%, including defaults for owner and layout and an enum for layout, so the schema carries the parameter burden. The description adds no syntax, format, or meaning beyond the schema, which is the baseline 3 case.

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?

It states a verb (Create) and a resource (dashboard), so the operation is identifiable, but the sentence is essentially a restatement of the tool name with no scope, no field mention, and no differentiation from other create_* tools in the sibling list.

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 about when to use this tool, when not to, prerequisites, or which alternative to prefer. The agent gets no routing information beyond the name 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=false and destructiveHint=false, so the mutation nature is known. The description adds nothing further: no mention of required permissions, whether creation is idempotent, what happens with the free-form 'fields' and 'links' payloads, or what a successful create returns.

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 a single short sentence with zero waste and the verb is front-loaded. However, for a tool with a free-form fields bag and nested link objects, this level of brevity reads as under-specification rather than disciplined conciseness.

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?

Against a 4-parameter schema with nested objects, a polymorphic 'fields' bag and no output schema, the one-line description leaves major gaps: how the different entity types differ, what fields apply to which type, and how links should be formed. It is not complete enough for confident invocation.

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 100%, so the schema already documents all four parameters, including the enum and the nested links/fields objects. The description merely repeats the entityType enum values and adds no syntax, format, or constraint detail beyond it, so the baseline of 3 applies.

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 ('Create') and enumerates the three creatable resource types ('project, portfolio or goal'), which maps directly to the entityType enum and separates it from narrower siblings like create_project or create_board. It does not explain, however, why an agent would call create_entity instead of the sibling create_project when creating a project.

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 or when-not-to-use guidance. The description never mentions the sibling create_project/create_board tools, prerequisites, or permissions, so the agent must infer routing from the name 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?

Annotations declare readOnlyHint=false and destructiveHint=false, so the agent already knows this is a non-destructive write. The description adds directional semantics ('works towards' → goal, 'is supported by' ← project) which clarifies link orientation, but it says nothing about duplicate handling, whether calls are additive, permission requirements, or failure behavior. Modest added value over the annotations.

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, purpose front-loaded, no filler. The second sentence is dense and its quoted relationship vocabulary with arrows is somewhat cryptic, but every clause carries information about valid inputs.

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 write tool with no output schema and only safety-hint annotations, the description covers entity types and valid relationships but omits how the target entity is referenced and what happens on invalid/duplicate links. Adequate but with a real gap for correct invocation.

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 67% and the nested 'entity' and 'relationship' fields have no schema descriptions at all. The description compensates by enumerating the valid relationship strings and their direction/orientation per entity type, which is the most important semantic gap. It does not explain the format of the 'entity' target reference (ID vs. key), leaving one required field ambiguous.

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 clear verb+resource: 'Link a project/portfolio/goal to other entities', and enumerates the entity types it operates on. It does not name its siblings (get_entity_links, delete_entity_link) to differentiate itself, so an agent must infer the read/delete counterparts from naming alone.

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?

No when-to-use guidance, no prerequisites, and no mention of alternatives such as get_entity_links for reading or delete_entity_link for removal. The agent must infer that this is the create counterpart of those siblings from name similarity only.

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-but-non-destructive profile is covered. The description adds the relationship default, but says nothing about what the backlink option actually does as a side effect, permission requirements on the external app/connector, or idempotency of re-linking the same object.

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 tight sentences with the core action front-loaded and the default-value tip second. Nothing is padded, though the parenthetical connector example is the only slightly expendable element.

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 write tool whose safety profile is carried by annotations, with a fully described 5-parameter schema and no output schema, the description is nearly sufficient. It could do more on external-app prerequisites and the backlink side effect, but an agent has enough to invoke it correctly.

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 100%, so all five parameters are already documented in the schema, including origin pointing to get_external_applications and relationship's 'usually RELATES'. The description's relationship default largely restates the schema's own hint, adding little new meaning, so the baseline 3 applies.

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 ('Link an issue to an object in an external application') and scope (via a connector, e.g. Jira), which implicitly separates it from the internal-linking sibling create_issue_link. It stops short of naming the sibling that it should not be confused with, so differentiation is inferred rather than explicit.

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 gives a conditional default ('Use relationship "RELATES" unless the app docs say otherwise'), which is useful invocation guidance, but there is no explicit when-to-use vs when-to-use-an-alternative (e.g. vs create_issue_link or get_external_links), and no prerequisites are stated. Usage is implied by the verb rather than spelled out.

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, and the description's 'Create' is consistent with that write signal. However, it adds nothing beyond the annotations: no word on name-collision behavior (error vs replace), whether the filter is personal or shared, or any auth requirement. It is essentially a restatement of the title.

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, front-loaded sentence with zero filler. It is efficient, though the brevity edges toward under-specification rather than true economy.

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 seven-parameter write tool with nested objects and no output schema, one sentence is not enough. It omits what a filter consists of at a high level and how it relates to update_filter, leaving the agent to reconstruct intent from the schema alone.

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 100%, so all seven parameters (name, query, sorts, fields, filter, folder, groupBy) are already documented in the schema, including the query/filter mutual exclusivity and the 'replaces fully' note. The description adds no parameter meaning, so baseline 3 applies when the schema does the heavy lifting.

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 (Create) and resource (saved filter) and adds the target scope ('for issue lists'). The verb implicitly distinguishes it from the get_filter/update_filter/delete_filter siblings, though it never names them, so the differentiation rests on the verb alone.

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?

No when-to-use context, no prerequisites, and no mention of update_filter as the alternative when a filter already exists. The agent must infer that 'create' means a new filter rather than modifying an existing one.

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 declare a write operation (readOnlyHint=false) that is not destructive (destructiveHint=false), so the safety profile is covered. The description adds the admin-rights requirement, a useful auth constraint, but does not describe bulk behavior, validation, or return semantics.

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 core action and then the prerequisite. No wasted words.

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 bulk-create tool accepting up to 100 nested absence objects with no output schema, the description omits key operational details such as bulk capability, partial-failure behavior, and date-format constraints. It is under-specified for the tool's 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% at the top level; the description only gives examples of absence types that are already enumerated in the schema's workflow field. It does not explain the required 'gaps' array structure, maxItems=100, or the required nested fields (user, workflow, from, to).

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 'Create' and resource 'employee absences', and clarifies the jargon 'gaps' with examples (vacation, illness, trip). It implicitly distinguishes from sibling find_gaps and delete_gaps by verb, though it does not name them 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?

It provides a prerequisite ('Admin rights required') but no explicit guidance on when to use this tool versus find_gaps, delete_gaps, or other create tools. Usage is implied by the verb 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?

Annotations already declare readOnlyHint=false and destructiveHint=false, so the write-but-non-destructive profile is covered. The description adds genuinely new context: the mandatory queue field and that text fields accept Yandex Flavored Markdown. It says nothing about permissions, queue-level required fields, or what happens to nested extraFields.

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, front-loaded sentences with no filler; the core action leads and constraints follow. The Markdown sentence is the weakest earner but still useful information an agent cannot get elsewhere.

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 22-parameter creation tool with no output schema, the description is thin: it omits any hint about the escaped-hatch extraFields/update-command mechanism, attachment handling, or the queue-vs-summary required-field discrepancy. The rich schema and annotations carry most of the load, leaving this merely adequate.

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 100%, so the schema already documents all 22 parameters, including the complex nested extraFields object. The description's only addition is generalizing YFM support to all text fields (the schema only says this for 'description'), which is a marginal gain over structured data.

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 ('Create a new issue in Yandex Tracker'), which is clearly distinguishable from siblings like edit_issue, bulk_update_issues, and import_issue. It does not explicitly name or contrast those alternatives, 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?

The description notes prerequisites ('Requires queue key and summary') but gives no when-to-use guidance, no mention of alternatives for related operations (edit_issue, import_issue, create_entity), and no exclusions. Note that 'summary' is stated as required here while the schema's required list contains only 'queue'.

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 agent knows this is a non-destructive write. The description adds only the admin requirement; it says nothing about whether re-creating with an existing id fails, what side effects occur on existing issues, or any rate/scope limits for an 11-parameter creation tool.

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 that front-load the action and then spend the rest on the highest-uncertainty parameter. Dense but each clause carries information; no filler.

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 an 11-parameter admin creation tool with no output schema and 55% schema coverage, the description covers the trickiest parameter but leaves half the surface (visibility flags, ordering, readonly, description) unexplained. Minimum viable rather than complete.

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 55%, and the description compensates well for the critical `type` parameter by enumerating valid class names and the container=true variant, which the schema only gestures at with a wildcard. However, order, hidden, visible, readonly, and description remain undocumented in both places.

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 ("Create a global issue field") and flags the admin privilege needed. It distinguishes global fields by implication from the local-field siblings (create_queue_local_field), though it never names that distinction 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?

The only usage signal is the parenthetical "(admin)", which hints at a permission prerequisite but is not elaborated. No guidance on when to use this versus create_queue_local_field, create_issue_field_category, or update_issue_field, and no prerequisites or duplicate-handling notes.

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 safety profile is covered. The description adds one piece of context beyond that — '(admin)' signals an elevated permission requirement — but says nothing about uniqueness constraints, idempotency, or what happens to existing field assignments when a category is created.

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; the verb and resource come first. It is marginally under-specified rather than padded, but structurally efficient.

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 mutating configuration tool with no output schema and one of three parameters undocumented, the description omits what an issue field category is, how it relates to issue fields, and whether the return value is the new category. Only the admin permission note carries useful 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 67% (name and order have descriptions; description does not). The description provides zero parameter detail, so the undocumented 'description' field is left entirely unexplained and no extra meaning is added for name (localized string form) or order (display weight).

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?

Specific verb (Create) plus resource (issue field category), which is clear enough to distinguish from create_issue_field and update_issue_field_category. The '(admin)' tag adds a useful qualifier, but the description does not explicitly contrast the tool with its nearest siblings, so it falls 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?

There is no when-to-use guidance, no prerequisites beyond the parenthetical '(admin)', and no mention of alternatives such as update_issue_field_category or create_issue_field. The agent must infer that this is a configuration/setup operation.

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 safety profile is known. The description adds nothing beyond restating that a link is created: no idempotency behavior on duplicate links, no permission requirements, no note that this applies only to issue-type entities versus other entity types.

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 wasted words. It is appropriately sized for the tool, though it is arguably too terse to be maximally useful.

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?

A simple three-parameter tool with a complete schema and no output schema, so the description need not explain return values. However, for a mutation it omits the one piece of context an agent needs for correct invocation: that relationship values come from configured link types.

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 100% and the enum for 'relationship' is fully enumerated in the schema, so the schema carries the parameter burden. The description adds no additional meaning such as which relationship values are valid in practice or how issueId/issue accept keys vs ids. Baseline 3 applies.

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 ('Create a link between the current issue and another issue'), and the scope ('current issue' + 'another issue') is concrete. It does not distinguish itself from near-siblings such as create_entity_link or import_issue_link, but an agent can still tell what it does.

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?

No when-to-use, when-not-to-use, or alternative guidance is given (get_issue_links, delete_issue_link, create_entity_link are never mentioned). It also never says that the 'relationship' value must come from the link types exposed by get_link_types, which is the main usage precondition.

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 declare readOnlyHint=false and destructiveHint=false, and the description's 'create a saved report' is consistent with that non-read-only, non-destructive profile. It adds the mutual-exclusion rule but says nothing about permissions, quota, or whether re-creating an existing report overwrites anything.

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 tight sentences, zero filler, with the core purpose and the critical source-selection rule front-loaded.

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 7-parameter, nested-object tool with no output schema, the description covers source selection but not the sorts/fields/format or expected return. It is adequate but leaves gaps given the tool's 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 coverage is already 86%, so the baseline is 3, but the description adds the one-of constraint across query/filter/filterId that the schema does not encode via anyOf/oneOf. That is meaningful semantics beyond the structured fields, though it leaves sorts/fields/format wholly to 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?

States a specific verb and resource ('Create a saved issue-list report') and ties it to its consumer context ('used by dashboard "issue list" widgets'), which separates it from the many queue/board/widget siblings. It does not explicitly contrast with find_issue_reports, 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 description gives one actionable usage rule—choose exactly one issue source among query | filter | filterId—which is real guidance, but it offers no when-to-use/when-not context versus alternatives like find_issue_reports or create_filter. It is also ambiguous about placement, saying the source goes 'inside parameters.filter' while query/filter/filterId are top-level schema properties.

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-vs-read profile is covered without the description. The description adds the admin-privilege requirement, which is genuine value beyond the annotations, but says nothing about idempotency, uniqueness constraints on the key, or what happens on collision.

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 zero filler. It is efficient, though the terseness borders on under-specification for a tool that takes a nested localized-name object and has admin semantics.

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 two-parameter tool with full schema coverage and no output schema, the description covers the essentials: what it creates and that it is admin-gated. It leaves gaps around key uniqueness, failure modes, and how the new type relates to existing ones, which an agent managing configuration would likely want.

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 100% and both properties carry inline documentation ('Type key, latin' and the localized-map example), so the baseline of 3 applies. The description adds nothing about the key format or the localization object shape beyond what the schema already states.

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?

Clear verb+resource ('Create a new issue type') with the '(admin)' qualifier signalling privilege scope. It does not, however, differentiate itself from the sibling update_issue_type or explain its relationship to get_issue_types, so it is clear but not sibling-aware.

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 usage signal is the parenthetical '(admin)', which hints at a permission requirement but not at when to prefer this tool over update_issue_type or how it fits the larger issue-type lifecycle. No when-to-use, when-not-to-use, or alternative is 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?

Annotations already declare this is a non-read-only, non-destructive mutation. The description adds the 'admin' permission signal, which is useful context beyond the annotations. It still says nothing about behavior on duplicate keys, whether the created entity is returned, or what the operation's effects are.

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 front-loaded and has zero padding, but it is under-specified rather than concise: a single four-word sentence for a tool with four required parameters including a nested i18n object omits essentials the agent needs.

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 creation tool with four required params, a nested localization object, an admin permission requirement, and no output schema, the description leaves out required input format expectations (notably the i18n map for 'name') and any confirmation of what is returned.

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 75%, with the schema documenting key ('latin'), name (i18n map), and order ('display weight'), while 'description' is left undocumented in both schema and description. The description adds no parameter meaning whatsoever, so the baseline 3 applies.

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 ('Create a priority'), so the agent knows this is a priority-creation tool distinct from update_priority and get_priorities. However, it does not explicitly name those siblings or explain what distinguishes creation from them 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?

The '(admin)' tag vaguely signals a privileged operation, but the description gives no when-to-use guidance, no prerequisites, and no alternative (e.g., update_priority for existing priorities). The agent must infer eligibility from the terse parenthetical.

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 and the description does not contradict it. However, the description adds nothing beyond that: not whether the name must be unique, what permissions are required, what defaults apply, or what is returned (no output schema exists).

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?

The single sentence is front-loaded and contains no filler, but its brevity comes from under-specification rather than disciplined editing. There is nothing to trim, yet nothing of substance was included.

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?

This is a seven-parameter mutation tool with no output schema, and the description says nothing about required vs optional fields, uniqueness constraints, or side effects. The only contextual information available comes from the schema and annotations, leaving the description inadequate for the tool's 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 100%, so all seven parameters (lead, name, tags, queues, startDate/endDate, description) are already documented in the schema. The description adds no syntax, format, or constraint information beyond that baseline, so a 3 is appropriate.

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?

"Create a project" names a clear verb and resource, but it is essentially a restatement of the tool name with no scope or distinguishing detail. With siblings like create_board, create_queue, create_dashboard and update_project/delete_project in the list, nothing here helps an agent tell this tool apart beyond the obvious noun.

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 exclusions, and no named alternative (e.g. update_project for existing projects, or get_projects for lookup). The agent must infer everything from the tool name 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?

Annotations declare readOnlyHint=false and destructiveHint=false, so the mutating-but-safe profile is already covered. The description adds that a specific required payload is needed, but omits side effects (e.g., does creating a queue also spawn a board or default workflow?), uniqueness constraints on key, and permission requirements.

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 tight sentences with the core action front-loaded and the required-field roster following; nothing is wasted. It is appropriately short, though it could have used the second sentence for routing rather than restating required fields.

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 six-required-parameter mutation with no output schema and only partial annotation coverage, the description is adequate but thin: it never says who can call it, what happens on key collision, or what side effects accompany queue creation.

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 100% and the nested issueTypesConfig has per-field descriptions, so the schema already carries parameter meaning. The description's phrase 'issueTypesConfig array binding issue types to workflow templates' is a useful summary but adds no syntax or constraint beyond what the schema states.

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 ('Create a new queue') and enumerates the required inputs, so the agent immediately knows what is produced. It does not, however, differentiate itself from the many sibling create_queue_* tools (autoaction, local_field, trigger, macro), which share the same noun.

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 prerequisites, and no mention of alternatives despite ~15 sibling tools whose names start with create_queue. The agent must infer placement from context 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?

Annotations (readOnlyHint=false, destructiveHint=false) cover only the safety profile. The description adds useful behavioral context: the action runs periodically and updates matching issues, plus the action-object types (Transition, Update, CreateComment, Webhook, CalculateFormula). It does not explain the scheduling mechanism (intervalMillis vs calendar) that drives the recurrence, which is central behavior.

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 front-loaded sentences with no filler; the core behavior and the action-object enumeration are efficient. The parenthetical list is dense but earns its place by documenting the otherwise opaque actions payload.

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 9-parameter creation tool with a nested actions array and no output schema, the description covers the essential mechanics (what it does and the action types) but omits required-parameter expectations, the filter/query XOR, and execution-timing params. Adequate but with clear gaps for correct invocation.

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 56% across 9 params. The description usefully clarifies the nested 'actions' param by listing the action variants, which the schema leaves as opaque 'Action objects', and echoes the filter/query selection. It does not address queueId, name, active, calendar, intervalMillis, or enableNotifications. Net, it partially compensates for the coverage gap and matches the ~3 baseline for middling coverage.

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 (Create) and resource (autoaction) and explains the core behavior: periodically updates issues matching filter/query. It also names the action-object variants. It stops short of distinguishing itself from the sibling create_queue_trigger, but the resource 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?

No guidance on when to create an autoaction versus a queue trigger (create_queue_trigger) or macro, even though these are close siblings. No prerequisites stated, such as needing an existing queueId. The agent must infer the selection criteria.

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 only declare readOnlyHint=false and destructiveHint=false; the description adds nothing beyond that. For a mutation tool with 11 parameters it does not disclose required permissions, behavior on duplicate field keys, or what defaults apply to the optional flags.

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 zero filler. It is not verbose, though it is arguably under-specified rather than efficient; the brevity is appropriate in form.

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 11 parameters, nested objects (name, optionsProvider), no output schema, and only 55% schema coverage, the description is far too thin to call the tool correctly. It leaves field-type encoding, localization format, and multi-value semantics unexplained.

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 55%, and the description contributes no parameter meaning at all - no explanation of id vs name, the localized name object, field type encoding, or how container/readonly/visible interact. For an 11-parameter tool this leaves several parameters undocumented in both places.

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 (Create) and resource (local/queue-specific issue field), and the parenthetical 'queue-specific' distinguishes it from global field creation like create_issue_field. It does not name the sibling directly, but the scope qualifier is enough for an agent to differentiate.

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 choose this over create_issue_field (global) or when to use update_queue_local_field instead. Prerequisites such as queue existence or permissions are unmentioned. The agent must infer usage entirely from the 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?

Annotations already declare this is a non-read-only, non-destructive write. The description adds one genuinely useful behavioral fact beyond that: the stored macro is not applied immediately, only 'on run', implying the stored definition has no side effect until invoked. It says nothing about permissions, whether body and issueUpdate can both be omitted, or validation failures.

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 that states the action first and the payload second, with no filler. It is efficient, though the brevity leaves behavior and usage unaddressed rather than being 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 four-parameter create tool with a nested issueUpdate object and no output schema, the description covers the payload concept but omits required inputs (queueId, name), whether at least one of body/issueUpdate is mandatory, and what identifying information is returned. It is minimally viable rather than complete.

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 50%: 'body' and 'issueUpdate' are documented in the schema, while 'name' and 'queueId' are not. The description's 'comment body and/or issue field updates' maps to those two documented parameters and the 'and/or' correctly signals at least one content field is expected, but it adds no syntax, format, or value guidance 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 gives a specific verb and resource ('Create a queue macro') and immediately defines what a macro is ('comment body and/or issue field updates applied on run'). It does not name or distinguish itself from the sibling update_queue_macro, but an agent can tell what object this creates.

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?

No when-to-use guidance, no prerequisites, and no routing to alternatives such as update_queue_macro for modifying an existing macro. The phrase 'applied on run' hints at the macro lifecycle but does not tell the agent when to choose create over update.

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 safety profile is covered. The description adds domain context about what actions and conditions can express (Transition/Update/Webhook/CalculateFormula, field/event checks), but says nothing about when the trigger fires, its side effects, or required permissions, so the added value is moderate.

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, purpose front-loaded, with the param detail following. Efficient, though the trailing ellipsis ('…') in the action list reads as an unfinished enumeration rather than a deliberate shorthand.

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 create tool with no output schema and minimal annotations, the description covers the two hard parameters but omits the required queueId/name semantics and any statement of trigger behavior or return. Adequate but with clear gaps.

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 40% and the schema types actions/conditions as opaque objects (additionalProperties: {}), so the description's enumeration of action types and the And/Or condition envelope genuinely helps for those two params. It still leaves queueId, name, and active unexplained, so it only partially compensates for the coverage gap.

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+resource ('Create a queue trigger'), which is enough to separate it from read/update/delete siblings (get_queue_trigger, update_queue_trigger, delete_queue_trigger). However it gives no hint of how it differs from the near-neighbor create_queue_autoaction, so the differentiation from that sibling is left to inference.

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 prerequisites (e.g., that the queue must exist), and no mention of alternatives such as create_queue_autoaction or update_queue_trigger. The text that follows the first sentence is parameter shape, not usage guidance.

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 declare readOnlyHint=false and destructiveHint=false, so the mutation/non-destructive profile is already covered. Beyond that the description adds nothing: no note on permission requirements, whether version names must be unique, what happens to dates, or what is returned. For a create operation this leaves real gaps.

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 zero padding. It is efficient, though the brevity edges toward under-specification rather than true conciseness.

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?

A 5-parameter mutation tool with no output schema and no annotation detail on side effects. The description does not say what creating a version affects, what the response contains, or how the optional dueDate/startDate interact, so an agent lacks context to call it confidently in edge cases.

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 100% and every parameter carries its own description, including the YYYY-MM-DD date format. The description adds no parameter meaning, so the baseline 3 for a fully documented schema applies.

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 ('Create a version in a queue'), which cleanly separates it from siblings like create_queue, create_queue_tag, or update_queue_version. It stops short of any scope or behavioral detail, but the action 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?

No when-to-use context, no prerequisites, and no named alternatives (e.g. get_queue_versions to check existing versions first, or update_queue_version for edits). The agent must infer the usage scenario entirely from the 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?

Annotations already declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive write. The description adds one piece of behavioral context beyond that: it is an admin-scoped operation, implying elevated permissions. It says nothing about idempotency, uniqueness of the key, or what happens on duplicate input, so it is adequate but thin.

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 the action front-loaded and zero filler, but it is arguably under-specified rather than concise. The '(admin)' fragment is efficient signalling, yet there is not enough content for a higher structure score.

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?

This is a mutation tool with no output schema and a nested localization object, yet the description does not say what is returned, whether the key must be unique, or how the created resolution is used. Given the complexity of the input and the absence of annotations covering these points, the description leaves meaningful gaps.

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 100%, with the key format ('Latin key starting with a lowercase letter') and the name localization object shape documented in the schema itself. The description adds no parameter meaning, so the baseline 3 applies.

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 ('Create a resolution'), which an agent can distinguish from get_resolutions and update_resolution by verb alone. The '(admin)' qualifier adds a scope hint. It does not, however, explain what a resolution is or how it relates to the sibling resolution tools, 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?

There is no when-to-use guidance and no mention of alternatives such as update_resolution or get_resolutions. The parenthetical '(admin)' is the only contextual cue, implying a permission prerequisite but not a usage condition.

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 mutation profile is covered. The description adds the 'sprints enabled' precondition, which is real behavioral context, but says nothing about required permissions, what happens to an existing active sprint, or failure modes for a create operation with four required fields.

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 sentence, front-loaded with the action, with the constraint tucked into a parenthetical. Nothing is wasted and nothing needs reordering.

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?

No output schema exists, and the description is silent on what is returned or how the new sprint is identified. For a create tool whose safety profile is carried by annotations, this is adequate but thin — the required-date semantics and the result of a successful creation are left entirely to the schema and inference.

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 75% with boardId, startDate and endDate documented in the schema; only 'name' is undocumented but self-evident. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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 on a board), which is immediately distinguishable from the get_/update_/start_/archive_/delete_sprint siblings by name and action. It stops short of explicitly contrasting itself with any sibling, but the action 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?

It provides one genuine precondition — the board must have sprints enabled — which tells the agent when this call will fail. However, it gives no guidance on how this relates to alternatives such as update_sprint or start_sprint, and no prerequisite about sprint board types beyond the single parenthetical.

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 agent knows this is a non-destructive write. The description adds the admin-permission requirement, which is genuinely beyond the annotations, but says nothing about key uniqueness, response shape, or what happens on conflict.

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 the verb and resource front-loaded and zero filler. Nothing redundant is present.

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 three-parameter creation tool with no output schema and fully documented parameters, the definition is barely adequate: it omits whether the created status is returned, whether keys must be unique, and any admin-permission consequences. The admin note helps but the behavioral picture is thin.

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 100%, so key format, the localized name object, and the type enum are all documented in the schema. The description contributes no additional parameter meaning, which is the expected baseline when the schema carries the load.

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 ("Create an issue status") and the parenthetical "admin" signals scope. It is clearly distinguishable from read/update siblings like get_statuses and update_status by the verb alone, though it never explicitly routes between them.

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 parenthetical "(admin)", which hints at a permission requirement but does not state when to use this versus update_status or get_statuses, nor any prerequisites or ordering constraints. No when-not-to-use or alternative is offered.

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 safety profile is covered. The description adds the admin-permission requirement and the queue-binding semantics, which is real added context. It does not describe what happens on conflict or whether the created entity can be re-created, so it is adequate but not rich.

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 compact clauses with no wasted words, and the core action plus the key queue caveat are front-loaded. It is efficient, though the parenthetical "(admin)" is slightly cryptic and the sentences truncate some detail.

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 7-parameter nested create tool with no output schema, the description covers the sharing nuance and issue-type attachment but leaves the required steps/initialAction structure entirely to the schema. Given the nested-object complexity, a bit more on what a valid workflow requires would round it out.

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 71%, so the schema carries most parameter meaning. The description adds value for two parameters — the omit-queue-to-share convention and that issueTypeResolutions is how issue types get attached — but says nothing about the required steps, initialAction, or type beyond what the schema states. Baseline 3 fits.

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 ("Create a workflow") and enumerates the substance it holds (statuses/steps plus transitions), so the agent knows this builds a workflow object rather than reading or editing one. It stops short of differentiating from siblings like update_workflow or get_workflow, which is what a 5 would require.

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 gives one conditional usage rule — "Omit 'queue' to create a common workflow available to all queues" — which is genuinely useful branching guidance. However, it never says when to reach for create_workflow versus update_workflow, nor outlines prerequisites beyond the parenthetical "(admin)".

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 readOnlyHint=false, so the destructive nature is structured data, not a description contribution. Critically, the description omits that a separate confirm flag must be set to proceed, which is the single behavioral fact an agent actually needs here.

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?

The single sentence is front-loaded and waste-free, which is good, but its brevity comes at the cost of under-specification rather than genuine conciseness. One sentence is appropriate in size but does too little work.

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 destructive mutation with an undocumented required confirmation step and no output schema, the description is too thin. An agent could call it without knowing that confirm=true is needed to complete the delete.

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 50%: the confirm parameter is documented in the schema but boardId is not. The phrase 'by id' loosely identifies boardId as the key, adding marginal value, but does not specify type or format to compensate for the coverage gap.

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 (Delete) and resource (board) plus the lookup key (by id), so the action is unambiguous. However, it offers no differentiation from siblings like delete_board_column, delete_queue, or delete_entity, leaving the agent to rely on the name alone.

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 gives no when-to-use or when-not-to-use guidance, no prerequisites, and no mention of alternatives such as archive_sprint or update_board. Usage must be inferred entirely 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds the useful concurrency detail that the version argument must equal the board version, but says nothing about irreversibility, what happens to cards/issues in the column, or the role of the confirm 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?

A single short sentence with the verb and resource front-loaded and no filler. The version parenthetical is slightly cryptic but does not waste space.

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 destructive, non-reversible operation with no output schema and a confirm parameter, the description omits what the confirm flag does, what is lost when the column is deleted, and any permission requirements. Too thin for the risk level of the 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 coverage is 50%; 'version' already carries 'Current board version' in the schema, so the parenthetical is close to a restatement rather than new meaning. boardId and columnId are undocumented but self-explanatory by name, so the baseline 3 for a partially documented schema is appropriate.

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 ('Delete a board column'), which cleanly separates it from siblings like update_board_column, get_board_column, and delete_board. It does not explicitly contrast with those siblings, but the verb+resource pair 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?

No guidance on when to use this versus alternatives, and no statement of prerequisites or consequences. The parenthetical about version is a parameter note rather than usage guidance, leaving the agent to infer everything about context.

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 readOnlyHint=false, so safety is covered structurally. The description adds scope value by clarifying that the entire checklist (not a single item) is removed, but says nothing about irreversibility, permissions, or whether the confirm flag is mandatory.

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. Every word carries weight.

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 low-complexity destructive tool with no output schema and full schema coverage, the description is nearly sufficient; annotations cover the safety profile and the schema covers the confirm gate. Only the missing pointer to item-level alternatives keeps it from a 5.

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 100%, so both issueId and confirm are already documented in the schema, including the confirmation requirement for the destructive/bulk operation. The description adds no parameter detail beyond that, so baseline 3 applies.

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 (Delete) and resource (the whole checklist of an issue). The word 'whole' distinguishes it from item-level siblings like delete_checklist_item and delete_entity_checklist_item, 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?

No when-to-use guidance, no when-not-to-use exclusions, and no mention of alternatives such as the item-level deletion tools. The agent must infer scope selection on its own.

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 readOnlyHint=false, so the agent knows this is a destructive write, and the description is consistent with that. It adds nothing beyond the annotations, though, notably omitting that the schema requires a confirm flag for this destructive operation. With annotations carrying the safety profile, 3 is appropriate.

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 clean, front-loaded sentence with no wasted words. It is efficiently sized for a simple delete, though it errs toward under-specification rather than over-verbosity.

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 destructive tool with full schema coverage and no output schema, the minimal prose is largely adequate, but the description never surfaces that a confirmation flag is mandatory for this irreversible operation, leaving the agent dependent on reading structured fields.

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 100%, so all three parameters (issueId, itemId, confirm) are documented in the schema itself. The description only loosely implies issueId ('from an issue') and says nothing about the confirm parameter, so baseline 3 applies.

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 (Delete) and resource (checklist item) with scope ('from an issue'), so the purpose is unambiguous. However, it does not distinguish itself from close siblings like delete_entity_checklist_item, delete_checklist, or delete_entity_checklist, so it falls 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?

The description gives no when-to-use guidance, no prerequisites, and names no alternatives. An agent is left to infer that the item must already exist and that get_checklist is a likely prerequisite (which is only hinted at in the schema, not the description).

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 readOnlyHint=false, so the safety profile is covered structurally. The description adds nothing beyond that: it doesn't say the deletion is irreversible, whether a confirm flag is mandatory, or what happens to comment reactions/replies attached to the comment.

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 zero filler, appropriate for a simple delete. It is efficient, though its brevity contributes to the usage and behavioral gaps noted elsewhere.

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 destructive tool with no output schema, annotations cover the safety signal and the schema covers all parameters, so nothing is strictly missing. Still, the description could have disclosed the confirm requirement and irreversibility to make the destructive nature actionable.

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 100%, so issueId, commentId, and the confirm flag are all documented in the schema. The description adds no parameter meaning, which is the expected baseline when the schema does the heavy lifting.

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 ('Delete a comment from an issue'), which is unambiguous. It edges out the similarly named delete_entity_comment by scoping to issues, but it never names that sibling explicitly, so 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?

No guidance on when to use this versus edit_comment, delete_entity_comment, or update_entity_comment, and no mention of the required confirm flag or any prerequisite. The agent must infer usage entirely from the 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?

Annotations already flag this as destructive (destructiveHint=true, readOnlyHint=false), so the safety profile is partly covered. However, the description adds nothing beyond that: it never says the deletion is irreversible, what happens to issues referencing the component, or that the `confirm` flag is required to proceed.

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 wasted words. It is efficient, though for a destructive operation the terseness shades into under-specification rather than optimal brevity.

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 destructive mutation with no output schema and an undocumented `confirm` parameter, the description should warn about irreversibility and describe the confirmation requirement. As written it leaves the agent without the information needed to invoke the tool 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 coverage is 50% – `confirm` is documented in the schema while `componentId` is not. The description's 'by id' loosely maps to componentId, but it does not explain the id type or the role of `confirm`, so it adds only marginal value over 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 (delete) and resource (component) and clarifies the identifier mechanism ('by id'), which lets an agent distinguish it from get_component, update_component and create_component. It offers no further scoping, but the verb+resource pairing 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?

There is no when-to-use guidance, no mention of alternatives such as update_component, and no stated prerequisites or cautions. An agent must infer everything about when deletion is the right call.

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=true, so the agent knows this is a destructive write. The description adds the entity types affected (project/portfolio/goal) but says nothing about reversibility or cascade effects. With annotations carrying the safety profile, this is adequate but thin.

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 efficient sentence with no filler, front-loading the verb and the affected resources. It is arguably too terse, but nothing 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?

For a destructive 3-param tool with no output schema, the schema covers the parameters and annotations cover safety, so the core is present. However, the cascading/write behavior of deletion and the confirm-gating workflow are not explained, leaving the definition minimally complete.

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 100%, with the enum and the confirm flag fully documented in the schema itself. The description only echoes 'by id' and the entity types, adding no format or constraint detail beyond the schema. Baseline 3 is appropriate.

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 (Delete) and the resource (project, portfolio or goal) plus the keying mechanism ('by id'). It is clear what the tool does, but it does not distinguish itself from overlapping siblings like delete_project, leaving ambiguity about when this generic tool applies.

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 prefer this over delete_project or other entity-specific deleters, and no mention of prerequisites such as the confirm flag being needed before success. Usage context is entirely left to inference.

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 readOnlyHint=false, so the safety profile is covered. The description confirms the delete is scoped to three entity types but omits whether deletion is irreversible, whether the solution's confirm flag is required in practice, and what permission is needed.

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 tight sentence with the action and scope front-loaded and no filler. It is arguably too terse given the destructive nature, but nothing in it 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?

For a destructive, 4-parameter mutation with no output schema, the description should at minimum flag irreversibility or the confirm expectation. It covers only the entity scope, leaving confirmation behavior, permissions, and post-delete state unaddressed.

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 50%: entityType and confirm are documented in the schema, while entityId and attachmentId are bare. The description only restates the three entity types already enumerated in the schema, adding no new meaning such as ID formats or where attachmentId comes from.

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 (Delete) and resource (file/attachment) plus the scope of entity types it applies to (project, portfolio, goal). An agent can distinguish it from delete_issue_attachment by the entity scope, though the description never names that sibling 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?

There is no guidance on when to use this versus delete_issue_attachment, list_entity_attachments, or download_entity_attachment, and no mention of prerequisites such as ownership or the confirm flag. The reader must infer usage entirely from the 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?

Annotations already declare destructiveHint=true, so the safety profile is covered. The description adds only the scope (all items, project/portfolio), and omits useful behavioral context such as whether the operations are irreversible, why 'confirm' is required, or what 'notify' triggers.

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 zero filler, which is appropriately tight for a scoped delete. It is arguably too terse given the destructive bulk nature, but it wastes no words.

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 destructive bulk operation with no output schema and only 50% schema coverage, the description should explain the confirm-gate, reversibility, and notify semantics. None of that is present, leaving the agent to infer the consequences of an irreversible bulk delete.

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 50%; 'confirm' and 'entityType' are documented in the schema, but 'notify' and 'entityId' have no descriptions anywhere. The description adds no parameter meaning beyond restating the project/portfolio scope already present in the entityType enum description.

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 (delete) plus resource and scope (all checklist items on a project/portfolio), which distinguishes it from the item-level siblings delete_entity_checklist_item and delete_checklist_item. However, it never names those alternatives explicitly, so differentiation relies on the agent inferring 'all' means bulk entity-level.

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 word 'all' implies this is the bulk variant versus the single-item deletion siblings, giving implied usage context. There is no explicit when-to-use/when-not statement, no mention of prerequisites, and no routing to alternatives for single-item deletion.

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 readOnlyHint=false, so the safety profile is covered. The description adds only the project/portfolio scoping; it says nothing about the confirmation requirement, the notify behavior, or irreversibility beyond what the annotation implies.

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 wasted words. It is efficient, though its brevity contributes to the gaps noted in other dimensions rather than being an independent virtue.

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?

A destructive, confirmation-gated tool with five parameters and no output schema needs more than one sentence. The description omits the confirm requirement, the notify behavior, and any return/error information, leaving the agent to infer invocation behavior entirely from the 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 description coverage is only 40% (confirm and entityType are documented in-schema; itemId, entityId, notify are not). With low coverage the description should compensate, but it adds no semantics for any of the five parameters, including the notify flag.

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 (Delete), resource (checklist item), and scope (of a project/portfolio), which distinguishes it from the issue-level delete_checklist_item sibling. It is clear but does not explicitly name the alternative tool an agent might confuse it with.

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?

No when-to-use guidance, no prerequisites, and no conditions under which this tool should be chosen over delete_entity_checklist, update_entity_checklist_item, or delete_checklist_item. The entity-type hint is the only routing signal.

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 annotations already declare readOnlyHint=false and destructiveHint=true, so 'Delete' adds nothing about safety. The description does not mention that a confirm flag is required to proceed, whether deletion is permanent/recoverable, or how the notify/notifyAuthor flags behave, which are the meaningful behavioral gaps for a destructive op.

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 efficient sentence with no wasted words, and the primary action is front-loaded. It is concise, though thin rather than optimally informative.

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 destructive mutation with no output schema and only 33% parameter coverage, the description is too sparse. It omits the confirmation requirement and the notification flags that materially affect how the tool is called, leaving the agent under-informed.

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 33% (only confirm and entityType are documented), yet the description adds no parameter detail at all. It restates the entity types but says nothing about entityId, commentId, notify, or notifyAuthor, so a third of the params remain undocumented in both places.

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 ('Delete') and resource ('a comment') plus the scope of entities it applies to (project, portfolio, goal), which is useful. It does not, however, say how it differs from the sibling delete_comment, leaving the agent to infer the distinction.

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 about when to use this tool versus delete_comment or update_entity_comment, and no prerequisites or conditions are stated. The agent must infer applicability from the entity-type scope alone.

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