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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=true and an open-world network call, so the safety profile is covered structurally. The description adds no behavioral context of its own - it does not say whether existing associations are replaced or appended, whether some target fields require version_id, or what authorization is needed for an additive link.

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

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

A single front-loaded sentence with no filler; the action and its targets are stated immediately. Every word 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 an output schema and annotations present, the description need not cover returns or safety. However, for a 6-parameter mutation that is only meaningful if at least one target array is supplied, it never states that constraint nor how this tool relates to the many sibling add/remove association tools, leaving a real 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 every parameter is already documented in the schema, making 3 the baseline. The description's enumeration of Preconditions/Test Sets/Test Plans/Test Executions roughly mirrors the schema's array properties but adds no format, cardinality, or mutual-dependency detail.

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 ('Link') and resource ('Test') plus the four target association types, and the singular 'one Test' distinguishes it from the plural bulk siblings. It does not, however, explicitly contrast itself with xray_add_tests_to_test_set / xray_add_tests_to_test_plan, which perform the reverse-direction association, so a reader 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?

Usage is only implied by the purpose statement ('Link one Test to...'); there is no explicit 'use this when you have a single test and want to attach it to many containers' guidance and no mention of the sibling alternatives that do the same job from the other direction. No exclusions or prerequisites are stated.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely new behavioral context by disclosing the side effect that unknown environment names will be created rather than rejected.

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; the action comes first and the non-obvious side effect follows immediately.

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

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

With an output schema, full parameter coverage, and annotations in place, the description only needs to supply the missing side-effect information, which it does. It could optionally note whether re-adding an existing environment is a no-op, but idempotentHint already implies this.

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 (test_execution as a Jira key/id, test_environments as a name array) are documented in the schema. The description contributes nothing beyond what the schema already says, so the baseline 3 applies.

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

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

States a specific verb (Add) and resource (Test Environments to a Test Execution), which cleanly distinguishes it from the sibling xray_remove_test_environments. It stops short of any explicit sibling routing, but the action and target are unambiguous.

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

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

The description gives no when-to-use guidance, no prerequisites (e.g. required permissions on the Test Execution), and does not point to xray_remove_test_environments or xray_add_tests_to_test_execution as alternatives. 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=false, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered structurally. The description adds no behavioral context of its own -- nothing about idempotency semantics, failure modes, or partial success when some execution keys are invalid.

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 wasted words. It is efficient, though its brevity 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?

With an output schema present and annotations covering safety and idempotency, the description does not need to explain return values. What remains missing is the operational context an agent would want for a membership-mutating call: prerequisites, behavior on invalid keys, and relationship to the remove/add-tests siblings.

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

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

Schema description coverage is 100%, with both parameters documented in the schema itself (issue key or numeric id). The description adds no format, cardinality, or batch-limit 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?

The description pairs a specific verb ('Associate') with two specific resources ('Test Executions' and 'Test Plan'). This is enough to distinguish it from xray_add_tests_to_test_plan (tests, not executions) and xray_remove_test_executions_from_test_plan (inverse operation), though it never names a sibling explicitly.

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

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

There is no statement of when to use this tool versus alternatives, no prerequisites (e.g. that the plan and executions must already exist), and no mention of the inverse removal tool. Usage must be inferred entirely from the name.

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

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

Annotations already declare that this is a non-read-only, non-idempotent, open-world mutation, so the safety profile is covered externally. The description adds useful context that evidence may be supplied inline as base64 or by an uploaded attachment id, but it does not disclose duplicate behavior, permissions, or the consequence of calling it repeatedly for a non-idempotent 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?

The description is a single front-loaded sentence with no wasted words. It states the operation, the accepted input forms, and the target resource immediately.

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

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

For a two-parameter mutation tool with annotations and an output schema, the description is minimally adequate. It does not explain non-idempotent duplicate behavior or the practical prerequisite of uploading a file first when using attachment_id, leaving meaningful operational context to be inferred from sibling tools or schema descriptions.

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

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

Schema description coverage is only 50%, so the description must help compensate. It does add the meaningful distinction that the 'evidence' payload can be base64 data or an uploaded attachment id, but it says nothing about test_run_id provenance or filename/mime_type requirements beyond what the schema already supplies.

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 ('Attach') and resource ('evidence files') targeted at a 'test run,' which cleanly distinguishes it from broader attachment upload tools. It does not explicitly name or contrast with sibling tools such as xray_remove_test_run_evidence or xray_upload_attachment, so sibling differentiation is left implicit.

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

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

It mentions two supported input modes ('base64 or uploaded attachment ids'), which gives some usage context, but it never states when to use this tool versus alternatives like xray_upload_attachment or xray_remove_test_run_evidence. There are no prerequisites, exclusions, or workflow 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=false, idempotentHint=false, destructiveHint=false, and openWorldHint=true, covering the safety and repeat-call profile. The description reinforces accumulation semantics with 'append', but adds no auth, ordering, or side-effect detail beyond the structured fields.

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

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

A single short sentence with the verb and resource front-loaded and zero filler. It is efficient, though the brevity is also a symptom of the missing detail scored elsewhere.

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

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

For a 6-parameter mutation tool with half its parameters undocumented, the description is too thin. Output schema means return values need not be explained, but step ordering, the meaning of 'data' vs 'action', and the Call Test option are left entirely to the schema or unstated.

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

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

Schema description coverage is only 50%: 'test', 'call_test', and 'version_id' are documented, while 'action', 'result', and especially the ambiguous 'data' are not. The description supplies none of those semantics and gives no hint of the relationship between action, data, and result.

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: 'Append a step to a manual Test.' Against siblings like xray_update_test_step and xray_remove_test_step, the verb 'append' is reasonably distinguishing. It stops short of explicitly naming those alternatives, but the action is clear.

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 statement of when to use this over xray_update_test_step (edit an existing step) or xray_add_test_step variants. The scope restriction 'manual Test' hints at applicability, but there is no explicit guidance or exclusion.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety/mutability profile is covered. The description adds no behavioral context of its own — nothing about duplicate handling, permission needs, or what happens if a test is already linked.

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

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

A single front-loaded sentence with zero filler. It is arguably too terse for the information an agent needs, but as conciseness goes it wastes nothing.

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

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

With an output schema present, return values need not be explained, and annotations cover the mutation safety profile. Still, for a link operation whose counterpart exists as a sibling, the definition leaves the agent to guess about duplicate links and the unlink path — adequate but not complete.

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

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

Schema description coverage is 100%, with both parameters documented as Jira issue keys or numeric ids, so the baseline is 3. The description adds no additional meaning beyond the schema (no cardinality note, no ordering semantics for the array).

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 ('Link') and both resources ('Tests', 'Precondition'), so an agent knows exactly what operation occurs. It does not, however, distinguish itself from the sibling xray_remove_tests_from_precondition or the parallel add_tests_to_test_set/test_plan tools, so sibling differentiation is absent.

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

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

