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

With no annotations the description carries the full burden and does so: PUT deletes every step missing from the payload, steps are reordered by the authoritative `index` before merging, a 2xx write can silently store nothing, and the read-back result can report a mismatch or null totalSteps. These are exactly the non-obvious traits an agent cannot infer elsewhere.

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 core action is front-loaded in the first clause, and the length is largely justified by the API quirks it must warn about. It is, however, a dense wall of em-dash-separated clauses rather than clearly separated points, which slightly hurts scanability.

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, yet the description fully documents the return shape ({ key, totalSteps }, plus stepsSent and a warning on mismatch, or null totalSteps on read-back failure). Combined with the usage constraints and mutation semantics, nothing an agent needs to call it correctly 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 100%, so the baseline is 3, but the description goes further by explaining that `position` indexes into the authoritative ordered sequence, is clamped to the step count, and that the `steps` array carries no ids because ids belong to stored steps. It adds real meaning over the schema's field-level text.

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 (insert steps), the exact resource (a STEP_BY_STEP script) and the mechanism (GET then PUT /testcase/{testCaseKey}), and explicitly contrasts itself with set_test_script for the replace case. An agent can distinguish it from set_test_script 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?

Explicit when-to-use conditions are given: allowed when the script is STEP_BY_STEP or when the case has no script content (including the empty PLAIN_TEXT stub), and refused for a PLAIN_TEXT/BDD script that really has text, with the alternative named. The self-referencing 'Call to Test' exclusion is also 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?

With no annotations provided, the description carries the full burden and delivers: what is copied vs. explicitly NOT copied (issue links, attachments, execution history), the folder-must-exist precondition, the 255-character failure mode and its local pre-check, the 400 on empty name, and non-deduplication semantics. This is exactly the destructive/mutation context an agent needs absent annotation hints.

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?

Purpose is front-loaded and the copy/no-copy inventory is efficient, but the name-limit passage runs long with multiple parentheticals covering astral-character boundaries, repeated '(copy)' markers, and the note field. The information is genuinely useful for edge cases, yet it is denser than a reader needs on first pass.

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 description compensates by stating the return shape: '{ key, url, sourceKey, note? }'. Combined with the copy semantics and failure modes, an agent has everything needed to invoke and interpret the result.

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 the baseline is 3, but the description adds substantial meaning beyond the schema: includeScript=false yields a copy with no steps plus a spurious empty PLAIN_TEXT testScript, name defaulting and shortening behavior, the step-id-dropping rule, and the empty-string edge case. This goes well past restating field definitions.

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?

Opening clause gives a precise verb+resource+scope: 'Copy a test case inside its own project,' immediately distinguishing it from create_test_case (new case) and get_test_case (read). The description also enumerates exactly which fields travel with the copy, so an agent knows what the resulting artifact is.

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?

Prerequisites and alternatives are explicit where it matters: 'The folder MUST already exist — the API never creates folders implicitly (use create_folder first)' names the sibling to call first. It also states the when-not implicitly via 'inside its own project,' but never spells out a cross-project alternative, so it stops short of full alternative routing.

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

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

With no annotations, the description carries the full burden and does well: it discloses the duplicate-name error (400), the case-sensitive nature of the name, and that the return is the raw created object. It omits auth requirements and idempotency, but core behavior is covered.

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 tightly written sentences, front-loaded with the core action, then key constraints, then return value. Every sentence adds necessary information without redundancy.

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

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

Given the simple create operation, full schema description coverage, and lack of an output schema, the description provides all essential context: what it does, a critical error case, case-sensitivity, and what it returns. 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 100%, so baseline is 3, but the description adds meaningful context beyond the schema: it explains why the name must be unique (rejected with 400) and that its exact casing matters because other tools reference it. This enriches the name parameter's semantics.

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 (Zephyr Scale environment) with scope (in a project) and even the API endpoint. It clearly distinguishes itself from the sibling list_environments by action, but does not explicitly name an alternative 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?

Provides implicit guidance: it explains the uniqueness constraint and the need to match casing for downstream use, but does not state when to use this tool versus alternatives or mention any prerequisites beyond the schema.

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?

No annotations are supplied, so the description carries the full burden and does so: it explains pre-flight validation, exact failure modes (400/403/409/5xx), non-idempotency with the specific error text, the recursive fallback semantics and the build where it is a no-op, and that 403 is never mistaken for a missing parent.

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?

Front-loaded with the core action and endpoint, and every sentence carries real information. It is a single dense paragraph with some overlap against the schema's own name rules, and could be broken into bullets for scanability, 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?

With no output schema, the description still explains the return value { id, name, type } and the critical caveat that id is only the last segment, directing the agent to get_folder_tree for ancestor ids. Nothing needed to call it correctly 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 100%, so the baseline is 3, but the description adds meaning beyond the schema: it clarifies that recursive is client-side only and effectively a no-op on the reference build, and explains that the two path rules surface through different layers (schema vs. tool).

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 with the underlying endpoint: 'Create a folder for test cases, test plans or test runs / test cycles (POST /folder)'. It also explicitly distinguishes itself from siblings, noting create_test_case/create_test_run/create_test_plan never create folders implicitly and fail with 400 on an unknown folder.

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 explicit when-to-use context and alternatives: which sibling tools do not create folders, that each folder type has its own tree so a path must be created once per type, that the call is not idempotent, and that the returned id is required by rename_folder/delete_folder.

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

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

With no annotations, the description carries the full burden and does so richly: it discloses the 400 on unknown/wrong-case values, the 255-char name limit enforced locally because the API returns a bodyless 500, BDD text stored verbatim, and the side effect that omitting testScript attaches an empty PLAIN_TEXT script. It even states the return shape { key, url }.

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?

Front-loaded with the verb+resource, then organized around prerequisites, value validation, and script semantics. It is dense and long, but nearly every sentence carries actionable constraint information, so little 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 15-parameter tool with nested objects, no output schema, and no annotations, the description covers prerequisites, validation failures, side effects, and the return value. Nothing an agent needs to invoke it correctly appears to be 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 100%, so the baseline is 3, but the description adds meaning beyond the schema: the 255-char name limit (schema only sets minLength 1), the folder-must-exist rule, owner user-key semantics, and estimatedTime units. It enriches the schema rather than merely restating it.

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?

Opens with a specific verb+resource ('Create a test case') and even names the underlying endpoint (POST /testcase). It is clearly distinguishable from siblings like create_test_cases_bulk, clone_test_case, and add_test_steps, the last of which it explicitly references.

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 strong operational context: folder must pre-exist ('use create_folder first'), owner must be resolved with find_jira_user, and it explains the consequence of omitting testScript. However it never explicitly contrasts when to reach for this tool versus create_test_cases_bulk or clone_test_case.

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 are empty, so the description carries the full burden and does so: it discloses the broken-bulk-endpoint fallback, that 4xx is not retried, the two distinct return shapes, that failed[] is omitted on full success, that created[] lacks indices, that an all-fail call raises with per-item lines, and the 255-char local rejection. This is exactly the behavioral detail an agent needs.

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 long but front-loaded with purpose and folder prerequisite before the failure/return semantics. Nearly every sentence carries operational weight (fallback behavior, return shape, failure mode), though the return-shape discussion is dense and could be tightened without loss.

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 annotations and no output schema, the description fully compensates by documenting both return shapes and the failure contract. Combined with 100% schema coverage on the input side, an agent has everything needed to call this correctly and interpret the result.

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 the schema already documents both parameters and the nested item shape. The description still adds value beyond the schema: the cross-reference that each item takes the same fields as create_test_case, the projectKey resolution chain order, and the 255-character name limit that is not expressed 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 (create), resource (test cases), and scope (several in one request, POST /testcase/bulk), which distinguishes it from the sibling create_test_case. It also names the shared field semantics and the fallback path, so an agent can tell what the tool actually does end-to-end.

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 concrete prerequisite ('use create_folder first' because folders are never created implicitly) and explains the build-specific fallback path, which is useful routing context. It does not explicitly contrast against single create_test_case or state when bulk is preferable beyond the implied 'several items', so it stops short of full when/when-not 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?

