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

With no annotations provided, the description carries the full burden. It discloses that the file is provided as base64 content, which is also in the schema. However, it does not describe the outcome (e.g., whether the attachment is appended or replaces existing ones), any size limits, or required permissions. This is a moderate gap for a mutation tool.

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

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

The description is a single, well-structured sentence that front-loads the action and key details. It is concise without unnecessary words, making it easy to parse quickly.

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

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

Given the tool's simplicity and full parameter documentation in the schema, the description adequately explains the core operation. However, without an output schema or annotations, it does not mention return values, error handling, or behavioral constraints (e.g., file size limits). This leaves some gaps in completeness.

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 adds no new parameter information beyond what the schema provides. The list of artifact types in the description mirrors the enum in the schema, so no extra semantics are offered.

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 clearly states the action ('Attach a file') and the target resource ('to a qTest artifact'), with specific artifact types listed. This distinguishes it from sibling tools, which are mostly CRUD operations on artifacts.

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 when to use the tool (any time you need to attach a file to an artifact) and lists example artifact types, but it does not explicitly contrast it with alternatives like qtest_link_artifacts or qtest_add_test_step. No explicit 'when not to use' guidance is provided.

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

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It adds the semantic that 'each run represents one executable instance of a test case,' which clarifies the concept. However, it does not disclose potential side effects, permission requirements, irreversibility, or behavior with duplicate or invalid IDs, leaving notable gaps for a mutating 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 two succinct sentences. The first sentence states the core purpose, and the second adds a helpful pointer to a related tool. There is no fluff or repetition of schema details, making it highly concise and well-structured.

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

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

For a 3-parameter tool with no output schema, the description adequately explains what the tool does, what a run is, and how to acquire the necessary IDs. It does not mention return values or error behavior, but these are not required by the schema and the tool's simplicity makes the description nearly complete. The lack of an output schema means return information could be helpful, but this is a minor 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 coverage is 100% (all three parameters have descriptions). The description itself adds little beyond the schema: it mentions test case IDs and test suite but not projectId. Since the schema already defines each parameter clearly, a baseline of 3 is appropriate.

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

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

The description clearly states the action: 'Create test runs inside a test suite from a list of test case IDs.' This uses a specific verb with a resource and distinguishes itself from sibling tools like qtest_list_test_runs (listing) and qtest_create_test_suite (creating a suite). It also explains the run concept as 'an executable instance of a test case.'

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

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

The description gives clear context for when to use the tool: to create excutable runs from test case IDs. It also provides a useful prerequisite instruction: 'Use qtest_list_test_cases to find test case IDs.' However, it does not explicitly state when not to use this tool or mention alternative tools, so it falls short of a 5.

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

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

No annotations are provided, so the description carries the full burden. It discloses the core behavior ('append' indicates adding to existing steps without overwriting) and the content of a step (action + expected result). However, it does not mention return values, error conditions, or side effects beyond the append action. For a simple mutation, this is adequate but not rich.

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

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

A single, clear sentence that is front-loaded with the verb and resource. No wasted words or redundant information.

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

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

For a simple append operation, the description plus schema cover the essentials: what it does, the parameters, and the target. The absence of an output schema and annotation context is not a major gap given the simplicity. It could mention return value or failure modes, but the core context is 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?

The input schema provides 100% coverage with descriptions for all parameters. The description's mention of 'action + expected result' loosely maps to the 'description' and 'expected' parameters but adds no new meaning beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states 'Append a single test step (action + expected result) to an existing test case' with a specific verb ('append'), a specific resource ('test step'), and context ('existing test case'). This clearly differentiates it from sibling tools like create_test_case or update_test_case.

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

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

The phrase 'to an existing test case' provides clear context for when to use this tool: you already have a test case and want to add a step. It does not explicitly name alternatives or exclusions, but the context strongly implies the use case and distinguishes it from creating a test case 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?

The description clarifies the folder nature and root-vs-nested behavior, but it does not disclose potential side effects like duplicate creation or permission requirements. The only annotation is idempotentHint: false, which partially covers non-idempotency, but the description does not elaborate on error conditions or return values.

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

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

The description is two sentences with no redundant information. It front-loads the primary action and immediately provides the key usage distinction, making it highly efficient and scannable.

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 create tool with four well-documented parameters, the description covers the critical behavioral distinction (root vs nested) and the schema handles parameter details. It does not explain return values or failure modes, but given the straightforward nature and the annotation hint about non-idempotency, the information is adequate.

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

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

Schema description coverage is 100%, so all parameters are already documented. The description adds marginal value by explaining parentId's role in context of root vs nested modules, but this is already implied in the schema's property description. Thus, the baseline of 3 is appropriate.

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

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

