TestRail MCP Server

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

The annotations only indicate a non-read-only, non-idempotent, non-destructive operation, so the description adds meaningful behavioral context by disclosing that directories are automatically zipped and uploads are capped at 256MB. It stops short of describing error handling or response details, but the annotation coverage lowers that burden.

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 three tight sentences with no filler: the core operation first, then directory behavior, then the size constraint. Every sentence earns its place.

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

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

For a simple three-parameter mutation with full schema coverage, the description is reasonably complete: it states the operation, entity types, directory handling, and upload limit. It is only mildly incomplete by not addressing the overlapping sibling tool or the expected return value, though no output schema exists.

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 documents all three parameters at 100% coverage, including the entity_type enum and the fact that directories are zipped. The description reinforces the directory behavior and size limit but adds no new parameter-level semantics beyond what the schema provides.

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

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

The description clearly states a specific action ('Add an attachment') and names the target resources (test case, test run, test result), so an agent understands the core purpose. However, it does not explicitly differentiate itself from the sibling add_attachment_to_run, which overlaps for run attachments.

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

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

The description gives no explicit guidance on when to use this tool versus alternatives like add_attachment_to_run. The directory-zipping and 256MB notes are useful constraints, but they do not help an agent select the correct tool among siblings.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, signaling a non-destructive write operation. The description adds the prerequisite about field names but doesn't describe side effects, success/failure behavior, or response format. The schema's fields parameter description provides additional behavioral details (e.g., server merges entries, unknown fields error), but that is part of the schema, not the description text.

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: the first states the purpose, the second provides a critical prerequisite. It is front-loaded, concise, and every word earns its place. 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?

Given the tool has no output schema and the annotations already cover safety traits, the description plus schema fully cover what an agent needs: purpose, required parameters, and a prerequisite. The only minor gap is that it doesn't describe what the response looks like (e.g., the created case object), but for a create operation this is often implicit. Overall, it is sufficiently complete for a well-scoped tool.

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

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

Schema coverage is 100%, and the schema descriptions for each parameter are detailed, especially for 'fields' with examples and error conditions. The description text adds nothing beyond the schema; it only mentions the prerequisite of get_case_fields. Since the schema carries the semantic weight, a 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 states a specific verb ('Create') and resource ('a new test case in TestRail'), making the purpose unambiguous. It also implicitly distinguishes from update_case by using 'create' and mentions a prerequisite tied to get_case_fields, which adds context.

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 notes that the operation requires knowing valid field names from get_case_fields, giving a clear prerequisite. It doesn't explicitly contrast with alternatives like update_case, but the create vs. update distinction is obvious from the name. Overall, it gives useful context for when 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?

Annotations already indicate the tool is a write operation (readOnlyHint=false) and not destructive. The description adds no additional behavioral context, such as whether results are appended or replaced, or any side effects.

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 communicates the core function without any wasted words.

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

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

For a simple add operation, the description combined with the full schema coverage and annotations is adequate. It lacks explicit guidance on usage context, but the essentials are covered. A more detailed description could mention that results are appended to an existing run.

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 descriptions cover all parameters (100%), providing detailed information for run_id and each field in the results array. The description itself adds no extra parameter semantics beyond what the schema already includes.

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 (add) and the resource (test results to a test run). It is specific but does not explicitly distinguish from the sibling tool 'add_results_for_cases'.

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

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

No guidance on when to use this tool versus alternatives such as 'add_results_for_cases' or 'get_results'. The description lacks context about prerequisites or use cases.

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

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

Annotations already cover readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the description does not need to repeat those. The description adds minimal behavioral context beyond confirming it's a write operation ('Add'), but does not disclose side effects like partial failures or validation behavior. It stays consistent 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 a single, front-loaded sentence that states the core functionality and key differentiator. No filler or redundant wording, earning a top score for conciseness.

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

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