With empty annotations the description carries the full burden, and it delivers: it discloses the return shape { key } and why no UI url is given, the fact that the API never creates folders implicitly, and non-obvious error behavior (case-sensitive status, 400 when a case status is supplied, get_status_options unable to list plan statuses). This is well beyond what structured fields provide.

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 purpose is front-loaded, but the body is dense with em-dashes and parentheticals, and it duplicates schema descriptions for owner, folder, and status almost word-for-word. That redundancy works against conciseness even though the information itself is 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?

There is no output schema, and the description compensates by documenting the return value ({ key }). For a 9-parameter tool with nested customFields it covers prerequisites and key quirks but says nothing about auth/permission needs, leaving a small gap.

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 nine parameters, and the description's owner/folder/status text is largely repeated verbatim from the schema. It adds only marginal semantic value (status option-set quirk) beyond what the schema already provides, matching the baseline 3.

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 test plan') and even names the endpoint (POST /testplan), which cleanly separates it from create_test_case, create_test_run, and create_folder in the sibling list. An agent can identify the operation without inspecting the 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?

It gives explicit prerequisites and routes the agent to other tools: the folder must already exist and be created with create_folder (type TEST_PLAN), and owner must be resolved with find_jira_user. It does not state when *not* to use this tool versus update_test_plan, so it stops short of a full 5, but the preconditions are clear.

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

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

No annotations exist, so the description carries the full burden — and it does: version-specific auto-add behavior, silent discard of out-of-range scriptResults indices, status never being derived from step statuses, 400/404 and empty-bodied 500 responses, and the warning that a 500 may still have written the execution and duplicated an item. These are exactly the failure modes an agent must know before retrying.

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?

Front-loaded correctly — what it does, the sibling alternative, then hazards. But it runs to roughly 400 words with hedged speculation and low-value specifics ('it landed second of three and second of four', 'its cause is undetermined') that a caller cannot act on; a tighter version would preserve the actionable warnings and drop the field-report narrative.

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 17-parameter mutation tool with nested scriptResults, no annotations and no output schema, the description closes every gap: it documents the return value ({ id }), the selector-vs-body distinction, and the recovery path (re-read with get_test_run_results rather than retry). Nothing an agent needs to call it safely 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 description coverage is already 100%, so the baseline is 3. The description still adds real meaning beyond the schema: the status/scriptResults coupling rule, the fact that omitted fields keep project defaults, that selectors only select and never set (so `environment` must be passed separately if the result should carry it), and that matchUserKey targets executedBy, not assignedTo.

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 ('Record a NEW execution of a run item') and even names the endpoint, then immediately distinguishes itself from update_last_test_result, the sibling it is most likely to be confused with. An agent can route correctly without opening the 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?

Explicit when-to-use vs. when-not: 'to amend the newest execution instead, use update_last_test_result', plus conditional guidance to pass matchEnvironment/matchUserKey whenever a case appears more than once, and to pass `status` in the same call as scriptResults. Alternatives and preconditions are named, not implied.

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

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

With no annotations, the description carries the full burden and does so exceptionally: it discloses non-atomic skip-and-commit semantics with concrete id-level evidence, version-specific behavior for non-member test cases, silent discarding of out-of-range scriptResults indices, status defaulting, batch-wide matchEnvironment/matchUserKey scoping, and no-upsert duplicate semantics. These are exactly the behaviors an agent cannot infer from 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?

It is long, but the length is largely earned by the tool's genuine complexity and it is front-loaded with purpose before behavior. The repeated 'verified live' parentheticals with example id arrays add evidence but are verbose, and a few clauses could be tightened without losing meaning.

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, yet the description explicitly states the return shape ([{ id }, …]) and its positional alignment with the request. Combined with the mutation hazards, failure modes, and version caveats it covers, an agent has everything needed to call this safely and 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 the baseline is 3, but the description adds real meaning beyond it: the returned ids are positionally aligned with the input array, only the fields passed per entry are sent, and matchEnvironment/matchUserKey select the run item for the whole batch rather than setting the created result's environment. The status/scriptResults interplay is also a semantic clarification the schema does not express.

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 opening sentence states a specific verb (Record), resource (NEW executions for several items of ONE test run), and the endpoint (POST /testrun/{runKey}/testresults). It is immediately distinguishable from the singular create_test_result and from update_last_test_result. An agent knows exactly what class of operation this is.

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 strong operational routing: re-read with get_test_run_results instead of sending a second update_last_test_result, and re-read before resending after a partial failure. It does not explicitly contrast itself with create_test_result for single executions, so the selection boundary versus that sibling is left implicit, but recovery and read-back alternatives are named precisely.

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

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

With no annotations, the description carries the full burden and does so richly: immutability, absence of PUT /testrun, items fixed at creation, status derived server-side from item statuses, the distinct status vocabularies, folder non-creation, and local rejection of issueLinks (HTTP 500). These are exactly the behavioral traits an agent needs before invoking a mutation.

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

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

It is dense and long, but front-loaded with the core action and the immutability constraint, and virtually every sentence encodes a real constraint (escape hatches, folder prerequisite, issueLinks rejection, return value). Slightly run-on in places, but nothing is 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 a 12-parameter mutation tool with no output schema and no annotations, the description covers the composition rule, prerequisites, escape hatches, result-import path, and even the return shape ({ key }). An agent has everything needed to call 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 description coverage is 100%, so the baseline is 3; the description still adds meaning beyond the schema by stressing that items is the ONLY place a run's composition can be set and must be complete, and that each item may carry execution-result fields to import results in one call. The name parameter's immutability is also reinforced.

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

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

The description opens with a specific verb+resource ('Create a test run / test cycle') and even names the HTTP endpoint, making it instantly distinguishable from siblings like recreate_test_run_with_items, search_test_runs, and get_test_run.

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 explicitly states when to use this tool (pass the COMPLETE items list now, since the run is immutable) and routes the agent to concrete alternatives: recreate_test_run_with_items, and the internal-API tools update_test_run / add_test_cases_to_run / remove_test_cases_from_run with their precondition (ZEPHYR_ALLOW_INTERNAL_API=true). It also flags prerequisites (folder must exist, use create_folder first) and forbids linking issues on a run, redirecting to test cases.

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 destructiveHint=true, yet the description goes far beyond: irreversibility, no bulk form, the fact that DELETE returns 2xx for nonexistent ids, the GET pre-check that 404s for missing ids, the side effect of downloading the full attachment content before deletion, and the exact response shape including the existenceVerified:false caveat. This is unusually rich disclosure of non-obvious 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?

Front-loaded with the core action and irreversibility, then progressively less critical caveats. It is long and dense, but each sentence carries distinct behavioral information rather than filler; the trailing return-shape sentence is the only part that could be trimmed.

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

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

No output schema exists, and the description compensates fully by describing the return object and the edge case where existenceVerified is false. For a destructive single-parameter tool, an agent has everything needed to call it and interpret the result.

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 schema already documents attachmentId, so the baseline is 3. The description adds real meaning beyond the schema: that ids are global rather than per-entity, that they come from list_attachments/upload_attachment responses, and that the pre-check makes the id's validity consequential.

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 ('Permanently delete one attachment'), the underlying endpoint (DELETE /attachments/{id}), and the scope constraint (one call per attachment, no bulk form). An agent can distinguish it from list_attachments/upload_attachment and from bulk siblings immediately.

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?

Explains where valid ids originate (list_attachments or upload_attachment response) and that the parent entity is not needed because ids are global. It stops short of naming a sibling tool as the alternative to use in a specific situation, but the operational context for when this tool applies is clear.

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

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