The description clearly states 'Create a Test Design module (folder)' with a specific verb and resource, and it distinguishes this from sibling tools like qtest_update_module and qtest_list_modules. The parentId guidance further clarifies scope.

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 clear context on when to omit or supply parentId, distinguishing root creation from nested creation. It does not explicitly name alternatives or say when not to use the tool, but the context is sufficient for a simple create operation.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It only states the action and parameter hints but does not mention potential side effects, permissions, idempotency, error cases, or whether the created requirement is returned. This is a significant gap for a mutation tool.

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

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

The description is two sentences with zero waste. It front-loads the action and then immediately provides the key input guidance, making it easy to parse.

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

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

The tool is a straightforward create operation, but with no output schema and no annotations, the description should at least hint at the return value or behavior on success. It doesn't, and it also omits any mention of prerequisites beyond projectId/parentId. This leaves minor gaps, but the core usage is covered.

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's note about 'fieldId -> value' for custom fields is redundant with the schema's 'Custom field values keyed by numeric field id.' It adds no new meaning beyond the structured schema.

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

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

The description clearly states the action ('Create a requirement') and the target resource ('under a module'), and it distinguishes itself from sibling tools like qtest_update_requirement and qtest_list_requirements. The required parent context is specified, making the purpose unambiguous.

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

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

It provides clear context on how to use the tool: supply parentId for the containing module and optional custom fields. It does not explicitly mention when not to use it or name alternatives, but the sibling names (e.g., update, list) implicitly differentiate usage. This meets the 'clear context, no exclusions' bar.

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

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

With no annotations, the description carries the full transparency burden. It only restates input capabilities (ordered steps, custom fields) and gives no information about permissions, return values, idempotency, or side effects. This is a mutation tool, and the description lacks behavioral disclosure beyond 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?

The description is a single sentence that is front-loaded with the core action and includes only essential information. No filler or 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?

The tool has 7 parameters with nested objects and no output schema or annotations. The description covers the primary use case but omits what the tool returns, how to discover field IDs (e.g., via list_fields), and any required permissions or prerequisites beyond 'inside a module.' This is adequate but leaves notable gaps for a complex creation tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema by calling steps 'ordered' and explaining fields as a 'fieldId -> value map', which clarifies the structure and relationship of nested parameters.

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

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

The description uses a specific verb and resource: 'Create a test case inside a module.' It clearly distinguishes the tool from siblings like create_module or create_requirement by scoping creation to test cases within a module.

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 'inside a module' implies the prerequisite context of a module ID, and the capability to add steps/custom fields suggests appropriate scenarios. However, it does not explicitly mention alternatives such as update_test_case or add_test_step, nor does it state when not to use this tool.

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

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

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It does explain the core nesting behavior, but it omits other relevant aspects such as permissions, duplicate handling, the returned object, or error conditions. This is a minimally transparent create-tool description.

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

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

Two sentences, front-loaded with the main purpose and immediately followed by the key usage variant. No filler words or redundant details; every phrase 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?

The description covers the essential creation modes, and the schema fully documents parameters. However, with no output schema present, the description could reasonably mention what the API returns (e.g., the created test cycle object), and it does not address potential errors or prerequisites. This is adequate but not fully complete.

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

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

Schema coverage is 100%, so the schema already documents all parameters well. The description adds valuable relational guidance by explaining how parentId and parentType work together ('Omit parentId for a root cycle, or nest under a release or another cycle'). This goes beyond the individual schema descriptions.

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 clearly states the tool's action: 'Create a test cycle.' It also specifies the two primary usage modes (root vs. nested), distinguishing it clearly from sibling create tools like create_module or create_test_case.

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

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

The description provides explicit context on when to omit parentId (root cycle) versus when to supply parentId and parentType (nesting). It doesn't explicitly name alternatives, but the context is clear and sufficient for this artifact-specific create operation.

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

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

With no annotations, the description carries the responsibility for behavioral disclosure. It states the create action and the fact that test runs are added to suites, but does not mention side effects, permissions, or error conditions. This is adequate for a simple create operation but lacks depth.

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 concise sentences front-load the primary action and context. Every word adds value; no filler or repetition.

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

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

Given the complete schema descriptions and moderate complexity, the description is sufficient for understanding the tool's core purpose. It lacks an explicit statement of return value or error behavior, but those are not required given the input schema richness.

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

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

Schema coverage is 100%, so the baseline is 3. The description reinforces the role of parentId and parentType ('under a test cycle (or release)') and adds domain context about test runs, but it does not add new semantics beyond the schema's field descriptions.

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 clearly states the action ('Create a test suite') and specifies the resource and scope ('under a test cycle (or release)'). It distinguishes this from sibling create tools by identifying the parent context (test cycle or release).

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 clear context on when to use the tool: when needing to create a test suite under a cycle or release. It does not explicitly name alternatives or exclusions, but the parent-type constraint gives sufficient usage guidance.

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

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