There is no when-to-use guidance, no prerequisites (e.g. the precondition must already exist), and no mention of the inverse operation for unlinking. The agent must infer usage entirely from the name.

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

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

Annotations cover the safety profile (readOnly=false, destructive=false, idempotent=true, openWorld=true), so the bar is lower. The description still adds real value by disclosing the side effect that each added Test spawns a test run, which the annotations do not 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?

A single tight sentence with the core action front-loaded and the notable side effect supplied in a parenthetical. 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 a full schema, an output schema present, and annotations declaring the safety and idempotency profile, the essential information is covered. The only real gap is the absence of routing guidance relative to the numerous sibling add/remove tools.

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 (tests array of Jira keys/ids and test_execution key/id) are already fully documented in the schema. The description adds no further syntax or format detail, placing it at the baseline of 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 (Add) and resource (Tests to a Test Execution), and adds the non-obvious side effect that a test run is created per Test. It does not differentiate from close siblings like xray_add_tests_to_test_set or xray_add_tests_to_test_plan, which share the same verb pattern, so an agent must infer the target-resource distinction 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 explicit guidance on when to use this tool versus alternatives such as xray_remove_tests_from_test_execution or xray_create_test_execution, nor any prerequisite or exclusion. Usage is only implied by the name.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety/idempotency profile is covered structurally. The description adds nothing beyond that — no note on duplicate handling (relevant given idempotentHint), no auth/permission requirements, no effect on existing plan membership.

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 short and front-loaded, but the single sentence is a verbatim echo of the name rather than an efficient information payload, so brevity here reflects under-specification rather than disciplined concision.

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 has a clear mutation semantic and an output schema exists, so return values need not be described. However, for a write operation with no description-level guidance on behavior (duplicates, limits, ordering), the definition is too thin to let an agent invoke it confidently.

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 (test_plan, tests) are fully documented in the schema with key/id format examples. The description contributes no additional meaning, which matches the baseline 3 for high-coverage schemas.

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 'Add Tests to a Test Plan.' is a direct restatement of the tool name (xray_add_tests_to_test_plan) and title, adding no distinguishing information. It conveys the verb and resource only because the name already does.

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

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

No guidance on when to use this versus siblings such as xray_remove_tests_from_test_plan or xray_add_test_executions_to_test_plan. No prerequisites, no mention of what happens when a test is already in the plan, no 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?

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered structurally. The description adds nothing beyond that – it does not explain what happens on repeat calls, whether existing memberships are preserved, or what the operation returns.

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

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

It is one short sentence, but this is under-specification rather than conciseness. There is no wasted wording because there is almost no wording at all; nothing is front-loaded because nothing is provided.

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 in a large family of parallel add/remove operations, the description is far too thin to guide correct selection. An output schema exists so return values need not be explained, but the absence of any behavioral or routing context leaves the definition inadequate.

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

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

Schema description coverage is 100%, with both parameters documented (Jira issue keys or numeric ids). The description adds no meaning beyond the schema, so the baseline of 3 applies when the schema does all the work.

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 "Add Tests to a Test Set" essentially restates the tool name and title verbatim. It names a verb and resource, but provides no scope or differentiation from siblings like xray_add_tests_to_test_plan or xray_add_tests_to_precondition, which share the identical 'add tests to X' 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?

There is no guidance on when to use this tool, when not to, or how it differs from the parallel add/remove tools for test plans, preconditions, and test executions. Usage is only implied by the tool name, and nothing routes the agent among the near-identical siblings.

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 cover the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=true), so the description only needs to add context. It notes that tests can be moved into the new folder in the same call, which is useful, but says nothing about failure modes (existing path, invalid project/test plan) or permission requirements.

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

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

A single, front-loaded sentence with no filler; the resource and the two placement modes come first, and the optional behavior comes last.

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 4-parameter create tool with an output schema and full annotation coverage, this is nearly sufficient: it names the two folder locations and the optional test attachment. It leaves out only edge-case behavior (path collisions, failure conditions), which keeps it short of a 5.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the project-vs-test_plan mode distinction but adds no format, syntax, or constraint detail (e.g. path normalization, whether tests are moved or copied) beyond what the schema already documents.

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 (folder), and scopes it to two concrete parent locations ('a project's Test Repository or in a Test Plan') with an optional payload. This distinguishes it cleanly from sibling folder operations like xray_rename_folder, xray_move_folder, and xray_delete_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?

Usage is implied rather than stated: the description hints at the two modes via 'Test Repository or in a Test Plan' and the optional Tests, and the schema's project/test_plan params disambiguate them. But it never says when to prefer this over xray_move_to_folder for relocating existing tests, nor any prerequisites.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false, so the mutation/safety profile is covered. The description adds one behavioral detail ('optionally linked to Tests'), but omits what is returned, whether linking requires pre-existing test keys, and any auth or folder constraints.

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 borders on under-specification for a 7-parameter create tool.

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

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

An output schema exists so return values need not be explained, and the schema covers most parameters. However, for a create tool with optional linking, a defaulted type, and an open-ended extra_fields object, the description leaves real gaps around interaction with sibling linking tools and the meaning of the precondition types.

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

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

Schema description coverage is 86%, so the schema already documents project, tests, definition, folder_path, extra_fields, and precondition_type. The description adds nothing beyond what the schema provides, so a 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 ('Create a Precondition issue') and adds the linking capability. It is clear but does not distinguish itself from sibling creation tools such as xray_create_test, relying on the reader to infer the differences 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 versus xray_create_test or xray_add_tests_to_precondition, nor any prerequisites or warnings. The agent must infer usage entirely from the tool name and sibling list.

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

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

Annotations already declare the write profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), so the description's main added value is that the created issue is an Xray Test with one of three definition modes. It says nothing about required permissions, duplicate-summary behavior, or what happens on conflicting definition inputs.

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 or restated boilerplate. It is terse to the point of being a fragment, 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 9 parameters, two required, and an output schema present, the description does not need to explain return values. However, for a creation tool with three mutually exclusive definition payload styles, the lack of routing between test_type and steps/gherkin/unstructured leaves a real gap for correct invocation.

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

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

Schema description coverage is 89%, so the schema already documents nearly every parameter. The description echoes the definition modes (steps/Gherkin/unstructured) but adds no mapping detail such as 'Manual => steps, Cucumber => gherkin, Generic => unstructured' that would help the agent pick the right field.

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 Xray Test issue') and enumerates the three definition flavors the tool supports, which distinguishes it from sibling create_* tools for preconditions, test sets and test plans. It does not explicitly name those siblings, but the resource noun is unambiguous.

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

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