For a mutation tool with full schema coverage and clear annotations, the description is sufficiently complete. It identifies the action, target, and unique usage caveat. While it omits details about the response format, the absence of an output schema and the presence of thorough parameter docs make this 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%, with each parameter (run_id, case_id, status_id, comment, defects) fully described including where to source IDs. The description itself adds no additional parameter-level meaning beyond what the schema already provides, so a 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 tool's purpose with a specific verb ('Add'), resource ('test results to a test run'), and a distinguishing mechanism ('using case IDs instead of test IDs'). This effectively differentiates it from sibling tools like add_results, which likely uses test IDs.

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 'using case IDs instead of test IDs' provides clear context for when to use this tool versus alternatives, implying that add_results is for test IDs. However, it does not explicitly name the alternative tool, stopping short of a full when/when-not specification.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds the useful detail that the response includes custom fields, which is not in the annotations or schema. This extra context about the return payload justifies a score above baseline.

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 that front-loads the purpose and the key detail about custom fields. There is no wasted wording 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?

For a simple read tool with one parameter and strong annotations, the description is mostly complete. It explains what is retrieved (including custom fields), though it does not exhaustively list all return fields. The absence of an output schema means a bit more detail could help, but the core guidance is sufficient.

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

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

The schema fully documents the single parameter (case_id) with a description and example format. The tool description adds no additional information about the parameter, so the baseline score of 3 applies given the 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 states a specific action (get) and resource (test case), and distinguishes itself from sibling tools like get_cases (plural) and get_case_fields by noting it returns the case's custom fields. This clearly identifies 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 usage for retrieving a single test case's details, but provides no explicit guidance on when to use this over alternatives like get_tests or get_cases. The context is inferred from the name and sibling list rather than stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context by explaining that omitting project_id returns all fields across all projects, making the scope transparent. It also discloses the return format ('types and options for dropdown fields'), going beyond the annotations.

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

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

Three concise sentences: purpose, parameter guidance, and return info. Front-loaded with the main action, no redundant phrasing, and every sentence contributes value. Structurally excellent.

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 optional parameter, high-quality annotations, and no output schema, the description covers the necessary context: what it returns, how to scope it, and the behavior when omitted. There are no significant gaps for the complexity level.

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

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

The schema already provides a detailed description of project_id, covering both the normal use case and the fallback behavior. The tool description mostly reiterates this information without adding new semantic details about parameter formatting, constraints, or usage beyond the schema coverage, which is 100%.

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: 'Get the field schema for test cases for a specific project.' It specifies the resource (field schema), the scope (test cases, project), and the return content (fields with types and options). This distinguishes it from sibling tools like get_cases or get_templates which manage test data rather than schemas.

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 guidance: 'You should normally provide project_id to get fields applicable to your project' and notes that omitting it is 'rarely what you want.' While it doesn't name alternative tools, it clearly instructs when to use the parameter and when not, which is strong usage direction for a simple 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: the `where` filter is client-side ('filters after fetching all cases'), implying inefficiency for large datasets, and `output_file` is recommended to avoid context limits. This goes beyond the annotations and informs the agent of performance trade-offs.

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 concise and front-loaded with the primary purpose. It uses two clear sentences plus a return statement, avoiding redundancy with schema details. Every sentence adds actionable information (scope, filtering, output format) without 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?

Given the tool's complexity (7 parameters, nested objects), the description covers essential aspects: what it returns, filtering options, and large-data handling. It does not explicitly mention suite_id requirements or response structure beyond IDs/titles, but these are documented in the schema. The lack of an output schema is mitigated by the clear return statement.

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 meaning by distinguishing `where` (client-side, after fetch) from `filter` (API-side, more efficient) and provides examples for both. It also clarifies the output_file use case, adding value beyond the schema's 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 retrieves all test cases for a project, with filtering options. It distinguishes itself from siblings like `get_case` (singular) and `get_tests` by emphasizing bulk retrieval and flexible filters. The verb 'get' and resource 'cases' are 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 implies usage for fetching cases with filtering and provides pointers to associated tools (query_section, query_suite, get_case_fields). It does not explicitly state when not to use this tool, but the examples and mentions of client-side vs API-side filters give practical guidance. It lacks explicit contrasts with alternatives, but the context is clear enough for typical scenarios.

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 annotations already declaring readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description adds behavioral value by specifying that the operation returns 'all' configuration groups and configurations, implying no filtering. It does not mention pagination or return format, but the safety profile is fully covered by 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 a single sentence that front-loads the action and resource, with no unnecessary words. Every word contributes to the meaning.

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

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