The description is consistent with the readOnlyHint annotation and adds minor context by noting the user must be authenticated ('authenticated qTest user') and that it can verify connectivity. However, it does not disclose additional behavioral traits beyond that, so a mid-range score 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?

The description is two sentences, immediately stating the primary purpose and then a brief usage note. No wasted words.

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

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

Given the tool's simplicity (no parameters, read-only, no output schema), the description is adequate. It states what it returns and why it is useful. However, it does not detail the profile contents, which might be considered a slight gap, so a 4 is appropriate.

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 has no parameters, so the schema coverage is trivially complete. The description does not need to add parameter semantics; the baseline for zero-parameter tools is 4.

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 clearly states the tool returns the authenticated user's profile with a specific verb ('Return') and resource ('profile of the authenticated qTest user'). It distinguishes from sibling tools by focusing on the current user, not projects, requirements, or test artifacts.

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

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

It explicitly states a use case: 'Useful for verifying connectivity and permissions.' This provides clear context for when to invoke the tool. It does not mention alternatives, but given the sibling tools are all about other qTest entities, the usage is well-scoped.

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

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

The readOnlyHint annotation already signals that this is a safe read operation, so the description does not need to repeat that. The description adds the scoping detail "by its numeric ID," which is useful but not a behavioral trait. It does not disclose return format, possible errors, or authentication needs, but for a simple getter with a read-only annotation, this is acceptable.

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, well-structured sentence with no wasted words. It front-loads the action ("Fetch a single qTest project") and then specifies the key parameter ("by its numeric ID"). Every part 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 tool with one integer parameter, a read-only annotation, and no output schema, the description is nearly complete. It states what it does and what input is required. It could optionally mention that the result is the full project object or that a missing ID would cause an error, but these are not critical given the tool's simplicity.

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 parameter description "Numeric project ID" already fully defines the single parameter. The tool description repeats this by saying "by its numeric ID," adding no new meaning beyond what the schema provides. Baseline of 3 is appropriate.

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

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

The description uses the specific verb "Fetch" and clearly identifies the resource as "a single qTest project," with the qualifier "by its numeric ID." This immediately distinguishes it from sibling tools like qtest_list_projects (which lists multiple projects) and other get_* tools for different resource types.

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 context: when you need one specific project and know its numeric ID. However, it does not explicitly mention alternatives (e.g., qtest_list_projects for listing all projects) or provide exclusions. The "single" vs. "list" contrast is implicit but not directly 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?

The annotation declares readOnlyHint=true, and the description's 'Fetch' is consistent. However, the description adds no behavioral context beyond what is already evident from the name and annotation—e.g., no mention of error handling, authorization, or response shape. With annotations present, the description is expected to add some context, but it does not.

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

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

The description is a single, clear sentence with no filler words. It is appropriately sized for the simplicity of the tool and front-loads the action.

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

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

Given the simple nature of the tool (a read operation with two fully described parameters and a readOnlyHint annotation), the description is adequate. It lacks explicit return-value details, but no output schema exists, and for a 'fetch by ID' pattern the behavior is generally predictable. The tool is well-contextualized by its name and 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 (projectId and requirementId) described in the schema. The description only paraphrases 'by ID' but does not add new semantic detail. The baseline of 3 applies because the schema covers the parameter meanings fully.

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

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

The description uses a specific verb ('Fetch') and clearly identifies the resource ('a single requirement') and the key selector ('by ID'). This distinguishes it from sibling tools like qtest_list_requirements (list multiple) and qtest_get_requirement_coverage (coverage-specific).

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 the use case: retrieve one requirement when you have its ID. However, it does not explicitly mention alternatives or when-not-to-use, such as using qtest_list_requirements for listing or qtest_get_requirement_coverage for coverage. Since the usage is implied by the wording, it meets the 'implied usage' bar.

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

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

The description complements the readOnlyHint annotation by clarifying that the tool returns a list of test cases currently linked to the requirement, adding the 'currently linked' context which implies a real-time view. It does not disclose additional behaviors like pagination, but annotations already establish it is a safe read operation, and the description aligns with that.

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, focused sentence with no extraneous words. It front-loads the main action ('List') and directly states the scope, capturing the tool's purpose efficiently.

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

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

The tool is simple (2 parameters, no output schema) and the description is sufficient to understand its function. It does not mention return value format, but the purpose is clear and annotations cover safety. The context is complete enough for an AI agent to select and invoke the tool correctly, though a note about the response being an array of test cases would have pushed it to 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?