No when-to-use guidance and no alternatives named. The agent must infer on its own whether to use this rather than xray_import_tests_bulk or xray_add_test_step, and nothing tells it which definition type to pick for a given input.

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 a non-read-only, non-idempotent, open-world mutation. The description adds that creating an execution generates one test run per Test, which is useful behavioral context. It does not cover permissions, duplicate-call effects, or rate 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?

Two short sentences, front-loaded with the core action, no wasted words. The linking note is useful and brief.

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 annotations covering safety, an output schema for returns, and 80% schema coverage, the description supplies the essential purpose and a key workflow hook (linking to plans). It could say more about idempotency or prerequisites, but it is largely sufficient.

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

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

Schema coverage is 80%, so the schema documents most parameters (tests, project, extra_fields, test_environments). The description only gestures at tests ('with Tests') without adding format or constraint details beyond the schema. 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?

Create a Test Execution issue with Tests (one test run per Test) is a precise verb+resource and scope. It distinguishes from sibling creators (Test, Test Plan, Test Set, Precondition) by naming the exact issue type. The linking instruction further clarifies its place in the Xray workflow.

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 explicit when-to-use versus alternatives (e.g., when to create a new execution vs. reusing an existing one, or when to use xray_add_test_executions_to_test_plan). The only guidance is a follow-up linking action via test_plans tools, which is not a usage condition.

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

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

Annotations already declare this is non-read-only, non-idempotent, non-destructive and open-world, so an agent knows calling it mutates state. The description adds nothing beyond that — it doesn't say a repeat call creates a second plan, what permissions are needed, or how the two test-sourcing paths (tests vs saved_filter) interact.

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 sentence is appropriately short, but the 'e.g. fixVersions via extra_fields' clause is a non sequitur attached to the tests clause and creates rather than removes ambiguity.

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 five parameters, two required, and two competing ways to attach tests (tests keys/ids vs saved_filter), the description should explain how those interact and which wins. Output schema exists so return values need no explanation, but the input-side ambiguity is left unaddressed.

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

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

Schema coverage is 80%, so the schema already documents tests, project, summary, extra_fields and saved_filter. The description restates the optional-Tests behavior and gives a fixVersions example that duplicates the extra_fields schema description rather than clarifying semantics. 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 ('Create a Test Plan issue') and notes the optional association with Tests, which distinguishes it from siblings like xray_create_test and xray_create_test_set. The trailing parenthetical is muddled, but the core 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 xray_add_tests_to_test_plan (for existing plans) or when to prefer saved_filter over an explicit tests list. The 'optionally with Tests' phrasing implies a use case but names no alternatives or prerequisites.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, and idempotentHint=false, so the safety and mutability profile is largely covered. The description adds only that Tests may be included optionally, but it does not disclose auth requirements, side effects beyond creation, or rate limits. It is consistent with the annotations and adds limited 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?

The description is a single front-loaded sentence with no wasted words. It states the core action and the optional add-on directly. Every part of the 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?

An output schema exists, so return values need not be described. Annotations cover safety and mutability. However, the description omits usage guidance, does not mention required project and summary parameters, and does not mention extra_fields, leaving some gaps despite the structured schema support.

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

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

Schema description coverage is 75%, so the schema already documents most parameters including tests, project, and extra_fields. The description mentions the optional Tests parameter but does not clarify project, summary, or extra_fields behavior. Baseline 3 is appropriate because the schema does most of the semantic work.

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

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

The description gives a specific verb and resource: 'Create a Test Set issue'. It also notes the optional inclusion of Tests. It does not explicitly differentiate from nearby siblings such as xray_create_test or xray_add_tests_to_test_set, but the resource name 'Test Set' is distinct enough to be clear.

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 provides no when-to-use guidance, prerequisites, or alternatives. It is implied that this tool creates a new Test Set issue, but the agent receives no explicit direction on when to choose this over xray_add_tests_to_test_set or how to handle existing Test Sets.

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, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: subfolders are deleted recursively while the Test/Precondition issues inside are preserved, which an agent could otherwise get wrong. Permissions and irreversibility are not restated, hence not a 5.

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

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

Two short sentences with zero filler; the destructive scope is front-loaded and the preservation caveat follows immediately. 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 an output schema present, return values need not be explained, and annotations plus full schema coverage carry the rest. The description covers the two facts an agent most needs for a destructive folder operation (recursion and issue preservation); only permission requirements are unstated.

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 all three parameters (path, project, test_plan), including the '/' root convention and the repository-vs-test-plan distinction. The description contributes nothing 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 ('Delete a folder') plus the destructive scope ('and its subfolders'), which clearly separates it from siblings like xray_create_folder, xray_rename_folder, and xray_move_folder. It never names an alternative explicitly, 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?

There is no statement of when to use this tool versus alternatives such as xray_remove_from_folder (which detaches rather than deletes) or xray_move_folder. No prerequisites or preconditions are given, leaving the agent to infer the selection context.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is largely covered. The description adds the word 'permanently', reinforcing that this is not a recoverable/soft delete, which is useful context beyond the annotations. It does not disclose cascading effects (e.g., removal from linked tests) or auth requirements.

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

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

One short, front-loaded sentence with no wasted words. The destructive nature is conveyed immediately.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety profile. However, for a permanent delete of an issue type that other entities (tests) reference, the description omits any note about side effects or linked-entity impact, leaving a meaningful 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?

Single parameter with 100% schema description coverage; the schema explains it accepts a Jira issue key or numeric id. The description adds nothing about the parameter, which is the expected baseline when the schema fully documents 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?

States a specific verb (Delete) and resource (a Precondition issue), making the target object clear. It does not differentiate itself from siblings such as xray_delete_test or xray_delete_test_set beyond the resource noun, but the resource is distinct enough that selection 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, no prerequisites, and no warning about consequences for tests that reference the precondition. The agent must infer the usage context entirely from the tool name.

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

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

Annotations already flag destructiveHint, idempotentHint, and readOnlyHint=false, so the safety profile is covered. The description still adds real value by disclosing the non-obvious side effect that the Jira issue itself is deleted, expanding the blast radius beyond what the annotations state. It does not cover cascading effects on related test runs, steps, or executions, nor permission requirements.

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

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

One sentence, zero filler, with the destructive nature and the surprising Jira-issue side effect front-loaded. 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 an output schema present, return values need not be explained, and annotations carry the disposition hints. For a destructive one-parameter tool the description is nearly sufficient, missing only cascade scope and permission/undo 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?

Single parameter with 100% schema description coverage, so the schema already documents the accepted key/id formats. The description adds nothing about the 'test' argument, making this a baseline 3 case where structured data does the work.

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

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