For a simple one-parameter read tool with strong annotations, the description is adequately complete: resource, scope, and all-encompassing behavior are stated. No output schema exists, but the description makes the primary return concept clear without needing to list result fields.

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

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

The input schema already documents project_id with a description ('The ID of the project'), covering 100% of parameters. The tool description adds no additional parameter semantics beyond restating the project scope.

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 ('Get') with a clear resource ('configuration groups and configurations') and scope ('for a project in TestRail'). It clearly distinguishes from sibling tools like get_tests or get_users by naming the exact resource.

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

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

The description provides clear context: this is the tool to retrieve configuration groups and configurations for a given project. It does not name alternatives or state when not to use it, but the resource name and scope are unambiguous relative to the listed siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds value by clarifying the return content ('label IDs and titles') and the terminology ('sometimes called tags'), which is helpful beyond the structured annotations. No contradiction exists.

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

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

The description is two concise sentences with no wasted words. The key verb and resource are front-loaded: 'Get all available test case labels.' The second sentence adds useful return and use-case context. It is appropriately sized for the tool's simplicity.

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 tool with one parameter and no output schema, the description adequately conveys what the tool does and what it returns. It mentions the return items ('label IDs and titles') and their purpose. It does not explicitly state that the output is a list, but 'all available' implies a collection, which is sufficient for this low-complexity tool.

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

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

The input schema has one required parameter (project_id) with a clear description that fully aligns with the tool description. Since schema description coverage is 100%, the description adds little additional meaning to the parameter. Baseline 3 is appropriate; the schema already documents the parameter well.

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: 'Get all available test case labels (sometimes called tags) for a project.' It uses a specific verb ('Get') and a specific resource ('test case labels'), and the parenthetical note ('sometimes called tags') prevents ambiguity. This distinctly differentiates it from sibling tools like get_tests or get_users.

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 the output can be used: 'Returns label IDs and titles that can be used when creating or updating test cases.' This gives clear context for invocation. It does not explicitly mention when not to use it or name alternative tools, but for a simple read operation the use case is well implied.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that it returns priority IDs and names but does not disclose other behavioral details such as authentication or rate limits. This meets the baseline for annotation-backed read tools.

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 with no wasted words. The first sentence states the core purpose with examples, and the second adds the return format and usage context. Ideal size for a simple lookup tool.

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

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

This is a low-complexity tool with no parameters and no output schema. The description fully explains what it returns (priority IDs and names) and why those are useful (for creating/updating test cases). No additional context is needed.

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 zero parameters, so the baseline is 4. The description appropriately focuses on the return value rather than parameter semantics, and there are no parameters to explain.

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 ('Get') and resource ('all available test case priorities'), with examples and a clear statement that it returns priority IDs and names. It is distinct from sibling tools, none of which mention priorities.

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 clearly states the returned IDs/names can be used when creating or updating test cases, providing contextual usage. However, it does not explicitly exclude alternative tools or state when not to use it, so it lacks explicit when-not guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description only restates the scope without adding extra behavioral context like error handling or return format.

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 directly states the tool's purpose without any wasted words.

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

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

For a simple one-parameter read-only tool, the description is sufficient when combined with annotations and schema. It lacks explicit output format details, but that is 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 single parameter test_id is fully described in the schema. The description adds no additional parameter meaning, so 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 verb 'Get' and the resource 'results' scoped to 'a specific test', which is unambiguous. It does not explicitly name alternative tools, but the resource is unique among siblings, so it distinguishes implicitly.

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

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

No explicit when-to-use or alternative guidance is given, but the purpose implies usage when you need results for a known test_id. This is minimally adequate but lacks clear context 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 the tool as read-only, idempotent, and non-destructive. The description adds behavioral context by revealing that it returns both IDs and names, and that these are interoperable with other tools. This goes beyond the annotations and helps the agent understand the tool's place in workflows.

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 conveys all necessary information: what it gets, example values, and the return format. Every clause earns its place; there is no wasted text.

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 no-parameter, read-only listing tool, the description is complete. It explains the output (status IDs and names) and how it can be used elsewhere. No output schema exists, so the description's mention of return values is sufficient.

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

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

The tool has zero parameters, so the baseline is 4. The description does not need to explain parameter details, and there is no schema coverage gap. It adds no extra parameter semantics, but none are needed.

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

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