The input schema already provides descriptions for both parameters ('Numeric project ID.' and 'Requirement ID.'), achieving 100% coverage. The description adds no information about the parameters themselves, so it relies on the schema. Per the rubric, high schema coverage yields a baseline of 3, which is appropriate.

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

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

The description uses a specific verb ('List') and resource ('test cases currently linked to (covering) a requirement'), clearly distinguishing it from sibling tools like qtest_get_requirement (which fetches requirement details) and qtest_get_traceability_matrix (which provides a broader coverage view). This unambiguously states what the tool 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?

The description implies use when you need to see which test cases cover a specific requirement, based on 'currently linked to (covering) a requirement.' It does not explicitly mention alternatives or exclusions, but the context is clear, especially given the required requirementId parameter. Sibling tools like qtest_get_traceability_matrix are not referenced, but the specific phrasing provides sufficient guidance.

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

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

With readOnlyHint=true provided by annotations, the description does not need to restate safety. It adds value by indicating the response includes test steps and properties, which is useful given no output schema. However, it does not disclose potential error handling (e.g., 404) or any other behavioral traits beyond the basic content.

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 that is front-loaded with the action and resource. It includes a useful qualifier ('including its test steps and properties') without any redundant or unnecessary words.

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

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

For a simple get tool with two documented parameters and a read-only annotation, the description is sufficiently complete. It communicates the scope ('single test case by ID') and the content of the response ('test steps and properties'), covering the main usage context. Minor gaps like error handling or response format are not critical given the tool's simplicity.

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 schema already provides full descriptions for both parameters ('Numeric project ID.', 'Test case ID.'), so the description adds little beyond the schema. It reinforces 'by ID' which aligns with testCaseId, but no additional semantic meaning is provided. Baseline 3 is appropriate given 100% schema coverage.

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

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

The description clearly states the action ('Fetch a single test case by ID') with a specific verb and resource. It distinguishes from siblings like qtest_list_test_cases by specifying 'single' and 'by ID', and mentions the included content ('test steps and properties').

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

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

The description implies usage: it is for retrieving one test case when the ID is known. However, it does not explicitly mention when to use an alternative like qtest_list_test_cases for multiple cases, nor does it provide exclusions or prerequisites. The context is clear but not fully explicit.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds that the result includes 'latest status,' which is useful return-value context, but it does not disclose error conditions, pagination, or whether the status is computed fresh. This is adequate but not rich behavioral detail.

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, concise sentence that is front-loaded with the action and resource. Every word earns its place, and there is no redundant or filler content.

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

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

For a simple get-by-ID tool with readOnlyHint and two well-documented parameters, the description is nearly sufficient. It states the return includes the latest status, and the absence of an output schema is mitigated by this hint. It could be more explicit about what fields are returned, but overall it is complete enough for an agent.

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 input schema has 100% parameter description coverage: both projectId and testRunId are described with clear types. The description adds no additional parameter meaning beyond what the schema provides, so the baseline score of 3 applies.

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

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

The description says 'Fetch a single test run by ID, including its latest status,' which uses a specific verb ('Fetch') and clearly identifies the resource (a single test run by ID). It distinguishes itself from sibling tools like qtest_list_test_runs by focusing on a single item rather than a list.

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

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

The description implies the tool is for retrieving one specific test run when you have its ID, contrasting with qtest_list_test_runs for listing multiple runs. It does not explicitly name alternatives or state when not to use it, but the context is clear enough for an agent to decide.

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

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

The annotations already declare readOnlyHint=true, so the description doesn't need to restate that. The description adds some context about the report's content but does not disclose details like pagination behavior or response format. This is a slight improvement over no additional behavior info, matching the baseline for read-only tools with 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?

The description is two sentences, with the action and resource front-loaded. Every word earns its place, efficiently conveying purpose and context without unnecessary filler.

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

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

For a read-only retrieval tool with good schema coverage and no output schema, this description is complete enough. It explains the purpose and the content of the returned matrix, and the 'coverage audits' hint is useful. While it doesn't detail pagination or filtering, those are well covered by the schema, so no major gaps remain.

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?

All parameters are already described in the JSON schema with 100% coverage. The description adds no additional parameter-level semantics, so it provides no value beyond the schema. Baseline 3 is appropriate when schema is the primary source of parameter information.

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 clearly states the tool's function with a specific verb ('Retrieve') and resource ('requirement traceability matrix report'), and elaborates on the content ('requirements with their covering test cases'). This distinguishes it from sibling tools that are named differently (e.g., 'get_requirement_coverage' might focus on individual coverage rather than the entire matrix report).

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 a clear usage context: 'Useful for coverage audits.' This tells the agent when to use the tool, though it does not explicitly mention alternatives or exclusions. That is sufficient for a basic use case.

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

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