Goes far beyond the single destructiveHint=true annotation: it discloses irreversibility, the exact scope of loss (case, script, execution history), the absence of inbound-reference checking, and the concrete consequence of orphaned 'Call to Test' steps. This is exactly the pre-call warning an agent needs before a destructive operation.

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 dense sentences, each earning its place: the action+endpoint, the irreversibility and blast radius, the referential-integrity caveat, and the return shape. The destructive warning is front-loaded rather than 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 one-parameter destructive tool with no output schema, the description supplies everything missing from structured fields: destruction scope, referential side effects, and the return shape ({ deleted: true, key }). An agent can call this correctly and warn the user with no further information.

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 single parameter already documents its format ('PROJ-T123'), so the description adds no syntax or format detail beyond the schema. Baseline 3 is appropriate when the schema carries the parameter semantics.

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 ('Permanently delete a test case') and anchors it to the concrete endpoint DELETE /testcase/{testCaseKey}. It is trivially distinguishable from siblings get_test_case, update_test_case, and clone_test_case without opening any 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?

Usage is implied by the verb and the explicit irreversibility warning, which tells the agent this is the last-resort path rather than a routine edit. However, it never names alternatives (e.g., update_test_case or move_test_cases_to_folder) or states when deletion is appropriate versus when it should be avoided.

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 give destructiveHint=true; the description goes far beyond, disclosing irreversibility (no trash/undo), non-idempotency, the 404 failure behavior for unknown keys, that the key is not reused, and the verified non-cascading behavior toward linked runs.

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?

Front-loaded with the core action and mostly dense with high-value facts, though it is on the long side with some redundancy around the 404/not-confirming point. Nearly 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?

Covers the return value ({ deleted: true, key }) despite no output schema, and fully describes failure modes, side effects, and sibling routing. Nothing an agent needs to call this destructive tool correctly 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?

Single parameter with 100% schema coverage documenting the key format (e.g. PROJ-P123). The description adds behavioral nuance about mistyped keys 404-ing but no additional syntax 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 and resource ('Permanently delete a test plan') plus the exact endpoint DELETE /testplan/{testPlanKey}, and clearly differentiates from siblings like delete_test_run and delete_test_case by contrast.

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?

Explicitly routes the agent: if the intent was the linked runs, use delete_test_run instead, and states the plan does not cascade to runs. Also gives the when-not condition (unknown/mistyped/already-deleted key fails with 404 rather than confirming).

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 carry destructiveHint=true; the description adds the irreversibility, the immutability of test runs (no PUT /testrun), the surprising 2xx-on-nonexistent-key DELETE semantics, and the GET pre-check that gates deletion. It even discloses the response shape and the caveat that success does not prove prior existence when the pre-check fails.

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?

Long but dense and front-loaded: destruction scope and irreversibility come first, then the immutability constraint, then escape hatches, then the verification caveat. Almost every sentence carries non-redundant operational detail, though the immutability/escape-hatch passage could be tightened.

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 compensates by documenting the return object and the existenceVerified:false edge case. Combined with the verification behavior, key format, and alternative routes, an agent has everything needed to call this correctly and interpret the result.

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 single parameter already documents the key format with examples, so the schema does the heavy lifting. The description adds only the endpoint path reference (DELETE /testrun/{key}), which is context rather than parameter meaning. 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 precise verb+resource ('Permanently delete a test run / test cycle') and immediately enumerates the full blast radius (execution results, attachments, test-plan links), plus the underlying endpoint. An agent can distinguish it from delete_test_case, delete_test_plan and recreate_test_run_with_items without opening a 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?

Explicitly names the alternatives (recreate_test_run_with_items, update_test_run, add_test_cases_to_run, remove_test_cases_from_run) and the conditions that select them, including the ZEPHYR_ALLOW_INTERNAL_API=true prerequisite. It also prescribes the intended public workflow ('delete + create_test_run with the full desired items') for the task the agent will actually want.

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

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

Goes far beyond the single readOnlyHint annotation: it discloses that outputPath is written on the MCP host, that the parent directory must pre-exist, that a failed download writes nothing, that credentials are never sent to another host, that query strings are moved out of the path so they never leak into errors, and that HTML responses are refused unless allowHtml is set. This is exactly the kind of side-effect and safety context annotations cannot carry.

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?

Long, but almost every sentence carries security or safety information not available elsewhere, and the core purpose is front-loaded in the first clause. Slightly dense, though nothing is padding.

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 still explains the return value ({ savedTo, bytes }) and the guarantee it carries, plus the HTML-refusal behavior and error-message shape. An agent has everything needed to call it correctly and interpret the result.

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 the baseline is 3, but the description adds real meaning beyond the schema: the mutual exclusivity of url/attachmentId, the constraint that url must be on the configured Jira host, the exact semantics of allowHtml as disabling the page guard, and the parent-directory requirement for outputPath.

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 ("Download the content of an attachment to a local file") and even names the REST endpoint. An agent can immediately distinguish it from list_attachments, upload_attachment, and delete_attachment among the siblings.

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

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

Gives clear usage context: address the attachment by attachmentId or by the exact url list_attachments returns, and pass exactly one of the two. It also routes the agent to list_attachments as the source of a valid url and explains when to set allowHtml. It does not explicitly name alternative download strategies, but the selection guidance is clear.

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

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

Annotations only supply readOnlyHint=true, yet the description reconciles it ("Reads from Zephyr only, so it stays available in ZEPHYR_READONLY mode") and adds rich behavior: silent dropping of non-BDD/nonexistent keys, HTTP 200 with an empty body on no match, 'PK' signature verification, overwrite-without-warning of an existing outputPath, and that a failed call leaves it byte-identical. This is well beyond what the annotation conveys.

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?

Purpose is front-loaded and every sentence carries a concrete, non-redundant fact (dialect limits, silent skips, overwrite behavior). It is dense to the point of being a wall of text, so it is not maximally scannable, but nothing reads as 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?

With no output schema, the description still discloses the return value ("Returns { savedTo, bytes }"), which is exactly the gap it needs to close. Combined with the edge-case behavior and file-format caveats, an agent has everything required 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 the baseline is 3, but the description adds operational meaning beyond the schema: quote requirements, disallowed lowercase/or forms, the exact per-field dialect restrictions, and that '~' is not expanded and the parent directory must pre-exist. It notably omits the same detail it advertises for tql from the schema text on outputPath syntax.

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 ("Export BDD test cases as Gherkin .feature files packed in a ZIP archive") and cites the underlying endpoint GET /automation/testcases. It is clearly distinguishable from siblings like set_test_script, download_attachment and search_test_cases.

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 strong context on when the call is viable: tql is REQUIRED, only the testCase.-prefixed dialect works, only BDD-script cases are exported, and it explicitly recommends testCase.key IN (...) since folder/status/priority filters are rejected. It never routes to an alternative for the main purpose (e.g. search_test_cases to discover keys), so it stops short of a full when/when-not map.

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 carry readOnlyHint=true, and the description goes well beyond that: it discloses the required "Browse users" permission and the 403 failure mode, the exact return shape, the empty-array behavior, and the conditionally absent emailAddress field. This is genuinely useful operational context an agent could not infer.

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 dense sentences with the endpoint and purpose front-loaded, followed by prerequisites and return shape. No filler; every clause carries information.

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-param read tool with no output schema, the description covers purpose, permission prerequisites, and return values well enough to call it correctly. The only real gap is the absence of routing against the duplicate jira_search_users sibling.

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 parameters (query substring semantics, maxResults default of 50) are fully documented in the schema itself. The description adds no parameter-level detail, 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+resource ("Search Jira users") and even names the underlying endpoint, which is more than most definitions offer. However, it never acknowledges the near-identical sibling jira_search_users, so an agent still cannot tell the two apart from the text 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?

Explicitly states the use case: resolve the Jira USER KEY required by owner/executedBy/assignedTo, and warns those fields reject usernames and e-mails. That is strong when-to-use context, but it names no alternative (jira_search_users, jira_get_user, jira_get_current_user, jira_search_assignable) so there is no when-not 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?