The description clearly states the tool's function with a specific verb ('Get') and resource ('all available test statuses'), and provides concrete examples (Passed, Failed, Blocked). It also indicates the output type (status IDs and names), which distinguishes it from sibling tools like get_tests or get_cases.

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

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

The description explains when this tool is useful by noting that the returned IDs and names can be used with add_result and get_tests. This gives clear context for usage, though it does not explicitly mention when not to use it or compare to alternatives. Given that no sibling tool directly overlaps with statuses, this is sufficient.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds context about what template IDs are used for, which is useful, but it does not disclose additional behavioral traits such as response format, pagination, or authorization requirements. This is acceptable but not exceptional given the annotations.

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

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

The description is two short sentences with no filler. The core purpose is front-loaded, and the second sentence adds valuable context without redundancy. Every word contributes to understanding the tool.

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

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

The tool is simple: one required parameter, no nested objects, and rich annotations. The description explains what the tool returns conceptually and how the result relates to other operations. It does not describe the response shape, but given the tool's simplicity and annotation coverage, the description is largely complete.

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

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

The input schema fully documents project_id, including a helpful cross-reference to query_project. Since schema description coverage is 100%, the description does not need to add parameter details. It also does not add any parameter-level meaning beyond what the schema already provides, so 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 ('Get') and the resource ('available test case templates for a project'). It also adds meaningful domain context by explaining that template IDs determine available fields when creating/updating test cases. However, it does not explicitly differentiate this tool from siblings like get_case_fields, so it falls short of a full 5.

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

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

The description implies when to use the tool by connecting template IDs to test case creation/updating, but it does not explicitly state when to use this tool versus alternatives. No exclusions or alternative tool names are mentioned, leaving the usage guidance mostly implied.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering the safety profile. The description adds no behavioral context beyond the optional filter, which is parameter-related. This is acceptable given the annotations but not enhanced.

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

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

The description is a single sentence with no redundant wording. Every word contributes to the core meaning: the action, the resource, the scope, and the optional filter.

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 retrieval tool with good annotations and full schema coverage, the description adequately scopes the operation and the optional filter. However, with no output schema, it does not describe return values or pagination, but this is not critical for such a simple tool.

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

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

Schema description coverage is 100%, with both run_id and status_id fully described in the schema, including a reference to get_statuses for valid IDs. The tool description adds no additional parameter meaning, so the baseline 3 applies.

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

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

The description uses a specific verb 'Get' with a clear resource 'tests' and scoping 'for a test run', distinguishing it from siblings like get_cases or get_results. The optional status filter further clarifies the exact functionality.

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 needing tests for a test run, but provides no explicit guidance on when to prefer this tool over alternatives or any exclusion criteria. The context is clear but no alternatives are mentioned.

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

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

Beyond the readOnly/idempotent annotations, the description discloses important behavior: global fetch may be forbidden for non-admin accounts, and it falls back to merging users across projects. This adds meaningful context about permissions and fallback, which annotations don't convey.

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

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

The description is two sentences: the first states the core purpose, the second explains the fallback scenario. Every word earns its place with no redundancy or padding.

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

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

For a simple read-only tool with only two optional parameters and rich annotations, the description fully covers purpose, scope, and fallback edge cases. No output schema exists, but the tool's behavior and expected results are clear from the description.

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 full descriptions for both parameters (project_id and fallback_all_projects) with 100% coverage. The description adds context about merging behavior, but it doesn't add new parameter-level details beyond what the schema already states.

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

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

The description clearly states the tool gets active users from TestRail, with specific scope (globally or per-project). It distinguishes from siblings, which all deal with tests, cases, sections, or runs rather than users.

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

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

The description explains when to use the tool (to retrieve active users globally or per-project) and describes the fallback behavior for non-admin accounts. It doesn't explicitly name alternatives, but no sibling tool serves the same purpose, so this is clear enough.

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 signal a non-read-only, non-idempotent mutation. The description adds that it creates or updates a test run, but it does not disclose side effects such as whether updating replaces all fields or whether creating without case_ids includes all cases. No contradiction but limited extra context.

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

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

Two sentences, front-loaded with the main purpose, no repetition or fluff. 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?