With no annotations, the description carries significant burden for disclosing behavior. It explains the source-to-target link direction but omits the unlink capability (unlink parameter), side effects, permissions, or reversibility. This is a notable gap for a mutation tool.

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

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

The description is four sentences, each contributing meaning: generic purpose, link mechanism, example, and supported types. No fluff or 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?

The description covers the core linking operation and supported types, but lacks mention of unlink behavior, return values, or edge cases. Given there is no output schema and no annotations, more detail would help the agent use the tool 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?

The schema descriptions already cover all six parameters at 100%. The description adds value by clarifying the relationship between objectType/objectId and linkType/targetIds, but it does not elaborate on the unlink parameter or other nuances, so baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a generic object-linking mechanism between qTest artifact types, with a concrete example and a list of supported types. It distinguishes itself from specific sibling tools like qtest_link_test_cases_to_requirement by emphasizing its generic nature.

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 use for arbitrary artifact pairings not covered by specialized linking tools, and the example provides context. However, it does not explicitly state when to prefer this tool over the specific link/unlink siblings or mention 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?

With no annotations, the description must carry the burden. It describes the logical effect ('marks the listed test cases as covering the requirement') but does not disclose side effects, idempotency, required permissions, reversibility, or response behavior. This is adequate but leaves notable gaps for a mutation tool.

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

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

The description is two sentences, front-loaded with the main purpose, and contains no filler. Every sentence adds useful information: the action and the ID guidance.

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 three simple parameters and no output schema, the description adequately explains the purpose, logical effect, and parameter sourcing. It could be more complete by describing expected outcomes or error conditions, but for this simple linking action, it covers the essentials.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying that IDs are numeric and referencing qtest_list_test_cases as a source for testCaseIds. This goes beyond the schema descriptions.

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 clearly states the action ('Create coverage links') and the resources involved ('requirement and one or more test cases'). It positions this as 'the primary traceability action', which distinguishes it from generic linking tools like qtest_link_artifacts, though it does not explicitly name that 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?

The description gives clear usage context by stating this is the primary traceability action and marks test cases as covering a requirement. It also instructs to use qtest_list_test_cases to find numeric IDs, which is practical guidance. However, it does not explicitly exclude alternatives or describe when not to use it.

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

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

The annotations already declare readOnlyHint=true, which indicates a safe read operation. The description adds value by specifying the return content (numeric IDs and allowed values) and that it lists both system and custom fields, giving more behavioral context than the annotation 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?

The description is two sentences, front-loaded with the action and resource, then a direct usage tip. Every word earns its place; no filler or repetition of schema details.

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

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

With no output schema, the description appropriately mentions that the result includes numeric IDs and allowed values, giving the agent a sense of what to expect. The tool has only two simple parameters, and the description covers its purpose and usage well, though it could mention pagination or error behavior for full completeness.

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 input schema provides 100% coverage for both parameters (projectId and objectType), so the baseline is 3. The description does not add additional parameter-level detail beyond what the schema already states, but it does clarify the purpose of the returned field IDs.

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

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

The description uses a specific verb ('List') with a clear resource ('system and custom fields for an artifact type in a project') and adds useful detail about the output (numeric IDs and allowed values). This distinguishes it from sibling tools that operate on specific artifact types like test cases or requirements.

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 explicitly states when to use the tool: 'Use this to discover field IDs needed by the 'fields' parameter on create/update tools.' This gives clear context, though it does not mention when not to use it or name alternative tools.

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

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

The readOnlyHint annotation already signals a safe read operation. The description adds valuable behavioral details: the default root behavior, parent-child traversal, and case-insensitive substring filtering. No contradictions.

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

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

Three concise sentences, front-loaded with the core purpose, then expanding on parameter behavior. Every sentence earns its place with no fluff or repetition.

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

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

For a simple read-only listing tool with three parameters and no output schema, the description is largely complete. It explains the main behaviors and filtering. It doesn't describe the response format, but that risk is mitigated by the tool's straightforward nature.

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

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

Schema coverage is 100%, but the description enriches parameter semantics by explaining that omitting parentId returns root modules and that search is a case-insensitive substring match. This goes beyond the schema's basic field descriptions.

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 clearly states the tool lists Test Design modules (folders), using a specific verb and resource. It also explains the variations for root vs. child modules, distinguishing it from other listing tools like test cases or projects.

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 clear usage context: omit parentId for root modules, provide parentId for children, and use search for filtering. While it doesn't explicitly name alternatives, the mode-based guidance is sufficient for a listing tool with simple pagination-free behavior.

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

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

With readOnlyHint=true already declared, the description adds useful context by specifying return fields (id, name, status) and the authentication requirement ('authenticated user can access'). This goes beyond the annotation without contradicting it.

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

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