With only readOnlyHint available, the description carries the behavioral burden and does so exceptionally: it discloses request cost (up to 2 per case), the dedup-before-cap ordering, unstable API ordering, lastResult null semantics ('never executed or run deleted', not 'untested'), the most-recently-CREATED selection rule that can surface older dates, fault-tolerant partial rows, 404 on unknown keys, and case-insensitive key resolution. This is far beyond what the annotation provides.

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?

Every sentence carries substantive information and the purpose plus cost model are front-loaded, but the whole definition is a single monolithic block with no visual grouping of the many distinct semantics (return shape, ordering, faults). Dense and largely waste-free, but readability suffers from the lack of 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 multi-request, deduplicating, order-unstable tool with no output schema, the description supplies everything an agent needs: the return envelope, lastResult shape with omitted-key and null rules, edge cases (empty issues, 404, truncation note), and default behaviors. Nothing material is left undocumented.

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 100%, so the baseline is 3; the description earns extra credit by explaining that maxCases is applied AFTER duplicate links are collapsed (so it counts distinct cases) and by clarifying that includeLastResults=false omits the key entirely rather than nulling it. These interaction details are genuinely new, though most of the parameter content overlaps the already-rich 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: a traceability report for a Jira issue covering every linked test case with its latest execution, and even names the underlying endpoints. It distinguishes itself from sibling tools by explicitly routing id-lookups to get_latest_result_for_test_case, so an agent can differentiate it without opening a 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?

Names an alternative (get_latest_result_for_test_case) and the exact condition selecting it ('when you need the id'), plus the includeLastResults toggle for skipping execution reads. It gives clear operational context but does not explicitly contrast against the closely related get_test_cases_linked_to_issue sibling, so it stops short of full when/when-not coverage.

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 supply readOnlyHint=true, but the description adds substantial behavioral context the annotation cannot: the ambiguous semantics of 'latest', live-verified evidence that it means highest id rather than newest date, the 404 condition, and the returned field shape. It also discloses read-back quirks (executionDate mirrors actualEndDate, executedBy duplicated as userKey, automated: true, issueLinks returned as traceLinks).

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?

Front-loaded with the verb, scope and endpoint, and nearly every sentence earns its place by adding non-obvious information. It is long and one clause ('so neither latest by date nor latest by date you set is a safe reading') restates the preceding point, costing a little tightness.

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 carries the burden of explaining return values and does so, enumerating fields and quirks. Combined with the 404 behavior and the ambiguity of the 'latest' selection, an agent has everything needed to call it correctly and interpret the result.

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?

There is a single parameter and schema description coverage is 100%, with the schema already supplying the format example (PROJ-T123). The description adds no additional meaning about testCaseKey beyond what the schema provides, 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 ('Read ONE execution of a test case across ALL test runs') and pins it to an endpoint, immediately distinguishing it from get_test_run_results and the run-scoped siblings. An agent can identify the tool's scope without opening the 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?

Gives explicit when-to-use-this vs when-to-use-an-alternative guidance ('whenever the specific execution matters, read the run with get_test_run_results instead') and names the failure condition (404 when the case has never been executed). This is a textbook routing instruction.

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 cover readOnlyHint=true, so the description carries the rest and does so usefully: STEP_BY_STEP scripts return a numeric id per step that update_test_case and set_test_script match on. That is genuine behavioral context beyond the annotation, though nothing is said about pagination or error 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?

Three sentences, front-loaded with the core action and endpoint, then the step-id caveat, then the return shape. Every sentence earns its place, with only mild density in the parenthetical.

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 compensates by describing the return ('the test case object as the API sends it, restricted to fields when given') and the step-id structure. Enough for an agent to call and interpret the result, though it doesn't note what happens for non-step scripts or missing keys.

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 both testCaseKey and fields. The phrase 'restricted to fields when given' adds only light confirmation of the fields parameter's effect, so 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 and resource ('Read one test case') and even gives the underlying endpoint GET /testcase/{testCaseKey}. It clearly distinguishes itself from siblings like search_test_cases, create_test_case, and delete_test_case.

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?

Routes the agent concretely: read step ids before editing steps by hand with update_test_case or set_test_script, and notes add_test_steps does that automation for you. It gives clear context and alternatives, but never explicitly states when to prefer this over search_test_cases.

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

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

Goes well beyond the readOnlyHint annotation: it discloses that the result is one entry per LINK (duplicates possible), that ordering is unstable and de-duplication by key is required, and that lastTestResultStatus is a denormalized value with specific staleness semantics after run deletion. This is exactly the kind of behavioral context annotations cannot carry.

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?

Purpose and routing are front-loaded in the first sentences, and the return-value caveats follow in a logical order. It is dense and long, but nearly every sentence carries distinct, non-redundant information; only slight trimming of the lastTestResultStatus explanation would improve it.

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 fully compensates by describing the return shape (array of test case objects, per-link entries), duplicate/order behavior, and the semantics of the key status field. An agent has everything needed to call and interpret 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 100% and the single issueKey parameter is already documented with an example format in the schema. The description references the key only via the endpoint path and adds no new meaning beyond what the schema provides, 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+resource ('List the test cases linked to a Jira issue'), gives the underlying endpoint, and frames the purpose as requirement/bug-to-test traceability. It clearly distinguishes itself from link_issues_to_test_cases (creation) and get_issue_test_coverage (execution-aware variant).

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?

Explicitly names the alternatives and the conditions selecting them: use link_issues_to_test_cases or the issueLinks field of create_test_case to create links, and use get_issue_test_coverage to also see the latest execution of each case. It even states when the distinction matters (denormalized vs live execution resolution).

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds genuinely useful behavior the annotations cannot express — that the payload embeds linked test runs and Jira issues, and that 'fields' can narrow it, letting an agent avoid extra round trips. It stops short of disclosing permissions, error behavior for a missing key, or payload size concerns.

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?

Front-loaded with the operation and endpoint, followed by the two most decision-relevant facts (embedded links, field narrowing). The trailing 'Returns the test plan object as the API sends it' is somewhat filler given there is no output schema to explain, but it is a single short clause.

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 read-only getter with full schema coverage and no output schema, the description gives enough to call it correctly — key-based lookup plus what the response contains. It could go further by stating behavior on a missing/invalid key or noting that omitted fields return the full object.

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 'testPlanKey' (with example PROJ-P123) and the comma-separated semantics of 'fields' are already documented in the schema. The description's 'narrow it with fields' adds only a marginal restatement, 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+resource+identifier ('Read a test plan by key') and even names the underlying endpoint (GET /testplan/{testPlanKey}), which clearly separates it from a bulk/search tool. It does not explicitly name the nearest sibling (search_test_plans), so an agent must infer that 'by key' is the differentiator.

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

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

Use is implied by 'by key' and by the note that 'fields' narrows the payload, but there is no explicit when-to-use/when-not guidance and no named alternative (e.g. search_test_plans or get_test_run) for the case where the caller lacks a key.

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=true, so the description carries the real burden and delivers: immutability (no PUT, items fixed at creation, status derived from item statuses), the internal-API auth flag required for mutation routes, and a non-obvious id-space caveat for items[].id. This is behavior far beyond anything the annotations provide.

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?

Purpose is front-loaded, followed by the immutability constraint, escape hatches, sibling alternatives, and the item-id warning. Every sentence carries information, though the single dense paragraph could be broken up for faster scanning.

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 read-only tool with no output schema, the description both sketches the return shape (key, name, status, owner, folder, items, or the filtered fields) and warns about the volatile items[].id. Nothing an agent needs to call it correctly or interpret results 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 description coverage is 100%, so both parameters are already documented, and the description's mention of returning 'only the requested fields' largely restates the schema. It adds no syntax or format 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?

States a specific verb and resource ('Read one test run / test cycle including its items') plus the underlying endpoint GET /testrun/{key}. It distinguishes itself from sibling read tools by naming get_test_run_results and get_test_run_summary as the tools for executions and status counts respectively.

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?