The tool has a complex oneOf schema, and the description orients the agent appropriately without restating schema details. It could mention required fields per action, but the schema already covers that, so overall it is sufficiently 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?

Input schema coverage is 100% with detailed descriptions for each parameter including action consts. The description's instruction 'Set payload.action to create or update' adds little beyond the schema's own descriptions, 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?

Description uses specific verbs 'Create' and 'update' and identifies the exact resource 'test run in TestRail'. It clearly distinguishes this tool from sibling tools like mutate_suite by naming the target resource and operation.

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

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

The description tells the agent to set payload.action to 'create' or 'update', providing clear context for when to use each mode. However, it does not explicitly name alternatives or exclusion criteria, so it falls short of the highest 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 annotations already flag readOnly=false, idempotent=false, and destructive=false, and the description does not add meaningful behavioral context beyond 'create or update.' It does not disclose postconditions, overwrite behavior, or what happens on the update branch, so the agent is left without additional operational expectations.

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 one clear sentence plus a short actionable instruction. It is front-loaded with the verb and resource and contains no filler.

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

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

The description and schema together are sufficient to know what action to set and which fields are required for each branch. However, there is no output schema and the description does not mention return behavior, success/failure signals, or prerequisites like resolving suite_id with query_suite (which only appears in 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%, so the schema already explains every parameter. The only additional instruction, 'Set payload.action to create or update,' restates what the schema's action const/descriptions already convey; it does not add new semantics.

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

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

The description names a specific operation and resource: create or update a TestRail section. It clearly communicates the dual-action nature but does not distinguish this from sibling mutation tools like mutate_suite beyond the resource name.

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

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

The description only explains how to choose between the two internal operations ('create' vs 'update') via payload.action. It gives no guidance about when to select this tool over sibling tools such as query_section for reads or mutate_suite for suite-level mutations.

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 indicate this is a mutation (readOnlyHint=false), and the description adds the dual create/update mode controlled by 'payload.action'. It doesn't disclose additional behavioral details like whether updates are partial, permissions required, or side effects. Given the annotations cover some safety profile, a score of 3 is appropriate.

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

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

The description is a single, front-loaded sentence that clearly states the purpose and the key usage instruction. Every word earns its place; it is concise without being under-specified.

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 complexity (one parameter with two possible shapes), the description covers the essential context: what the tool does and how to select create vs. update. The schema enriches the details. However, it does not mention potential return values or side effects, though the annotations provide some behavioral context. Slightly more detail could be added, but it is largely complete.

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

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

Schema coverage is 100%, so all parameter descriptions are already present in the schema. The description only restates the 'action' values ('create' or 'update') which are already defined as consts in the schema. It adds no new semantic meaning beyond what the schema provides, matching the baseline of 3.

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

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

The description uses a specific verb and resource: 'Create a new test suite or update an existing one in TestRail.' This clearly states the tool's function and distinguishes it from sibling tools like mutate_section or mutate_run. The mention of 'create' or 'update' operations further pins down the exact behavior.

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 the tool: when you need to create or update a test suite. It specifies the operation via the 'action' field, giving concrete usage context. However, it does not explicitly mention alternatives or when not to use this tool, 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the operation split ('one' vs 'many') but does not disclose that downloading writes to the local filesystem via 'output_file', nor does it describe return behavior. It does not contradict the annotations, and the added operational detail is modest, so 3 is appropriate.

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

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

The description is a single clear sentence followed by a brief operational instruction. It is front-loaded with the core purpose and contains no filler or redundant background. Every clause earns its place, and the 'one'/'many' hint is directly actionable.

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, combined with the detailed oneOf schema and the annotations, gives the agent enough to invoke the tool for both modes. There is no output schema, so the description could have mentioned what a successful 'many' call returns, but the schema already says it retrieves metadata. Overall it is complete for the tool's complexity and expected use.

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

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

Schema description coverage is 100%, and the schema's parameter descriptions already explain 'action', 'attachment_id', 'entity_type', 'entity_id', and 'output_file' in detail. The description only references 'payload.action' and the concept of downloading/listing, adding little beyond what the schema provides. Baseline 3 is correct because the schema carries the parameter semantics.

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

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

The description states a specific verb ('Download', 'list'), a clear resource ('attachment'), and the domain ('test case or test run in TestRail'). It also distinguishes the two operations ('one' or 'many'), making it easy to understand what the tool does and to separate it from write-focused siblings like 'add_attachment'.

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 by stating when the tool applies: for downloading a single attachment or listing attachments for a test case/run. It does not explicitly name alternatives or exclusions, but the read-only scope and the sibling tool 'add_attachment' strongly imply the read-versus-write boundary. It also tells the agent to set 'payload.action' to select the operation, which is practical usage guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no extra behavioral context beyond what the schema provides (the action parameter), so it meets the baseline but offers no additional transparency.

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 wasted words. It efficiently conveys both the operation and the mechanism.

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 moderate complexity (oneOf schema) and strong annotations, the description is sufficient. It lacks mention of return format or pagination, but these are not critical for a read-only query tool and are not required by the absence of an output schema.

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

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

Schema description coverage is 100%, with detailed descriptions for the payload and action values. The description merely restates the action logic ('Set payload.action to one or many'), adding no new semantics beyond what the schema already defines.

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 retrieves 'a single project or all projects in TestRail,' using the specific verb 'retrieve' and resource 'projects.' It distinguishes from sibling tools by the resource (projects vs tests, cases, suites, etc.).

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 by stating what it retrieves, and the sibling context clearly shows this is the project-query tool. However, it does not explicitly mention alternatives or exclusions, 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?

Annotations already provide readOnlyHint, destructiveHint, idempotentHint. The description adds the dual-mode behavior ('one' vs 'many'), which is useful context beyond annotations.

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

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

Two concise, front-loaded sentences that efficiently convey the tool's purpose and key usage pattern.

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 adequately explains the tool's retrieval purpose and action modes. While no output schema is provided, the annotations cover safety, and filtering details are in 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%, so parameters are well-documented. The description clarifies the action parameter's role but doesn't add new info beyond schema.

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

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

The description clearly states the tool retrieves test runs (single or all) for a project, with a specific verb and resource. It distinguishes from sibling tools like mutate_run.

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

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

No explicit guidance on when to use this tool versus alternatives like get_cases or get_results. The description implies read-only use but doesn't differentiate within sibling retrieval 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description's 'Retrieve' wording is consistent with those. The description adds the one-vs-many selection behavior, but it does not disclose details such as child-section nesting or large-output behavior, which are documented only in the schema. 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 sentence communicates the tool's purpose and the key operation switch without repetition or filler. It is front-loaded with the primary behavior and the action mechanism is stated 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?

For a read-only query tool with a rich oneOf schema, the description plus schema covers the necessary call structure, required IDs, and optional filters/output_file. It does not describe the return shape, but no output schema exists and the operation is a simple retrieval, so this is a minor gap. The only notable omission is explicit routing guidance relative to get_sections.

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 fully documents the action branches, section_id, project_id, suite_id, include_child, output_file, and name_pattern. The description's instruction to set payload.action to 'one' or 'many' adds no meaning beyond what the schema already provides, hitting the baseline of 3.

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

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

The description states a specific verb ('Retrieve') and resource ('sections for a project'), and notes the two operation modes via payload.action. It is clear on its own, but it does not explicitly differentiate from the sibling get_sections tool, so it stops short of a 5.

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

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

The description tells the agent to choose action='one' or 'many' but gives no context for when to use query_section versus sibling tools such as get_sections or mutate_section. The only usage hints live inside the parameter schema ('Use query_suite...'), not in the tool-level guidance, so there is effectively no when-to-use/when-not-to-use 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 the tool as read-only, idempotent, and non-destructive. The description adds the dual-mode behavior (single vs. many) driven by payload.action, which is beyond the annotations and helps the agent understand how the tool's output varies. No contradictory behavior is disclosed.

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 that conveys the essential purpose and operation selection without any filler. It earns its place 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 has a moderately complex oneOf schema and no output schema. The description explains the operation modes but does not describe the return format, error behavior, or any limitations like pagination. While annotations cover safety, the description leaves out details that would be helpful for a complete understanding of expected responses.

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 parameters are already well-documented. The description reiterates the action parameter's role ('set payload.action to one or many') but does not add new meaning to suite_id or project_id beyond what the schema provides. This aligns with the baseline for fully described schemas.

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

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

The description clearly states the verb 'retrieve' and the resource 'test suite(s)', and specifies the two modes: single or all for a project. This distinguishes it from sibling tools like get_cases or query_run by targeting suites specifically, especially with query_suite vs mutate_suite.

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 operational instructions ('Set payload.action to one or many') but does not provide guidance on when to use this tool versus alternatives. It lacks explicit when-to-use or when-not-to-use context, such as 'use mutate_suite for modifications.'

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds the domain-specific detail about Multi-select case field type ID 12, but does not disclose output format or behavior for invalid or unknown refs. 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, front-loaded sentence with no filler. Every phrase adds meaningful context: numeric reference IDs, Multi-select field, type ID 12, textual values, and project scope.

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

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

For a simple three-parameter tool with fully documented schema and safety annotations, the description gives sufficient context for selection and invocation. The absence of an output schema leaves the exact return shape unspecified, but this is a minor gap given the tool's simplicity and clear purpose.

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 covers all three parameters with descriptions, so the description does not need to repeat parameter details. It adds overall context, such as the transformation from reference IDs to textual values, but no parameter-specific meaning beyond the schema. Baseline 3 is appropriate 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?

States a specific operation: resolving numeric reference IDs to textual values for a Multi-select case field. It identifies the field type (ID 12) and the project scope. This clearly distinguishes it from sibling tools like get_case_fields or query_project.

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

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

The description clearly implies the intended use case: converting opaque numeric references into readable values for a Multi-select field in a project. It does not explicitly name alternatives or state when not to use it, but the context is clear enough for an agent to select it appropriately.

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

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

Annotations only indicate false for readOnly, idempotent, and destructive, which are not very informative. The description adds the behavioral trait of partial updates, but doesn't disclose return values, side effects, or error handling beyond the schema. It's 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?

Two sentences, front-loaded with the main purpose, and every sentence adds value. It's 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?

The description covers the essential update behavior and partial-update semantics, but it doesn't mention what the tool returns or any side-effect beyond the update. Since there is no output schema, the description could do more to explain the response, but the key operational details are present.

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 adds meaningful semantics by explaining that only specified fields are changed (partial update). This goes beyond the schema's description of the fields parameter, which focuses on the flat-map structure.

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 'Update a test case in TestRail' with a specific verb and resource. It doesn't explicitly distinguish from the sibling tool update_cases, but the singular 'a test case' and the tool name imply single-case updates, making the purpose clear.

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

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

The description gives clear usage context: it requires knowing valid field names from get_case_fields and supports partial updates, which tells the agent how to use it. It doesn't explicitly mention when not to use it (e.g., for bulk updates), but the prerequisite and partial-update behavior are useful 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 indicate only that the operation is not read-only, not idempotent, and not destructive. The description adds the dependency on get_case_fields and the need for valid field names, but it does not disclose whether updates are partial/merge or full replacement, or how errors are handled beyond the schema's note. Some behavioral context is added, but significant gaps remain.

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 three sentences: purpose, prerequisite, and efficiency comparison. Every sentence earns its place with no redundancy, and the most important information (bulk update) is front-loaded.

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

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

For a bulk mutation tool with no output schema and sparse annotations, the description covers purpose, usage alternative, and prerequisite. It lacks details about return value or partial failure behavior, but the rich schema and sibling context compensate somewhat. A more complete description might mention whether the update merges or replaces existing fields.

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

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

Schema description coverage is 100%, with detailed descriptions for both parameters: case_ids is a simple array, and fields is fully explained with format, example, and error conditions. The description's mention of 'same field values' adds little beyond the schema, so 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 the tool performs a bulk update of multiple test cases with the same field values, using a specific verb ('bulk update') and resource ('test cases'). It distinguishes itself from the sibling update_case tool by noting it is more efficient than calling update_case multiple times, and it mentions the prerequisite of get_case_fields for valid field names.

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

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

Explicitly provides usage guidance by comparing to update_case, stating 'More efficient than calling update_case multiple times,' which implies the appropriate context for using this tool. It also clarifies that get_case_fields must be called first to obtain valid field names, serving as a clear prerequisite.

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