States a specific verb (Delete), a precise resource (Test issue), and adds that the underlying Jira issue is removed too. The word 'Test' distinguishes it from sibling deletions like xray_delete_test_set, xray_delete_test_plan, and xray_delete_test_execution, though it never explicitly names those alternatives.

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 delete tools or the alternative update/archive paths, and no stated prerequisites. 'Permanently' hints at caution but is not framed as a when-to-use condition.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but they do not say what is destroyed. The description adds that the deletion is permanent and removes associated test runs, which is meaningful cascade information 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?

One sentence, front-loaded with the verb and resource, and the consequential detail (permanent, test runs included) is stated without 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?

An output schema exists, so return values need not be explained, and the single parameter is fully documented in the schema. The cascade behavior is covered; only irreversibility warnings and auth expectations are absent, which is a minor gap for a one-parameter delete.

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

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

The single parameter has 100% schema description coverage (Jira issue key or numeric id), so the schema already carries the semantics. The description adds nothing about the identifier format, 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 (Delete) and resource (Test Execution issue), and adds scope: the deletion is permanent and cascades to the test runs. This distinguishes it from siblings like xray_delete_test, xray_delete_test_plan, and xray_delete_test_set by resource.

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 such as xray_remove_tests_from_test_execution or xray_delete_test. No prerequisites, permissions, or confirmation requirements are stated, so the agent must infer usage entirely.

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, idempotentHint=true and openWorldHint=true, so the safety profile is largely covered. The description's only addition is the word 'permanently', which usefully reinforces irreversibility but says nothing about cascading effects on associated test executions or required permissions.

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 efficient, though arguably under-specified rather than optimally concise for a destructive operation.

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 one fully documented parameter, an output schema, and annotations covering safety and idempotency, the description is sufficient to invoke the tool correctly. The only missing element is a note on side effects for related executions.

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 parameter, with the schema already documenting accepted formats (Jira issue key or numeric id). The description adds nothing 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 ('Delete') and resource ('Test Plan issue') with the scope qualifier 'permanently'. It is distinguishable from siblings like xray_delete_test and xray_delete_test_set by naming the exact entity, though it does not explicitly contrast with 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?

No guidance on when to use this versus alternatives, nor on prerequisites or when deletion is inappropriate. For a destructive, irreversible operation, the absence of any 'when-not' context is a real gap.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so safety is covered. The description adds genuinely non-obvious behavioral context: the deletion is permanent and the member Tests survive the operation, which an agent could not infer from the schema or annotations alone.

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

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

A single tight sentence with the destructive action front-loaded and the critical side-effect in a parenthetical. Nothing is wasted.

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

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

For a one-parameter destructive tool with full annotation coverage and an output schema, the description supplies the essential behavior (permanent, non-cascading). It could mention any permission requirements or irreversible-confirmation guidance, but is nearly 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?

Only one parameter (test_set) with 100% schema description coverage, so the schema already documents the accepted key/id formats. The description adds no additional parameter meaning; baseline 3 applies.

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

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

States a specific verb (delete) and resource (Test Set issue) and adds the key scoping fact that contained Tests are kept, which meaningfully distinguishes it from xray_delete_test. It does not name sibling tools explicitly, so it stops short of full sibling differentiation.

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

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