Explicitly routes the agent to alternatives: get_test_run_results for executions, get_test_run_summary for status counts, and the immutability escape hatches (recreate_test_run_with_items, or the internal-API tools gated behind ZEPHYR_ALLOW_INTERNAL_API=true). Both the when-to-use and when-not-to-use cases are covered.

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

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

With readOnlyHint already covering safety, the description adds substantial behavior: pagination semantics, the total/isLast formula, the note field indicating which path produced values, unspecified ordering, and 404 on missing runs. This is far beyond what annotations convey.

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?

Front-loads the purpose and every sentence carries information, but it is delivered as a single dense paragraph mixing return-value, fallback, and parameter detail. Slightly heavy for a description, though little 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?

No output schema exists, so the description fully documents the return shape ({ startAt, maxResults, total, count, isLast, values, note? }) and the meaning of total and isLast. An agent has everything needed to call and interpret results.

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% (baseline 3), and the description adds real meaning: onlyLastExecutions deduplication behavior and the fact that a newly created run already seeds one 'Not Executed' execution so total starts at the item count. It also clarifies maxResults client vs server defaults implicitly.

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 (page through) and resource (execution results of a test run / test cycle), including the underlying endpoint. It is clearly distinguishable from siblings like get_test_run, get_test_run_summary, and get_latest_result_for_test_case.

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 clear operational context: onlyLastExecutions semantics, the default, and the older-build fallback path. It does not explicitly name an alternative tool or state when to prefer this over, say, get_latest_result_for_test_case, so it stops short of full when/when-not 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 only declare readOnlyHint=true; the description carries the rest and does so richly — counting semantics ('LAST execution of each item'), the guarantee that latestResults/executed never exceed itemCount, case-sensitive verbatim status grouping, and edge cases like passRatePct being absent only when executed is 0. This is far beyond what the annotation provides.

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?

Dense and front-loaded: purpose first, then counting rules, then return shape. Every sentence carries semantic weight about the output contract, though the run-on structure and parentheticals make it heavier than strictly necessary.

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, so the description must define the return contract — and it does, enumerating every field (key, name, runStatus, itemCount, latestResults, executed, executionProgressPct, byStatus, passRatePct, note) plus the derivation of the computed fields. Nothing needed to interpret the result 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?

There is a single parameter with 100% schema description coverage, including an example key format (PROJ-R123 / PROJ-C123). The description adds no additional parameter meaning, 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+resource ('aggregated execution summary of a test run / test cycle') and immediately disambiguates it from siblings get_test_run and get_test_run_results by describing it as a composite read that aggregates counts. An agent can tell exactly what this returns versus the raw endpoints.

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 names the underlying endpoint (GET /testrun/{key}) and the fallback path (get_test_run_results), giving the agent context for when this aggregation path applies. It does not, however, explicitly say 'use this instead of get_test_run when you need counts' or state exclusions, so routing 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?

With only readOnlyHint provided, the description carries the behavioral load and does so richly: it discloses that any JSON error from the plugin (including 403) counts as reachable, that only Jira's HTML 404 or a network failure counts as unreachable, and that the tool itself fails only when Jira is unreachable or rejects credentials. It also describes the return shape, well beyond what the annotation provides.

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 primary check before the conditional plugin check. Every clause earns its place — the error-classification rules are exactly what an agent needs to interpret results, and the return summary is compact.

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, so the description appropriately documents the returned object (ok, jiraUser, baseUrl, zephyrPluginReachable) and the condition under which zephyrPluginReachable is omitted. Combined with the error semantics, an agent has everything needed to call and interpret this 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?

The tool takes no parameters, so there are no argument semantics to document; the schema is empty with additionalProperties false. Baseline 4 applies since no parameter explanation is needed.

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 — verify connectivity and credentials via GET /rest/api/2/myself, plus optional Zephyr plugin reachability on /rest/atm/1.0. This is clearly a diagnostic tool, distinct from siblings like jira_get_current_user (which fetches the user) or jira_server_info (which returns server metadata).

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 explains the tool's operating conditions (only checks the plugin when ZEPHYR_DEFAULT_PROJECT_KEY is set) and failure conditions, which gives useful context. However, it never explicitly says when to reach for this tool versus alternatives such as jira_request or jira_get_current_user — the diagnostic use case is only implied.

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 annotation readOnlyHint=false already tells the agent this is a mutation. The description adds a genuinely useful behavioral caveat (Server expects wiki markup, not Markdown), but says nothing about permission requirements, notification side effects, or whether the comment can be edited afterwards.

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

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

A single compact line with the key formatting gotcha front-loaded; no wasted words. It is a fragment rather than a full sentence, which slightly limits readability but not utility.

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?

Only two required, fully documented parameters and an output schema, so little is required of the description. It covers the main pitfall (markup format) but omits any mutation context such as permissions or side effects, leaving it minimally 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% – both 'key' (with an issue-key pattern) and 'body' are documented in the schema, and the description merely repeats the body formatting note. Baseline 3 is correct since the schema carries the parameter burden.

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'), which is unambiguous against the sibling read/update/delete comment tools. It does not explicitly name those siblings, but the tool name plus description make the add-vs-update-vs-delete distinction obvious.

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 tool versus jira_update_comment or jira_delete_comment, and no prerequisites stated (e.g. comment permission on the issue). The only usable signal is the verb itself, so context is entirely implied.

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, so the description carries most of the behavioral burden. It does not disclose whether the sprint must be active or future, whether issues already in another sprint are moved or rejected, or what happens on partial failure.

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 waste, which is good, but it is arguably under-specified rather than truly concise for a mutation tool with meaningful edge cases.

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 mutation tool with no output schema and only a minimal annotation, the description omits the operational context an agent needs: sprint state constraints, behavior for issues already in a sprint, and return/failure semantics.

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 parameters are documented in-schema, including the cross-reference to jira_list_sprints for sprintId and an example format for issues. The description adds nothing beyond this, 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 (move) and resource (issues into a sprint), which is distinguishable from the sibling jira_move_issues_to_backlog by direction. However, it does not explicitly name that sibling or scope the operation, 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?

No guidance on when to use this tool versus alternatives like jira_move_issues_to_backlog, nor any prerequisites (e.g., sprint must be active/future). Usage is only implied by 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?

The only annotation is readOnlyHint=false, which just confirms this is a write. The description adds nothing beyond that: it doesn't disclose idempotency (does adding an existing watcher fail or no-op?), permission requirements, or whether the watcher is notified. Minimal but not incorrect.

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. Nothing to trim and nothing misplaced.

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 only a readOnlyHint=false annotation, the description leaves too much unspecified: idempotency behavior, required permissions, and whether notifications fire. The schema covers inputs fully, but the behavioral surface of the write is undocumented.

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 both params are well documented in the schema (key pattern, username Server-vs-Cloud note). The description contributes no additional parameter meaning, 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?

Precise verb+resource: 'Add a user as a watcher of an issue'. An agent can immediately distinguish it from jira_get_watchers (read) and jira_remove_watcher (removal) without opening a 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?

Usage is implied by the mutating verb 'add' – this is the action to take when a user needs to watch an issue. But the description names no alternative, no prerequisite (issue existence, user existence), and no when-not condition. Sibling jira_get_watchers and jira_remove_watcher are not referenced.

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 supply only readOnlyHint=false, so the description carries nearly the full behavioral burden and delivers almost nothing: it omits that this is a mutating create, that it may fail if time tracking is disabled, and that timeSpentSeconds conflicts with the human-readable display format. Only the bare fact of logging work is conveyed.

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 — nothing wasted. It is arguably under-specified rather than verbose, but on the conciseness axis it is appropriately sized for what it attempts.

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

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

An output schema exists, so return values need not be explained, and the input schema is fully documented. What remains missing is behavioral and routing context — this is a write operation in a four-tool worklog family and the description gives no indication of that.

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 four parameters (key, timeSpentSeconds, started, comment) are documented in the schema with patterns and format examples. The description adds no syntax or format 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?