The description is two sentences, front-loaded with the action, and every word contributes value. It states the purpose, return fields, and usage guidance without redundancy.

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

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

For a simple list tool with one optional parameter and no output schema, the description fully covers the essential aspects: what it lists, what it returns, and how it should be used first. No gaps are evident.

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 input schema fully describes the only parameter 'assignedOnly' with a clear Boolean description, so the schema provides 100% coverage. The tool description does not add extra parameter semantics, which is acceptable given the high schema coverage.

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

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

Description clearly states the tool lists all qTest projects the authenticated user can access, with a specific verb ('List') and resource ('qTest projects'). It distinguishes itself from sibling tools like qtest_get_project by focusing on listing all accessible projects.

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 clear context by stating 'Use this first to discover the projectId required by most other tools,' giving an explicit when-to-use instruction. It does not explicitly name alternative tools, but the guidance is strong enough to indicate this is the initial discovery tool.

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

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

The annotation readOnlyHint: true already indicates a safe read operation. The description adds valuable behavioral context by noting that filtering is 'client-side', which implies a distinct mechanism (e.g., results may be fetched and filtered locally) and clarifies the scoping behavior with parentId. This goes beyond the annotation without contradicting it.

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

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

The description is two sentences, front-loaded with the primary action, and contains no filler words. It efficiently covers the tool's scope and key features without redundancy.

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

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

For a simple list operation with a fully described schema and a read-only annotation, the description covers the essential aspects: what it lists, optional scoping, and filtering. It lacks an output schema but that is not necessary for a list tool. The description is complete enough for an agent to select and 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?

The input schema has 100% description coverage, so the baseline is 3. The description adds semantic nuance by tying parentId to 'parent module' and search to 'name substring' and 'client-side' filtering, which slightly deepens understanding beyond the schema's property descriptions. This justifies a 4.

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

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

The description uses a specific verb ('List') with a clear resource ('requirements') and adds scoping context ('optionally scoped to a parent module') and filtering behavior ('client-side filtering by name substring'). This distinguishes it clearly from sibling tools like qtest_get_requirement (which retrieves a single requirement) and qtest_create_requirement/update_requirement.

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 clear usage context: listing requirements in a project, with optional module scoping and name-substring filtering. It does not explicitly mention alternatives or exclusions, but the context is sufficient for an agent to decide when to use this tool versus others like qtest_get_requirement or qtest_search.

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

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

The readOnlyHint annotation already declares this is a safe read operation. The description adds the client-side filtering behavior by name substring, which is useful. However, it does not disclose other behavioral aspects like pagination limits (though maxItems is in schema) or response format. This is acceptable given the annotation coverage, but not rich.

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

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

The description is two sentences with no wasted words. The first sentence states the primary purpose, and the second adds the optional scoping and filtering details. It is front-loaded and easily scannable.

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 list tool with annotations and full schema coverage, the description is largely complete. It explains the operation, optional scoping, and filtering. However, it does not specify the return format (e.g., summary vs full details), but this is implied by the tool name and the presence of get_test_case for detailed retrieval. Overall, it is sufficiently complete for an agent to invoke effectively.

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 parameters (search, maxItems, parentId, projectId) having descriptions. The description mentions parentId scoping and name substring filtering, but these are already covered in the schema property descriptions. The description adds no new semantic value beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool lists test cases in a project, with an optional module scope via parentId. It distinguishes itself from siblings like get_test_case (which retrieves a single test case) and list_modules (which lists modules). The verb 'List' plus resource 'test cases' is specific and 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 provides clear context for when to use this tool: for listing test cases, optionally scoped to a module. It does not explicitly mention alternatives or exclusions, but the sibling names make it obvious that get_test_case is for single retrieval and list_modules is for modules. This counts as clear context without explicit exclusions.

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

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

The readOnlyHint annotation already declares this as safe. The description adds value by disclosing the hierarchy traversal behavior (root vs children) and name filtering. It doesn't mention pagination or response format, but these are not critical for a simple list operation.

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

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

Three sentences, front-loaded with the core action, no redundancy. Every sentence adds a specific detail: root behavior, child behavior, and name filtering.

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 tool with no output schema, the description adequately covers the key context: hierarchy and filtering. It doesn't discuss pagination but that's a minor gap for a list operation with good annotations.

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 parameters. The description adds minimal extra meaning beyond the schema; it restates parentId's behavior and the parentType matching relationship, but this is already implied by the parameter descriptions.

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 clearly identifies the tool as listing test cycles. It specifies behavior with and without parentId, distinguishing root-level and child cycles, and mentions name filtering. This separates it from other list tools like qtest_list_test_cases and qtest_list_test_suites.

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

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