The word 'permanently' signals the destructive nature, but there is no explicit statement of when to use this versus xray_delete_test, xray_delete_test_plan, or xray_remove_tests_from_test_set, and no prerequisites or warnings about irreversibility are given.

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, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is fully covered elsewhere. The description adds the return content shape ('each file's name and content'), but no behavioral context such as permission requirements, output format/archive details, or behavior when no selector is supplied.

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

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

A single front-loaded sentence with the action first and the return preview second; nothing is padded. The return clause is largely redundant with the output schema, which keeps it just short of a 5.

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

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

With an output schema present, return values need no prose, and all parameters are documented in-schema. What's missing is selection behavior for a zero-required-parameter export (what is exported by default, and how keys vs filter_id are combined).

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 both parameters, so the schema carries the semantics of keys and filter_id; the description adds nothing about their interaction or precedence. Baseline 3 applies when structured fields do the work.

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 ('Export Cucumber Tests as .feature files') and even previews the return shape. It does not explicitly contrast itself with the sibling xray_import_cucumber_features, but the export direction 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 tool versus alternatives, and no hint about how to choose between the two mutually competing selection inputs (keys vs filter_id). The name suggests the context but the description states no conditions or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: return encoding varies by content type (text files as text, others as base64), which affects how the agent must handle the response.

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

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

One sentence, front-loaded with the action, followed immediately by the return-format caveat. No filler and nothing important is 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?

With a rich annotation set, a fully documented single parameter, and an output schema present, the description only needs to add the caller-facing behavior it does (text vs base64 payload). Minor omissions such as error behavior or size limits remain, but nothing essential for correct invocation 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 ('Attachment or evidence id.'), so the schema carries the semantics. The description adds no format, source, or lookup guidance for attachment_id, 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 (download) and resource (attachment or evidence file), and the name pairs it against its sibling xray_upload_attachment. It is clear what the tool does, though it never explicitly contrasts itself with any 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?

Usage is only implied: it is a fetch-by-id tool, so the agent infers it is used to retrieve a known attachment id. There is no statement of when to prefer this over, say, xray_get_test_run or xray_get_step_library, nor any prerequisites.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered. The description adds the useful fact that the response includes both coverage status and the covering Tests, but says nothing about how coverage is computed or what happens when version/test_plan/environment scoping is combined.

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

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

A single efficient sentence with the core action and result front-loaded and no filler. It is arguably too terse for a six-parameter tool with several scoping options, 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?

An output schema exists, so return-value explanation is not required, and annotations cover safety. However, for a tool with six parameters offering version, test-plan, environment and final-status scoping, one sentence leaves the agent without guidance on how those modes interact or which combinations are meaningful.

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 every parameter including version, is_final, test_plan and environment is already documented in the schema itself. The description adds no syntax, formatting, or interaction hints 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 gives a specific verb and resource ('Get the coverage status of a requirement / story and the Tests covering it'), so an agent knows it returns coverage data plus linked tests. It does not, however, distinguish itself from the near-identical sibling xray_get_coverable_issues, leaving the singular/plural boundary to be inferred.

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 indication of when to use this versus xray_get_coverable_issues, nor any mention of prerequisites such as needing a valid Jira issue key. The agent gets no routing guidance at all.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that results are paginated, which annotations do not convey, but says nothing about how coverage is computed, default page size, or the interaction between version/test_plan/environment scoping.

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

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

A single front-loaded sentence with the resource stated first and the pagination constraint last; no filler. It is efficient, though arguably too terse given the tool's nine parameters.

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

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

An output schema exists, so return values need not be explained, and the schema fully documents parameters. But for a 9-parameter search tool whose behavior depends on coverage-scoping inputs (version, test_plan, environment, is_final), the description omits how these shape the result, leaving an inference 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 every parameter (jql, limit, start, fields, issues, version, is_final, test_plan, environment) is already documented in the schema. The description contributes 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 (Search) and resource (coverable issues: requirements, stories) plus the returned dimension (coverage status). However, it never distinguishes itself from the sibling xray_get_coverable_issue (singular), leaving the agent to infer the plural/singular split 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?

The description gives no when-to-use guidance, no conditions or exclusions, and no mention of the singular get_coverable_issue alternative or when a bulk/paginated search is preferable to a single-issue lookup. Only the '(paginated)' hint implies 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 read-only, idempotent, non-destructive, open-world behavior. The description adds that the payload contains parameters and rows and that overrides may apply, but it does not expand on permissions, limits, or edge cases beyond what annotations/schema 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?

One front-loaded sentence with no filler; verb and resource lead. Every phrase contributes to scoping the request.

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?

Output schema exists, annotations state safety, and schema thoroughly documents parameters and the one-test-with-override edge case. The description supplies the essential purpose, so an agent has enough 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 all three parameters are documented in the schema. The description only repeats the override idea and does not add syntax or format details beyond 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: retrieving datasets (parameters and rows) of data-driven Tests, with optional override context. It clearly separates this from sibling get_test tools that fetch test metadata rather than dataset content, though it does not explicitly name an alternative.

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?

Only implies when to use it through 'optionally as overridden on Test Plans / Executions'; it does not say when to choose this over other getters or when not to request overrides. The schema carries the real conditional logic.

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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds real behavioral context beyond them by disclosing that Call Test steps are flattened/expanded, which changes the shape of the returned step list. It stops short of noting any recursion depth, performance, or unresolvable-reference caveats.

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 sentence with zero padding, front-loading the resource and the one behavior that matters. Nothing is repeated from the title or schema.

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

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

With an output schema present, return values need not be explained, and annotations plus a fully-described schema cover the rest. The only gap is the lack of routing guidance versus xray_get_test, which would make this a standalone definition.

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%: test, fields, and version_id are all documented in the schema itself. The description adds no parameter-level detail (e.g. how fields interacts with the expanded steps), 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 (Test) with a distinguishing behavioral detail: 'Call Test' steps are expanded inline into the called tests' steps. That expansion is exactly what separates this from the sibling xray_get_test, though the description never names that sibling explicitly.

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

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

Usage is only implied by the expansion behavior – an agent can infer 'use this when you want Call Test steps resolved', but there is no explicit when-to-use, when-not-to-use, or pointer to xray_get_test as the non-expanded alternative.

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, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds genuinely behavioral detail beyond that: the result includes counts and the entire recursive subfolder tree, which tells the agent this is a deep traversal rather than a shallow listing. It does not mention pagination or size limits for large repositories.

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

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

Two sentences, zero waste. The core capability is front-loaded before the sibling routing sentence, so an agent skimming the opening clause already knows what the tool returns.

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 spelled out; the description still usefully flags that the subfolder tree is complete, which is the key recursion property. Missing only guidance on project vs test_plan selection, which the schema descriptions already handle adequately.

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 all three parameters documented in the schema including the project vs test_plan distinction, so the baseline is 3. The description contributes only the folder_path usage hint via the sibling reference, adding no syntax or format 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 and resource ('Get a folder') plus its scope ('with its counts and complete subfolder tree'), which distinguishes it from the mutation siblings like xray_create_folder and xray_move_folder. It also routes to xray_get_tests for the folder's Tests, though 'counts' is left unqualified (counts of what?).

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 alternative (xray_get_tests with folder_path=...) and the condition that selects it, so the agent knows where to go when it wants a folder's Tests rather than the folder itself. No exclusions or guidance on choosing between project and test_plan modes for folder scope.

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, idempotentHint, openWorldHint and non-destructive, covering the safety profile. The description adds the useful behavioral detail that it surfaces progress and per-test errors, but with an output schema present the shape of those returns is partly already documented.

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

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

A single front-loaded sentence that names the resource and the payload categories with no wasted words. Optimal length for a one-parameter status tool.

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

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

Because an output schema exists, the description need not explain return values; it correctly points at the job_id source. It is complete for calling the tool, though it could note polling/retry expectations for a job-status endpoint.

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, documented at 100% coverage in the schema with its origin (jobId from xray_import_tests_bulk). The description does not add format, type, or retrieval semantics beyond what the schema already 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 (Get) and resource (status/progress of a bulk test import job), and explicitly enumerates what is returned (progress, per-test results/errors). It is immediately distinguishable from the many get_* siblings because it scopes to an import job rather than a test, plan, or 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?

The schema links job_id to the output of xray_import_tests_bulk, which implies this is a follow-up/polling call, but neither description nor schema states when to call it (frequency, after queuing) or contrasts it with other alternatives. Usage is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, lowering the bar. The description adds genuine behavioral context beyond that: the result is paginated and the history covers who/what/when including steps, definition and links.

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 tight sentence that front-loads the resource and ends with the pagination qualifier. Every clause earns its place; nothing is redundant with 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?

With an output schema present, return-value detail is unnecessary, and annotations cover the safety profile. The description is nearly sufficient, though it could note the auth/scope requirement or that history may be empty for certain issue types.

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

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

Schema description coverage is 100%, so all four parameters (issue, issue_type, limit, start) are fully documented with types, bounds, defaults and an enum. The description adds no parameter-level syntax or format 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?

Specific verb (Get) plus precise resource (Xray change history of an issue) and an enumerated scope of what the history contains (steps, definition, links) and when. No sibling tool covers issue change history, so it is trivially distinguishable from the get_* family.

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 purpose implies when to reach for it (auditing changes to an issue), but there is no explicit when-to-use/when-not guidance and no alternatives are named. Adequate but inferential.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds only that the list is 'known to Xray' (i.e., an Xray-scoped subset rather than all Jira link types), which is a mild behavioral nuance. With an output schema present, return values need no further explanation.

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

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

A single front-loaded sentence with no filler. Every clause (verb, resource, scope, purpose) earns its place.

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

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

For a zero-parameter, read-only lookup with full annotations and an output schema, the description supplies everything an agent needs to decide to call it. No gaps remain that more text would usefully close.

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. Schema coverage is also 100% with an empty properties object, meaning there is nothing for the description to compensate for.

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

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

The description gives a specific verb ('List') and resource ('Jira issue link types known to Xray') plus a scoping qualifier ('used for requirement coverage'). This is clearly distinguishable from the many test/precondition/plan/run siblings and from the other lookup tools like xray_get_statuses.

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

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

The phrase '(used for requirement coverage)' implies the context in which link types matter, but there is no explicit when-to-use, when-not-to-use, or alternative named. Usage is implied rather than stated, which is the minimum viable level.

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, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds the useful detail that the result includes the precondition's type, definition, folder and linked Tests, but says nothing about error behavior for a missing/invalid key or the size of the linked-Test set.

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

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

A single front-loaded sentence with no filler; the resource and the payload it returns are stated immediately with zero 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?

With an output schema present, the description need not describe the return shape, and the safety profile is carried by annotations, so what remains is adequate for a 2-parameter read tool. The only shortfall is the absence of any disambiguation from the sibling list tool.

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

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

Schema description coverage is 100% – both the precondition key/id format and the optional 'fields' Jira field list are fully documented in the schema. The description contributes no additional parameter meaning, so the baseline 3 applies.

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

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

States a specific verb ('Get') and resource ('a Precondition') and enumerates the returned facets (type, definition, folder, linked Tests), which is more informative than the title alone. However, it never distinguishes itself from the sibling xray_get_preconditions (plural list tool), leaving the singular/plural routing to be inferred from the 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 when-to-use guidance, no stated prerequisites, and no mention of alternatives such as xray_get_preconditions for listing or xray_get_expanded_test for deeper traversal. The agent must infer that this is the single-entity fetch from the name and parameter shape.

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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered without the description. The description adds only the pagination trait, which the limit/start parameters already convey in the schema, and says nothing about return shape or result ordering.

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: verb, resource, filter dimensions and pagination trait in that order. Nothing could be removed without losing 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?

With an output schema present and 100% parameter coverage plus a full annotation set, the description only needs to frame the search scope, which it does. It is close to complete, missing only a note on the singular-vs-list sibling relationship.

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 eight parameters including defaults and the fields list; baseline is 3. The description's filter enumeration only restates what the schema supplies, adding no format or syntax detail 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?

States a specific verb+resource ('Search Preconditions') and enumerates the filter axes (JQL, keys, project, type) plus pagination, which is far more informative than the plural name alone. It reasonably separates itself from the singular xray_get_precondition, though it never explicitly states the list-vs-single 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?

The enumerated filters imply when the tool is useful (you have a JQL, key list, project or type to search by), but there is no explicit guidance on when to prefer xray_get_precondition for a single known key, nor any exclusions or prerequisites. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety and repeat-call profile is fully covered. The description adds only the set of configuration categories returned; it says nothing about auth requirements, rate limits, or whether settings are merged across multiple projects.

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, with the enumerated contents doing useful work rather than padding. Nothing extraneous.

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 annotations cover the safety profile. For a simple one-parameter read tool this is nearly sufficient, though a hint about valid project identifiers or when to prefer this over GraphQL-based queries would close the remaining 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 single 'projects' array parameter is documented as 'Jira project keys or ids'. The description adds no 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?

States a specific verb (Get) and resource (Xray project settings), then enumerates exactly what the settings comprise: test types, test environments, coverage, step fields, test run custom fields. No sibling tool retrieves project-level settings, so the agent can distinguish it 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?

No when-to-use guidance, no prerequisites (e.g., that a valid Jira project key is needed), and no mention of alternatives. Usage is only implied by the tool name and the listed return contents.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds the global-vs-project scope distinction, which is useful, but discloses nothing further about behavior. With annotations carrying the load, a 3 is appropriate.

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

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

One front-loaded sentence with no wasted words; the scope qualifier is compactly parenthesized. Nothing extraneous, though it is 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?

A single optional parameter, full annotation coverage, and an output schema mean little more needs saying. The description covers the essential scope nuance, so an agent can 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% and the single 'project' parameter is fully documented in the schema, including the omit-for-global semantics. The description's mention of 'globally or for a project' restates rather than extends 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 (List) and resource (test run statuses and step statuses), which is clear enough to distinguish it from the surrounding test/run CRUD siblings. It does not explicitly name an alternative tool, but the resource is unambiguous.

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

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

The parenthetical '(globally or for a project)' implies the two usage modes, and the schema clarifies that omitting project yields the global configuration. There is no explicit when/when-not guidance or naming of alternatives.

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 readOnly, idempotent, non-destructive, openWorld, so the safety profile is covered. The description adds nothing further: no mention of pagination behavior, what happens with no filters applied, or the global vs project-scoped configuration distinction present in the schema.

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

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

A single front-loaded sentence with no waste. It is efficient but arguably too terse for a six-parameter search tool, which keeps it just under a 5.

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 all parameters are documented in the schema. However, for a tool with six optional filters, the description never clarifies the default scoping behavior (all steps vs project-scoped) or how filters compose, 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%, so all six parameters are already documented in the schema (kind, test, limit, start, search, project). The description adds no extra semantic detail beyond what the schema provides, 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?

Names a specific verb ('Search') and resource ('the reusable manual or BDD (Gherkin) step library'), and the kind enum reinforces the two modes. It does not distinguish this from sibling tools like xray_get_test or xray_add_test_step, so it stops short of a 5.

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

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

No statement of when to reach for this tool versus related siblings (e.g. xray_get_test for a specific test's steps, or the add/update step tools). The two library kinds are implied rather than framed as usage guidance, leaving the agent to infer selection.

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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds useful content-level context by naming the definition variants returned (steps/Gherkin/unstructured) and the folder/Jira field payload, but says nothing about errors, permissions or missing-test 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?

A single front-loaded sentence that leads with the verb and resource and then enumerates the returned content. No filler, no 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?

An output schema exists so return values need not be re-explained, annotations cover the safety profile, and all four parameters are schema-documented. The description is sufficient to call the tool, with the only real gap being the lack of routing guidance against the near-identical expanded/versions siblings.

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

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

Schema description coverage is 100%, so 'test', 'fields', 'include_relations' and 'include_requirements' are already fully documented in the schema. The description adds no syntax, format or default information beyond what the schema provides, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Get one Xray Test') and enumerates what the payload contains: type, steps/Gherkin/unstructured definition, folder and Jira fields. The word 'one' implicitly separates it from the plural sibling xray_get_tests, but it never addresses xray_get_expanded_test, which an agent would likely confuse it with.

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

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

There is no statement of when to use this tool versus xray_get_expanded_test, xray_get_test_versions or xray_get_tests. The single-item framing gives a weak implied context (fetch one test by key), but no explicit conditions or exclusions are offered.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds useful payload context (it returns environments, Test Plans, and test runs), but says nothing about pagination behavior beyond the schema, authentication, or performance cost.

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

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

A single front-loaded sentence that states the resource and its returned contents with zero filler. Every clause earns its place.

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

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

An output schema exists, so return values needn't be fully explained, and annotations carry the safety profile. The description covers the resource and its main contents, though it could note how runs pagination interacts with the runs_limit/runs_start parameters.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters (test_execution key/id, fields, runs_limit, runs_start). The description adds no syntax, format, or default detail beyond what the schema provides, 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 (Get) and resource (Test Execution) and enumerates the returned sub-resources (environments, Test Plans, test runs with test + status). The singular name plus 'a Test Execution' distinguishes it from the plural sibling xray_get_test_executions, though this distinction is implicit rather than stated.

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

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

There is no explicit when-to-use guidance, no mention of alternatives like xray_get_test_executions or xray_get_test_run, and no stated prerequisites. The agent can infer it fetches a single execution by key/id, but nothing is spelled out.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds that results are paginated, which is useful context, but it does not disclose authentication needs, rate limits, or other behavioral traits beyond what annotations and the output schema 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 description is a single sentence with zero filler, front-loading the search action, the resource, and the accepted query forms. It is appropriately sized for a paginated list tool whose parameters and return shape are defined elsewhere.

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

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

Given full schema coverage, an output schema, and annotations that cover the operation's safety profile, the description provides enough orientation to call the tool correctly. It could be improved by explicitly differentiating from the singular retrieval sibling or mentioning filtering options like modified_since, but it is complete enough for a straightforward search endpoint.

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

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

Schema description coverage is 100%, so all seven parameters are already documented in the input schema. The description mentions JQL, keys, and project, which maps to a subset of parameters, but it adds no syntax or format detail beyond what the schema already provides. A baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description names a specific verb ('Search') and resource ('Test Executions'), and lists the primary query modes (JQL, keys, project) plus pagination. It is clear what the tool does, but it does not explicitly distinguish itself from the singular sibling xray_get_test_execution or other list tools.

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

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

The description implies usage for bulk search and filtering by JQL, keys, or project, but it gives no explicit when-to-use guidance, no exclusions, and no named alternatives to compare against siblings. The context is clear enough to infer a list/search operation, but guidance is minimal.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds only that the result bundles Tests, Executions and folders — useful, but the output schema already conveys the shape, so incremental value is modest.

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

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

A single tight sentence that front-loads the verb and resource. No filler, though it is arguably terse given the tool's compositional behavior.

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

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

With a full input schema, a rich annotation set, and an output schema, the description only needs to frame scope — which it does by noting the plan is returned with its Tests, Executions and folders. Adequate for an agent 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%, and the schema documents all three parameters (fields, test_plan, include_test_status) with defaults and formats. 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?

States a specific verb ('Get') and resource ('Test Plan'), plus what the response composes (Tests, Test Executions, folder structure). This distinguishes it from the list-style xray_get_test_plans and the singular xray_get_test, though those siblings are not named explicitly.

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

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

There is no statement of when to use this tool versus xray_get_test_plans or xray_get_test_executions, nor any prerequisites. The agent must infer selection from the name and resource 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, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered structurally. The description's only behavioral addition is 'paginated', which the limit/start schema parameters already convey, so it adds little beyond the structured data.

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

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

One compact sentence with the resource and filter modes front-loaded and zero filler. It is appropriately sized, though the parenthetical '(paginated)' is somewhat redundant with the schema.

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

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

An output schema exists so return values need no explanation, and annotations cover safety. However, for a 7-parameter collection tool sitting among many similarly named get_* tools, the description does not explain how jql, project, and test_plans interact or when to prefer one filter over another, 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 each parameter (jql, project, test_plans, modified_since, fields, limit, start) is documented in the schema itself. The description adds no syntax or precedence detail beyond what the schema already provides, which is the baseline case.

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

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

States a specific verb (Search) and resource (Test Plans) with the filter dimensions (JQL, keys, project) and pagination. It is clearly a bulk/collection query, contrasting with the singular xray_get_test_plan, though it never names that sibling explicitly.

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

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

'Search' implies list/multi-result usage, which distinguishes it loosely from single-entity siblings, but there is no explicit when-to-use or when-not-to-use guidance and no mention of how it relates to xray_get_test_plan or the other get_* variants.

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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered and the description need not repeat it. The description adds the aggregation-by-status behavior, but says nothing about pagination, the API-call cost of max_tests, or how test_plan vs test_execution scope interact (both appear optional) — useful context that is left to the schema. Adequate with annotations carrying the load, hence a 3.

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: the action, the target resources, and the aggregation key are all stated before the optional example. Nothing could be trimmed 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?

An output schema exists, so return-value explanation is unnecessary, and annotations cover the safety profile. What remains slightly under-specified is whether test_plan and test_execution are mutually exclusive or combinable and what happens when neither is supplied (all five params optional). For a read-only counting tool this is largely 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% and every parameter has a substantive description (including the default ['FAILED'], the environment-with-test_plan coupling, and the one-call-per-100 cost), so the schema does the heavy lifting. The description only loosely implies that test_plan or test_execution is the scope selector, adding no format or exclusivity detail beyond the schema. 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 precise verb ('Count') and resource ('Tests of a Test Plan or Test Execution') with the aggregation dimension ('per status'), which unambiguously separates it from siblings like xray_get_tests (list) and xray_get_test_runs (raw runs). An agent can distinguish its role 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?

The phrase "e.g. to answer 'how far along is it?'" gives a clear motivating use case, implying progress/status reporting. However, it never states when to prefer this over xray_get_test_plans, xray_get_tests, or xray_get_test_runs, and offers no exclusions or prerequisites. Usage is implied rather than specified.

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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is fully covered structurally. The description adds only 'in full detail' as behavioral context; it says nothing about pagination, permission requirements, or behavior when the id is unknown.

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

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

A single front-loaded sentence with no filler; the detail enumeration and the two identification modes are packed efficiently with no wasted clauses.

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

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

With a full output schema and complete annotations, the description only needs to identify the resource and how to target it, both of which it does. Minor gap: it never clarifies that all three parameters are optional or that exactly one of the two modes must be supplied.

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

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

Schema coverage is 100% and the schema descriptions already state '(with test)' and '(with test_execution)'. The description restates the same id-or-(Test + Test Execution) pairing, adding no new syntax, format, or constraint detail. 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 (one test run) and enumerates the detail returned (steps, evidence, defects, examples, iterations). It implicitly contrasts with the plural xray_get_test_runs via 'one test run', but never names a sibling explicitly.

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

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

The description gives the two valid lookup modes (by id, or by Test + Test Execution), which is useful invocation context. However, it offers no guidance on when to prefer this over xray_get_test_runs or xray_get_test_execution, and no exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint and openWorldHint, so the safety profile is covered. The description adds the useful note that results are paginated, but says nothing about how pagination interacts with the limit/start params or about result ordering. Adequate but thin 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 zero filler, and the pagination caveat is appended compactly. Nothing is wasted, though it is arguably under-specified rather than maximally 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?

With an output schema present the description needn't explain return values, and the safety profile is in annotations. But for a 10-parameter search tool it omits how filters combine (AND vs OR), whether test_run_ids overrides other filters, and result ordering, leaving moderate 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% across all 10 parameters, so the schema already documents each filter, its format, and defaults. The description only echoes the filter axes and adds no syntax, combining semantics, or note that test_run_ids bypasses the other filters. Baseline 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?

Specific verb (Search) plus resource (test runs) and enumerates the five filter dimensions, so an agent can distinguish it from xray_get_test_run (single run) and xray_get_test_executions (different resource). It never names those siblings explicitly, so differentiation relies on inference.

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

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

There is no when-to-use guidance, no mention of when to prefer xray_get_test_run or xray_get_test_progress instead, and no statement about combining filters. Usage is only implied by the filter list.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered. The description adds only the pagination trait, and says nothing about the expandable payload behavior the tool offers.

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

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

A single front-loaded sentence with no filler; the search verb, the resource, the filter facets and the pagination caveat all appear in one 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?

For a 14-parameter read tool with an output schema and rich annotations, the description is minimally adequate: it covers the search entry points but gives no hint that results can be enriched via include_steps, include_definition, expand_call_tests or include_requirements, which are meaningful behavioral choices an agent faces here.

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 every parameter carries its own description (JQL example, page size/offset, field list default, folder path format), so the schema does the heavy lifting. The description's facet list largely restates schema content rather than adding syntax or interaction detail.

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 (Search) and resource (Xray Tests) plus the facets it can filter on, which cleanly separates it from the singular sibling xray_get_test and xray_get_expanded_test. It stops short of explicitly naming which sibling to use for a single-test lookup.

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 plural 'Search ... (paginated)' phrasing, which signals a list/multi-result retrieval, but the description never states when to prefer this over xray_get_test or xray_get_expanded_test, nor any prerequisite or exclusion.

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, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful retrieval context by stating that the returned Test Set includes the Tests it contains. It does not add details about permissions, rate limits, or output shape, but with rich annotations and an output schema, this is a reasonable contribution.

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, front-loaded sentence with no wasted words. It efficiently states the action and the key returned relationship. For a simple retrieval tool, this is appropriately sized.

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 retrieval tool with full schema coverage, rich annotations, and an output schema, the description is largely complete. It conveys the core return relationship and avoids redundant return-value documentation. The main gap is the absence of when-to-use guidance relative to similar getter siblings.

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

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

Schema description coverage is 100%, so both parameters are fully documented in the input schema. The description adds no parameter-level detail beyond what the schema already provides. Per the calibration rule, a baseline of 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific verb and resource: 'Get a Test Set with the Tests it contains.' It is clear that this retrieves a single Test Set including its contained Tests, distinguishing it implicitly from the list-oriented sibling xray_get_test_sets. However, it does not explicitly call out how it differs from siblings such as xray_get_test or xray_get_expanded_test.

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 provides no explicit guidance on when to use this tool versus alternatives. It does not mention the relevant siblings xray_get_test_sets, xray_get_test, or xray_get_expanded_test, nor does it state prerequisites or exclusions. Usage is only implied by the verb 'Get'.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds only 'paginated' as behavioral context, which is useful but minimal; it says nothing about defaults, result caps, or ordering.

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

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

A single short sentence with the verb and scoping constraints front-loaded and zero filler. 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?

An output schema exists and all parameters are documented in the schema, so the description need not explain return values. However, for a flexible multi-filter search tool with seven optional parameters, the absence of any usage context leaves a gap that the structured fields do not fill.

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

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

Schema description coverage is 100%, so all seven parameters (jql, project, test_sets, fields, modified_since, limit, start) are documented in the schema. The description merely names three of the filter concepts already covered, adding no syntax or format detail beyond the schema. 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 (Search) and resource (Test Sets) plus the three filter modes (JQL, keys, project) and notes pagination. This distinguishes it reasonably well from the singular xray_get_test_set sibling, though it never explicitly names an alternative.

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

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

There is no when-to-use or when-not-to-use guidance and no routing to siblings such as xray_get_test_set (single) or xray_get_tests. The agent must infer that this is the bulk/plural listing tool from the name and description 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, idempotentHint, and destructiveness=false, so the safety profile is covered. The description adds that results are paginated and that they feed version_id parameters, which is useful but brief. It doesn't explain pagination semantics or mention include_archived/include_definition behavior beyond what the schema says.

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

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

A single tight sentence in parentheses, front-loaded with the action and resource. No wasted words, though it is very terse and could carry slightly more structure without bloat.

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 needn't be explained, and annotations cover safety. The one notable gap is that pagination behavior isn't detailed, but for a read-only list tool with full schema coverage, the description is nearly 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 five parameters are fully documented in the schema. The description adds only the conceptual link that returned ids map to version_id parameters elsewhere, which is context rather than parameter syntax. 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 (List) and resource (versions of a Test), clearly distinguishable from sibling xray_get_test which returns the test itself. The parenthetical explaining the version_id purpose adds useful routing context, though it doesn't explicitly differentiate from other get tools.

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

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

The parenthetical hints at when to use it (to obtain version_id values for other tools), which is implicit guidance. But there's no explicit when-not-to-use or named alternative within the large sibling set.

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 the full safety profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false), so the description's burden is reduced. But it adds no behavioral context whatsoever: no auth/permission notes, no statement that arbitrary mutations can alter or remove data, and no error semantics for an escape-hatch 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?

A single front-loaded sentence with no filler or repetition. It is efficient, though the extreme terseness borders on under-specification for a generic mutation entry point.

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

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

With an output schema present and 100% param coverage, the essentials are covered by structured fields. For a generic GraphQL escape hatch, however, the description omits useful navigational context — e.g., that the schema can be discovered via xray_graphql_schema or that queries should use xray_graphql_query — leaving a gap for correct invocation.

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

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

Schema description coverage is 100% (both mutation and variables are documented inline), so the schema carries the burden and a 3 baseline applies. The description adds no format, syntax, or variable-binding guidance beyond what the schema already states.

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

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

States a specific verb+resource ("Run an Xray GraphQL mutation") and scopes it with "not covered by a dedicated tool," which meaningfully separates it from the many dedicated xray_create_*/update_*/delete_* siblings. It is clear but does not name the closest sibling (xray_graphql_query) it complements.

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?

"Not covered by a dedicated tool" implies a fallback condition, so the agent can infer when to reach for it rather than a purpose-built mutation tool. However, it names no explicit alternative, gives no exclusions, and never mentions the sibling xray_graphql_query or xray_graphql_schema, leaving selection to inference.

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