"Log work against an issue" names a specific verb (log work) and resource (issue), so the action is unambiguous. It does not, however, distinguish itself from siblings jira_update_worklog, jira_delete_worklog, or jira_list_worklogs, which an agent must open separately to disambiguate.

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 (timetracking must be enabled, user must have Work On Issues permission), and no pointer to the sibling worklog tools. The agent gets no signal about when creating a worklog is the right choice versus updating or listing 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 only declare readOnlyHint=false, so the description carries the rest of the burden. It adds nothing about permissions, notification side effects, or the fact that passing a null assignee performs an unassign operation. No contradiction with annotations, but no value added either.

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 words, front-loaded, no waste. It is appropriately terse for a simple two-parameter mutation, though it is on the edge of being under-specified rather than 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 write tool with no output schema and only a bare readOnlyHint annotation, the description should at minimum note the unassign behavior and any auth/notification implications. None of that is present, leaving the agent to rely entirely on 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%, and the schema itself documents both 'key' (with pattern and example) and 'assignee' (noting null unassigns). The description adds no 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?

The description states a verb and resource ('Assign an issue'), so the operation is unambiguous. However, it essentially restates the tool name jira_assign_issue and offers no differentiation from siblings such as jira_update_issue, which can also change an assignee.

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. needing an assignable user from jira_search_assignable), and no mention of alternatives like jira_update_issue. The agent must infer everything 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 declare only readOnlyHint=false, so the description carries most of the behavioral burden. It usefully discloses the two-phase workflow (describe_create then create) and that the fields object accepts ids or aliases, but says nothing about required fields, permission scope, failure modes, or what a rejected payload looks like. Adequate but with clear gaps 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?

Two short sentences, the action statement front-loaded and the prerequisite immediately after. No filler, no restatement of the title.

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

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

An output schema exists, so return values need no explanation, and the description covers the one genuinely hard part of this tool: how to construct the opaque fields object. It omits error/permission behavior, which is the only notable gap for a write operation.

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%, but the single parameter is a free-form nested object (additionalProperties), so the schema alone cannot tell an agent what to put in it. The description compensates by stating keys may be field ids or business aliases and pointing to jira_describe_create for value shapes — meaningfully beyond the schema text.

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 an issue'), which is unambiguous against the read/update/delete siblings (jira_get_issue, jira_update_issue, jira_delete_issue). It does not explicitly differentiate itself from other create-flavored siblings such as jira_create_remote_link or jira_add_worklog, but the resource is precise enough that misrouting is unlikely.

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

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

Gives an explicit prerequisite workflow: 'Call jira_describe_create first for the field template.' This is real routing guidance for the create path. It stops short of naming when-not-to-use conditions (e.g., to modify an existing issue use jira_update_issue), so it lands at 4 rather than 5.

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 only annotation is readOnlyHint=false, which merely confirms this is a write. The description adds no behavioral context: no permission requirements, no note on whether the link is idempotent or what happens on duplicate URLs, no return information. For a mutation tool this is 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 compact sentence with the verb and resource front-loaded and no filler. It is appropriately sized for a simple tool, though the parenthetical example is the only extra content.

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, no-output-schema tool with full schema coverage, the description covers the essential action but omits any usage context or behavioral notes. 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 description coverage is 100%, so all four parameters (key, url, title, relationship) are already documented in the schema, including the issue-key pattern and the example relationship string. The description adds nothing 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?

Specific verb ('Attach') plus resource ('remote link') and a concrete example (Confluence page) that disambiguates from jira_link_issues, which handles issue-to-issue links. It never names that sibling explicitly, so differentiation is left to the agent's inference 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?

There is no when-to-use guidance, no mention of prerequisites, and no routing to alternatives such as jira_link_issues (internal links) or jira_get_remote_links (read side). The agent must infer the use case purely from 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=true, so the safety profile is covered by structured data. The description adds nothing beyond that — no statement that deletion is permanent/irreversible, no permission requirements, and no error behavior — so it contributes no new behavioral context.

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 a single short sentence with zero filler and the action is front-loaded. It is appropriately terse for a one-parameter operation, though it borders on under-specification rather than deliberate 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?

For a destructive, non-read-only mutation with no output schema, the description is too thin: it omits irreversibility, permission needs, and failure modes. The destructiveHint annotation partly compensates, but the definition still leaves an agent without enough context to call this 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 100% and the schema itself documents the single `id` parameter, including its source ("from jira_list_attachments"). The description adds no syntax or format 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 gives a specific verb and resource ("Delete an attachment"), so an agent knows exactly what operation is performed. However, it does not distinguish this tool from the similarly named sibling `delete_attachment` (non-prefixed) or from other delete siblings, leaving ambiguity about which namespace to call.

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 preconditions, and no alternatives named. The agent gets no signal about how the attachment id should be obtained or when deletion is appropriate versus using `jira_get_attachment_meta` first.

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 safety profile is covered structurally. The description adds nothing beyond that: it doesn't state that deletion is permanent/irreversible, whether permissions are required, or what the response looks like.

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 waste. It is efficient, though its brevity leaves it under-specified rather than optimally 'concise'.

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 two-parameter delete with full schema coverage and annotations covering the safety profile, the minimum viable information is present. It still omits confirmation of permanence, which matters for a destructive operation.

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 a useful pointer that commentId comes from jira_list_comments, so the schema carries the parameter burden. The description adds no meaning beyond it, making the baseline 3 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 ('Delete a comment') that an agent can readily distinguish from its siblings jira_add_comment, jira_update_comment and jira_list_comments by name. It is clear but adds no explicit sibling differentiation beyond the naming convention.

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 the other comment tools, no prerequisites, and no mention of when deletion is appropriate or inadvisable. The agent must infer everything 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 destructiveHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds nothing beyond that: it does not say the deletion is permanent/irreversible, what happens to subtasks by default, or whether the issue must be unlinked first. With annotations lowering the bar, a bare restatement still leaves meaningful behavioral 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?

It is a single short sentence with no waste and the action is front-loaded, but it is so terse that it is under-specified rather than genuinely concise. Nothing is padded, but nothing is earned beyond the name either.

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 tool, the definition is incomplete: no mention of irreversibility, subtask handling implications, or required permissions. The annotations cover the destructive flag and the schema covers inputs, but the description does not compensate for the remaining behavioral risk an agent needs to weigh before calling it.

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

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

Schema description coverage is 100%, and both parameters (key with pattern and example, deleteSubtasks with default) are fully documented in the schema. The description adds no parameter meaning beyond that, 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?

The phrase 'Delete an issue' states a specific verb and resource, but it essentially restates the tool name (jira_delete_issue) without differentiating it from sibling delete tools like jira_delete_comment, jira_delete_attachment, or jira_delete_link. An agent can infer the target, but nothing in the text distinguishes scope or intent beyond the name itself.

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 or conditions (e.g., when to prefer jira_delete_link or jira_delete_comment for related objects). The agent must infer all usage context 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=true, so the agent knows this is a destructive write. The description adds only the source of the link id; it does not state that deletion is permanent or what happens to the linked issues, which is the kind of context that would add value beyond 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?

A single front-loaded sentence with a useful parenthetical and no filler. The phrase 'by its id' mildly restates the parameter name, keeping it just under a perfect 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?

For a one-parameter destructive tool with annotations covering the safety profile and no output schema, the description supplies everything needed to invoke it correctly: the action, the identifier, and where to find that identifier.

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% for the single linkId parameter, so the schema already documents it. The description's note about the issuelinks field reinforces but does not meaningfully extend the schema's own 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?