Provides explicit guidance on when to use root vs child listing: 'With no parentId, returns root-level cycles. Provide parentId (and the matching parentType) to list children.' It also notes name filtering, but doesn't explicitly mention alternatives 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=true, so the read-only nature is covered. The description adds the parent-scoping constraint but does not disclose return format, pagination, or that parentType also supports 'release' and 'root' (it only mentions suite and cycle). This is a minor transparency gap.

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

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

The description is two concise sentences with no fluff. The main action is front-loaded, and the parameter guidance is direct.

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 list tool with full schema coverage, the description is adequate but omits the full list of parentType enum values and the default behavior. It also gives no indication of the return structure, though the absence of an output schema makes this less critical.

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 each parameter already described. The description's instruction to 'Provide parentId and parentType' is redundant and slightly misleading because parentType is optional in the schema (default test-suite). It adds little meaning beyond the schema.

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

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

The description uses the specific verb 'List' with resource 'test runs' and scope 'under a parent', clearly distinguishing it from singular get_test_run or add_test_runs. It also names the required context (parent suite/cycle).

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 clearly implies when to use this tool (to list test runs under a parent) by instructing to provide parentId and parentType. It does not explicitly name alternatives like qtest_get_test_run, but the context is evident from the sibling tool names.

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

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

The readOnlyHint annotation already signals a safe read operation. The description adds clarifying context about the parent relationship (cycle or release), which helps the agent understand the scoping. No contradictions and no hidden destructive behavior.

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

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

Two concise, front-loaded sentences deliver the necessary information without fluff. Every phrase earns its place, making it easy for an agent to parse quickly.

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 list operation with good schema coverage and annotations, the description is adequate. It clearly communicates the core operation and required parent context. Minor gaps like not mentioning the parentType default or required projectId are covered by the schema.

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

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

Schema description coverage is 100%, and the description's 'Provide parentId and parentType' merely echoes the schema. No additional syntax, formatting, or relationship details beyond what the schema already documents, so baseline 3 is appropriate.

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

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

The description clearly states the tool lists test suites, scoped under a test cycle or release. This specific verb+resource combination distinguishes it from sibling tools like list_test_cases and list_test_cycles.

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 context: listing test suites requires a parentId and parentType. However, it does not explicitly compare against alternative tools (e.g., list_test_cycles) or mention when not to use this tool, so it falls short of clear guidance.

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

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

Annotations already declare readOnlyHint=true, establishing the safety profile. The description adds useful context with QQL syntax examples and the requirement to specify artifact type, but does not disclose additional behavioral traits such as result formatting or pagination beyond what the schema already provides for maxItems and 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?

The description is a single, front-loaded sentence with three illustrative examples. Every clause serves a purpose, with no redundant or filler content, making it highly concise and well-structured.

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?

Combined with a fully described schema and read-only annotation, the description covers the essential usage, parameter requirements, and query syntax. It lacks an explicit description of the return shape, but no output schema exists, and for a search tool the absence is acceptable. Overall, the description is sufficiently complete for an agent to invoke the tool 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%, with each parameter clearly explained. The description reiterates the objectType requirement and gives examples for the query parameter, but adds minimal semantic value beyond the schema's own parameter descriptions.

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 clearly states the tool's action ('Search'), resource ('a project's artifacts'), and mechanism ('using qTest Query Language (QQL)'). It distinguishes from sibling listing tools (e.g., qtest_list_test_cases) by emphasizing query-based search across multiple artifact types.

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 example queries and instructs to 'Specify the artifact type to search,' implying the use case for flexible QQL queries. However, it does not explicitly contrast with sibling list tools or state when to prefer search over simple listing, leaving the comparative guidance implied rather than explicit.

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

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

No annotations are provided, so the description carries the full burden. It discloses accepted status examples and optional fields but fails to mention side effects, return values, error behavior, or whether this creates a new log entry or overwrites an existing one. For a write operation, this is a significant gap.

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

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

Two sentences, front-loaded with the core action, and no redundant information. Every phrase contributes (statuses, optional fields, ISO 8601).

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 description covers the essential purpose and parameters, but given no output schema and no annotations, it is incomplete regarding return value and side effects. An agent would not know what to expect after submission (e.g., a log ID, success indicator, or errors).

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by giving status examples and clarifying optionality of note/timestamps, but it does not elaborate on projectId or testRunId beyond their schema descriptions.

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

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

The description uses a specific verb ('Record') and resource ('execution result (test log)') with a target ('against a test run'). It clearly distinguishes this from sibling tools like qtest_get_test_run or qtest_list_test_runs.

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 clearly conveys the context for use: logging a result against an existing test run. It does not explicitly mention alternatives or exclusions, but the purpose is unambiguous given the tool name and 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?