The description states a specific verb and resource ('Delete an issue link by its id'), which is unambiguous and clearly distinguishable from the link-creation siblings such as jira_link_issues. It does not explicitly name an alternative tool, so it falls just short of the top mark.

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 parenthetical 'find ids in the issue's issuelinks field' gives a prerequisite hint on how to obtain the required input, which is genuinely useful. However, there is no guidance on when to use this versus other link-related tools or any caution about the operation being irreversible.

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 known from structured data. The description adds nothing beyond that — no note that deletion is permanent/irreversible, no warning that the worklog is unrecoverable, and no indication of permissions required.

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 fragment with no wasted words and the operation is front-loaded. But the brevity reflects under-specification rather than tight economy, since nothing about behavior or usage is covered.

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 delete with full schema coverage and annotations signaling destructiveness, the structured fields carry most of the load. Still, an irreversible mutation tool with no output schema would benefit from at least a note on permanence or confirmation expectations.

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 schema documents both key (with pattern and example) and worklogId (pointing to jira_list_worklogs). The description adds no parameter meaning 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 verb (Delete) and a resource (worklog), so the basic operation is identifiable. However, it is essentially the tool name restated with no additional specificity, and it does not distinguish this from close siblings like jira_update_worklog or jira_list_worklogs.

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

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

There is no guidance on when to use this tool versus jira_update_worklog, jira_delete_issue, or other destructive siblings, and no mention of prerequisites or exclusions. The only implied usage comes from 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?

The readOnlyHint annotation already tells the agent this is a safe metadata read, and the description adds valuable return-content detail (writable fields, required flags, value shapes, allowed values) that compensates for the absence of an output schema. It does not mention that results are scoped per project/type beyond the brief parenthetical, leaving some behavior inferred.

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 waste: the trigger condition first, then a precise enumeration of what is returned. 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?

With no output schema, the description carries the burden and it explains the return payload well enough for the agent to consume it before creating an issue. Annotations cover the safety profile, so remaining gaps are minor.

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% with only two required parameters, both fully documented in the schema (including the pointer to jira_get_issue_types). The description adds no parameter-level meaning, so the baseline of 3 is correct.

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: it returns the field metadata (writable fields, required fields, value shapes, allowed values) for issue creation. Clear enough that an agent knows what it does, though it doesn't explicitly contrast itself with the parallel jira_describe_edit sibling.

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?

"Call before creating an issue" gives explicit, actionable timing for when to use it. There is no statement of when not to use it and no named alternative, but the intended invocation point is unambiguous.

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

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

readOnlyHint=true already tells the agent this is a safe read; the description adds the non-obvious behavioral fact that the returned field set is dynamic ("right now") and pre-filtered by workflow/screen. It doesn't mention auth requirements, but for a read-only introspection tool with annotation coverage, this is solid added value.

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

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

Two short sentences with the action directive front-loaded ahead of the return-value explanation. Every clause earns its place with 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 a single-param read tool with an annotation covering safety, the description explains both purpose and the nature of the return set. No output schema is needed, and the only minor gap is not distinguishing it from sibling discovery tools like jira_get_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?

Only one parameter (key) with 100% schema description coverage including a regex pattern and example. The description adds no syntax or format 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?

States a specific verb (Returns) and resource (fields editable on this issue right now), and adds the scoping detail that results are already filtered by workflow/screen. It does not explicitly differentiate itself from the similar sibling jira_get_fields (static field list) or jira_describe_create, so it stops just short of a 5.

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

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

Gives a clear directive on when to use it: "Call before updating an issue." This ties the tool to the update workflow. It doesn't name alternatives (e.g., jira_get_fields for the unfiltered list) or state when-not to use it, so it's 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?

The readOnlyHint annotation already establishes this is a safe read. The description adds the concrete set of metadata fields returned, which is useful context, but says nothing about auth requirements, error behavior for missing attachments, or size/pagination limits.

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

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

A single compact sentence with the resource and returned fields front-loaded and no wasted text. It is arguably under-informative rather than verbose, but structurally clean.

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

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

An output schema exists so return values need not be explained, yet the description still names the fields. For a single-parameter, read-only tool with full schema coverage, this covers what an agent needs to call it correctly, with only routing guidance 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 description coverage is 100% and the single 'id' parameter is already documented in the schema (including its source, jira_list_attachments). 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 (Get) and resource (attachment metadata) and even enumerates the returned fields (filename/size/author/download url). It is clearly distinct from sibling write tools like jira_upload_attachment or jira_delete_attachment, though it does not explicitly name or contrast with a sibling.

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 explicit when-to-use or when-not-to-use guidance. The only routing hint, that the id comes from jira_list_attachments, lives in the input schema rather than the description, so an agent reading only the description gets no selection 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 already declare readOnlyHint=true, and the description adds nothing beyond that safe-read implication. It does not explain pagination behavior despite a maxResults parameter, nor how jql interacts with board scope. With annotations lowering the bar, the description still contributes no extra behavioral context.

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 waste. It is appropriately sized, though it is terse to the point of under-specification rather than maximally 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?

An output schema exists, so return values need not be described, and all parameters are schema-documented. However, for a list tool sitting among search_issues, get_sprint_issues and list_backlog, the description omits any routing or pagination nuance an agent would need to choose 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 description coverage is 100%, so all three parameters (jql with example, boardId as numeric id, maxResults page size) are already documented in the schema. The description adds no syntax, format, or interaction detail beyond that, making the baseline 3 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 (List) and resource (issues) with a scoping qualifier (on a board), which distinguishes it from jira_search_issues and jira_get_sprint_issues by resource scope. However, it does not name or contrast with those siblings explicitly, so an agent must 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 when-to-use guidance, no mention of when to prefer this over jira_search_issues or jira_get_sprint_issues, and no prerequisites stated. The only routing signal is the implied 'board' scope in the purpose sentence.

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

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

With readOnlyHint=true already declaring the safe-read profile, the description contributes nothing further — no pagination behavior, no scope/ordering note, no indication of what a component entry contains. It essentially restates 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 front-loaded sentence with no filler. It is efficient, though its brevity is partly the cause of the missing guidance rather than a virtue of tight writing.

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 trivial single-parameter read tool with annotations covering safety, little else is strictly needed. However, with no output schema, the description offers no hint of the returned component shape or count, leaving a modest gap.

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 'key' parameter is documented with a format pattern and example, so the schema does the heavy lifting. The description adds no extra meaning about the key, making the baseline 3 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 ('List the components of a project'), so the agent knows exactly what it does. It does not, however, differentiate itself from nearby siblings like jira_get_versions or jira_get_statuses, which follow the same pattern.

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 (e.g. jira_get_project or jira_get_versions) and no prerequisites stated beyond the implicit project key. Usage is only inferable 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=true, so safety is covered. The description adds one piece of behavioral context beyond that: the returned identity is the authenticated caller, not a looked-up user. It says nothing about auth prerequisites, error behavior when unauthenticated, or rate limits, so it does not go far 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?

Five words, front-loaded with the verb, no filler. It is arguably too terse to be maximally useful, 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?

An output schema exists, so return values need no explanation, and there are no parameters or complex interactions to cover. For a zero-arg read tool the description is essentially sufficient, missing only sibling routing 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?

The tool takes zero parameters, and the schema is an empty object, so there is nothing for the description to disambiguate. The baseline for a parameterless tool 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 (Get) and a specific resource (the authenticated user), and the word 'authenticated' scopes it to the caller's own identity rather than an arbitrary user. That scoping does partly distinguish it from siblings like jira_get_user and jira_search_users, though it never names 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?

There is no explicit when-to-use guidance and no mention of alternatives such as jira_get_user or find_jira_user. The agent must infer that this tool is for the current caller and the others are for looking up other users.

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

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

readOnlyHint=true already declares this as a safe read, so the safety profile is covered by annotations. The description adds scope context (plugin fields included), which is genuinely useful, but says nothing about ordering, result size, or whether it includes custom fields beyond plugins. Adequate but limited beyond 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 short clauses with no filler, and the scope statement is front-loaded before the use case. Efficient and front-loaded, though extremely terse.

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 zero-parameter read tool, the description covers what is returned at a high level and its primary purpose (obtaining field ids). No output schema exists, so the return shape is only implied, but nothing critical is missing for 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?

Zero parameters, so the baseline of 4 applies. There are no parameter semantics for the description to clarify.

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

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

States a specific verb+resource ('List every field') and adds a distinguishing scope note ('plugin-provided ones included'). It is clearly separable from metadata siblings like jira_get_issue_types or jira_get_priorities, though it never names them. Clear but without explicit 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?

'Use it to obtain field ids' gives an implied usage context, which is helpful. It does not state when not to use it or point to a named alternative among the many metadata tools, so guidance remains thin.

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

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

readOnlyHint=true already establishes this is a safe read, so the bar is lower. The description adds useful behavior beyond annotations: the default is a full-field payload including custom fields, and expand can retrieve additional sections in one round trip. It says nothing about permissions, rate limits, or error behavior for a missing key.

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 waste, with the core action and default payload front-loaded and the expand hint following. Nothing is padded or repeated.

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

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

An output schema exists, so return values need no explanation, and readOnlyHint covers safety. The description supplies the one thing the schema can't: that the default response is all fields including custom fields, and how to widen it via expand. Complete for a simple read-by-key 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 100%, so all three parameters are already documented with examples. The description's mention of expand adds the nuance of co-fetching sections in the same call, but duplicates the schema's own example values (changelog, renderedFields) rather than adding new semantics. 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 ('Get an issue') and immediately characterizes the default payload ('all fields by default, custom fields included'), which separates it from list/search siblings like jira_search_issues. It never names a 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?

The description tells the agent how to use the expand parameter to fetch extra sections 'in the same call,' which is genuine usage guidance, but it offers no when-to-use/when-not framing relative to jira_search_issues or jira_get_transitions. Usage context is implied 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=true, so the safety profile is covered. The description adds nothing beyond that — no indication of scope (global vs per-project), whether the result is cacheable, or how many types are returned. It merely restates the operation.

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 words, front-loaded verb-first, with zero filler. Appropriately sized for a trivial no-argument lookup, though it is terse to the point of saying only what the name already says.

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 zero-parameter, read-only listing tool with no output schema, the description is minimally adequate: it conveys the operation but not the scope of the data (all issue types vs project-specific) or the shape of the response. Nothing is wrong, but an agent gets no help beyond the name.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the schema is trivially complete. Baseline 4 applies for a no-argument tool.

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 ('List') and resource ('issue types'), which cleanly distinguishes it from the nearby resource-lookup siblings such as jira_get_priorities, jira_get_statuses, and jira_get_fields. It stops short of any differentiation statement or scope qualifier, but the purpose is unambiguous.

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

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

No guidance on when to use this versus alternatives, nor any precondition or context (e.g. whether issue types are global or project-scoped). 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?

readOnlyHint=true already declares this is a safe read with no side effects, so the safety bar is met by annotations. The description adds that the `name` field is the consumable value for linking, which is useful output-consumption context, but it discloses nothing further about caching, auth, or result shape.

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

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

Two short sentences with zero waste: the purpose is front-loaded and the follow-on sentence earns its place by telling the agent what to do with the result.

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

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

An output schema exists, so return values need no explanation, and the description supplies the one integration detail an agent needs (use `name` for linking). It is essentially complete for a zero-arg read-only lookup, with only minor room for extra 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?

The tool takes zero parameters, so the baseline is 4. The description's note about the returned `name` concerns output rather than inputs and does not detract from the parameter picture, which is trivially complete.

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 ('List issue link types'), which is clearly distinct from neighbors like jira_get_issue_types, jira_get_priorities, or jira_get_remote_links. However, it never explicitly names a sibling to contrast with, so it falls short of the top band.

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

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

The second sentence gives real workflow guidance: the returned `name` is the value to pass when linking issues, which routes the agent to jira_link_issues. It does not state exclusions or prerequisites, so it is clear context without full when/when-not coverage.

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

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

readOnlyHint=true already tells the agent this is a safe read, and the description adds nothing beyond that. With no output schema, it should disclose what is returned (priority names, IDs, ordering) but does not.

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 words, front-loaded with the verb, no filler. It is efficient, though arguably too terse to be 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?

The tool is simple (no params, read-only), so a short description is defensible, but with no output schema the description never states what the priorities list contains or how to use it. Minimum viable for a metadata lookup.

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

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

The tool takes zero parameters, so the baseline of 4 applies. The schema is empty and the description adds nothing, but there is nothing to document.

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 ('List') and resource ('priorities'), so an agent knows this retrieves the available Jira priority values. However, it does not distinguish itself from the many sibling metadata-list tools (jira_get_statuses, jira_get_issue_types, jira_get_fields), and it essentially restates the tool name.

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 siblings like jira_get_fields or jira_get_statuses, and no context such as 'use to resolve valid priority names/IDs before creating or updating an issue.' Nothing is said about when-not to use it.

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=true, so the safety profile is covered, but the description adds nothing beyond that — it does not say what "details" encompasses, whether archived/deleted projects are resolvable, or what errors occur for an unknown key. With annotations present the bar is lower, yet this description contributes zero additional behavioral context.

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 a single four-word phrase with no wasted words and is trivially front-loaded. Its brevity, however, crosses into under-specification rather than efficient conciseness, so it does not earn a 4.

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

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

The tool is a simple single-parameter read with a fully documented schema and an output schema, so return values need not be explained. It is minimally adequate, but the vague term "details" leaves the agent unsure what project attributes are returned or how this differs from listing projects.

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 single required parameter (key) is fully documented in the schema with an example pattern. Per the baseline rule, a 3 is correct when the schema does the heavy lifting and the description adds no parameter meaning beyond it.

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?

"Get project details" gives a clear verb and resource, so the basic action is unambiguous. However, it offers no differentiation from siblings like jira_list_projects (which also deals with projects) or jira_get_issue (same get-by-key pattern), leaving the agent to infer scope from 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?

There is no guidance on when to use this tool versus jira_list_projects or other project-related tools, and no stated prerequisites such as required project permissions or whether the project must exist. The agent must guess the intended usage 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 readOnlyHint=true, so the safety profile is covered, and the description adds no behavioral context beyond that: no pagination behavior, no note on what happens for issues with no links, no return shape. For a read-only list tool this leaves the description doing little work.

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 verb and resource, and every clause earns its place; nothing redundant.

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, single-parameter read-only list operation with full schema coverage and no output schema, the description is sufficient to call the tool correctly. It stops short of 5 only because pagination or result-scope behavior is never hinted at.

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 single 'key' parameter is fully documented with a pattern and example, so the schema carries the burden. The description only implicitly ties the issue key to the target issue and adds no format or edge-case detail 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?

States a specific verb (List), resource (remote links), and scope (attached to an issue), and adds a concrete example (Confluence pages) that separates it from the similarly-named jira_get_link_types, jira_link_issues, and jira_create_remote_link siblings.

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

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

Usage is implied by 'attached to an issue' — the agent can infer it reads existing remote links for one issue — but there is no explicit when-to-use guidance or naming of alternatives such as jira_get_link_types for link metadata.

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

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

Annotations already declare readOnlyHint=true, so safety is covered, but the description adds nothing beyond that - no note on behavior for a nonexistent sprint id, no error handling, no pagination or return-shape context.

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. It is efficient, though its brevity edges toward under-specification rather than optimal 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?

For a simple read-only getter with an output schema and full annotation coverage, the description is minimally adequate. It still leaves the agent without usage guidance or failure-mode behavior, which are the only remaining 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% and there is a single integer parameter, so the schema fully documents it (including the exclusiveMinimum and the pointer to jira_list_sprints). The description adds no meaning beyond that, making the baseline 3 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 ('Get a sprint'), so the agent knows exactly what it retrieves. It does not distinguish itself from siblings like jira_list_sprints or jira_get_sprint_issues, 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 offers no when-to-use context, no prerequisites, and no routing to alternatives. The only hint at usage lives in the schema's parameter description ('from jira_list_sprints'), which is not part of the description text.

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