No annotations are provided, so the description carries the full burden for behavioral disclosure. It states that links are removed, but does not mention potential side effects, error behavior if links do not exist, required permissions, or reversibility. The phrasing adds little beyond what the name already implies.

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

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

The description is a single, concise sentence with no redundant wording. It is easy to scan and directly communicates the core action, making every word earn 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?

This is a mutation tool with no annotations and no output schema. The description covers only the basic action, omitting details about what happens to the requirement and test cases, whether the operation is idempotent, or what the response contains. For a simple tool, one might argue it suffices, but more context is expected given the lack of annotations and output schema.

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

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

The input schema already provides clear descriptions for all three required parameters, achieving 100% coverage. The description does not add additional parameter semantics, but with full schema coverage, the baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Remove coverage links') and the target ('between a requirement and one or more test cases'). It is distinct from related sibling tools like qtest_link_test_cases_to_requirement and get/list operations, unambiguously indicating an unlinking action.

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 guidance on when to use this tool versus alternatives such as qtest_link_test_cases_to_requirement or qtest_get_requirement_coverage. There are no stated prerequisites, use cases, or exclusions, leaving the agent to infer usage solely from the tool's 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?

No annotations are provided, so the description carries the full burden of disclosing behavior. It only states what can be updated and the custom fields map format; it does not mention permissions, partial-update semantics, effect on child artifacts, or response behavior. For a mutation tool, this is a significant transparency gap.

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

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

The description is two concise sentences with no filler or redundancy. The key action and object are front-loaded, and the fields map instruction is a valuable addition in the second sentence.

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

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

The tool is simple and all parameters are documented, so invocation is feasible. However, with no output schema and no behavioral details, the description leaves gaps about what happens if no updatable fields are supplied, whether partial updates are allowed, and what the response contains. It is adequate but lacks richer operational context.

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

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

Schema description coverage is 100%, so all parameters are already documented. The description adds a brief clarification about providing fields as a map of fieldId -> value, but this largely reiterates the existing schema description ('Custom field values keyed by numeric field id'). No substantial new meaning is added.

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

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

The description uses a specific verb ('Update') and identifies the resource ('a module'), explicitly listing the updatable attributes: name, description, and custom fields. This clearly distinguishes it from sibling tools like qtest_create_module or qtest_update_requirement.

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 it is used to modify an existing module, but it does not explicitly state when to use this tool over qtest_create_module or other update tools. There are no exclusions or alternative comparisons, so usage context is only implied.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It mentions the optional move-to-parent-module behavior, but does not clarify whether updates are partial or full replacement, permission requirements, reversibility, or side effects. This is a significant gap for a mutation tool.

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

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

Two sentences, front-loaded with the primary action and fields, followed by the optional move behavior. No extraneous content; 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?

For a six-parameter update tool with no annotations or output schema, the description covers the main purpose but omits important behavioral details such as update semantics and any side effects. It is adequate for basic invocation but not fully 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 baseline is 3. The description adds minimal extra meaning by grouping name/description/custom fields and clarifying parentId's optional move, but it does not provide information beyond the schema's own parameter descriptions.

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 clearly identifies the verb 'Update' and resource 'requirement', and specifies the fields (name, description, custom fields) and optional parent module move. This distinguishes it from sibling tools like qtest_get_requirement (read) and qtest_create_requirement (create).

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 (when you need to modify an existing requirement) but does not explicitly state when to use it versus creating a requirement or updating a module, nor does it mention exclusions or prerequisites. There is no differentiation from alternatives beyond the inherent purpose.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds a valuable behavioral trait by stating 'Creates a new version in qTest,' which is a non-obvious side effect not evident from the schema. However, it does not mention other behaviors such as whether unspecified fields are left unchanged or whether permissions are required.

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

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

The description is two sentences long and front-loaded with the primary purpose, followed by a key behavioral note. Every word earns its place; no filler or redundant 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?

The description covers the main purpose, the updatable fields, and a significant side effect (versioning). It lacks mention of what happens to unspecified fields or the return value, and there is no output schema to fill that gap. However, given the tool's scope and the strong schema coverage, it is reasonably 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?

The input schema has 100% description coverage, so the baseline is 3. The description adds no new parameter-level semantics beyond the schema; it only repeats field names. No explanations of parameter interactions or required identifiers are added beyond what the schema already provides.

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

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

The description states a specific verb ('Update') and resource ('a test case'), and explicitly lists the attributes that can be changed (name, description, precondition, custom fields). This clearly distinguishes it from sibling tools like qtest_create_test_case or qtest_get_test_case.

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

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

The description implies the tool is used when updating an existing test case, but it does not explicitly state when to use it versus alternatives, nor does it mention any exclusions or prerequisites. For example, it doesn't say 'use this instead of qtest_create_test_case if the test case already exists'.

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