TestRail MCP Server

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

Annotations declare the safety profile (not read-only, not destructive, not idempotent), so the description is free to add operational detail. It contributes real behavior beyond annotations: automatic zipping when file_path is a directory and a 256MB maximum upload size. It does not say what happens on duplicate filenames or how large attachments are reported.

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, zero filler, and the core action is front-loaded before the two conditional constraints. Every sentence carries information an agent would otherwise have to guess.

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 mutation tool with full schema coverage, annotations covering safety, and no output schema, the description covers the notable edge cases (directories, size limit). The main gap is the absence of any statement about the result of a successful upload or failure modes, which an agent might want.

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

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

Schema description coverage is 100%, so the schema already documents entity_type, entity_id, and file_path, including the 'C123'/numeric ID convention and the directory-zipping behavior. The description largely restates the file_path zip semantics, adding little meaning beyond structured fields; 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 names a specific verb and resource ('Add an attachment') and enumerates the three target entity types (test case, test run, test result), so an agent knows exactly what the tool does. It stops short of explicitly differentiating itself from the sibling read counterpart query_attachment, which keeps it from 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?

Usage is implied by the purpose rather than stated: there is no explicit 'use this when...' or routing advice against siblings like query_attachment. It does supply practical preconditions (directory auto-zip, 256MB cap), which is useful but is constraint information rather than when-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 readOnly=false, destructive=false, idempotent=false, so the safety profile is covered structurally. The description adds the dependency on get_case_fields and the failure mode for unknown field names, but does not describe permissions, validation behavior, or what is returned.

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

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

Two tight sentences; the core create action is front-loaded and the prerequisite follows. No wasted text, though the second sentence could be folded into the first without loss.

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

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

For a mutation tool with full schema coverage, no output schema, and annotations covering safety, the description plus schema is largely complete. The main omission is any note about what happens on success (created ID) or overlapping fields.

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

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

Schema description coverage is 100%, so the baseline is 3; the description adds only the field-name provenance requirement, which the schema's 'fields' description already explains in detail. No additional parameter meaning beyond the structured fields.

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

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

States a specific verb and resource ('Create a new test case in TestRail'), clearly distinct from update_case/get_case siblings by the verb. It does not explicitly name the sibling it is not, so it stops short of full sibling differentiation.

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

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

Names a concrete prerequisite and the tool that satisfies it: field names must come from get_case_fields, and unknown field names will error. This gives clear context for correct invocation, though it does not compare against update_case or otherwise 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?

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that: it does not warn that re-adding the same result is non-idempotent (duplicates possible), nor describe permissions or what the call returns. For a mutation tool with no output schema, this is thin.

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

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

A single front-loaded sentence with zero filler; the action and scope come first. It is efficient but borders on under-specification rather than true conciseness, since no behavioral detail accompanies it.

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

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

For a non-idempotent write tool with no output schema, the description omits what happens on success (created IDs, duplicates) and does not route the agent to the sibling add_results_for_cases or the required lookup tools. Annotations carry the safety signal, but the remaining behavioral gap is significant.

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

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

Schema description coverage is 100% and the schema itself documents run_id, the results array, and each nested field including cross-references to get_tests and get_statuses. The description adds no syntax, format, or batching semantics beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb (add) and resource (test results) with scope (one or more, to a test run), so the core action is unambiguous. It does not differentiate from the near-identical sibling add_results_for_cases, which an agent could easily confuse with this tool.

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

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

There is no when-to-use guidance, no prerequisites (e.g. results must belong to an existing run), and no mention of the closely related add_results_for_cases alternative. The agent is left to infer the distinction from names alone.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the mutation/safety profile is covered structurally and is not contradicted. The description adds nothing beyond that — no note on failure behavior for invalid case/status IDs, batch atomicity, or permission requirements.

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

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

A single front-loaded sentence with zero filler that conveys the action and the case-ID-vs-test-ID distinction immediately.

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

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

For a non-idempotent write tool with no output schema, the description plus full schema and annotations cover the essentials, but the description contributes little on its own and omits any error/permission context an agent might need.

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

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

Schema coverage is 100% and the schema itself documents run_id, the results array structure, and even points to get_cases/get_statuses for ID lookup. The description adds no parameter meaning beyond the schema, so baseline 3 is appropriate.

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

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

States a specific verb (add), resource (test results), target (a test run), and the key distinguishing mechanic: case IDs rather than test IDs. This implicitly separates it from the sibling add_results, though it never names that sibling directly.

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 'using case IDs instead of test IDs' phrasing implies when to pick this over add_results, but it is never stated explicitly and no prerequisites (run must exist, valid status IDs, permissions) are given. Usage is inferable but not spelled out.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safe read semantics are covered. The description adds the useful detail that custom fields are included in the result, but says nothing about error behavior (e.g. missing case), depth of returned data, or 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?

A single, front-loaded sentence with no filler; the verb and the noteworthy detail (custom fields) come first. It is appropriately sized for a simple single-parameter lookup, though it could be marginally more informative without bloat.

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

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

For a low-complexity read tool whose safety profile is covered by annotations, the definition is minimally adequate. With no output schema, the description only lightly sketches the return (detailed info plus custom fields) and omits noting what happens for an unknown case_id.

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 single case_id parameter (with example formats '123' or 'C123') is fully documented in the schema. The description adds no syntax or semantic detail beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description names a specific verb (Get) and resource (test case) and adds a scope note about custom fields, which is useful. However, it does not explicitly distinguish itself from close siblings like get_cases (plural list) or get_case_fields, leaving the differentiation to inference.

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

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

There is no statement of when to use this tool versus alternatives such as get_cases, get_case_fields, or query_test. The agent must infer usage purely from the name, with no exclusions or prerequisites offered.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false. The description adds value by describing the return format ('fields with their types and options for dropdown fields'), which is important since no output schema exists. It does not discuss auth or rate limits, but those are less critical for a read-only metadata 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?

Three sentences, front-loaded with the main action, followed by parameter guidance and return value information. Every sentence earns its place with no redundancy.

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

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

For a simple read-only tool with one parameter and no output schema, the description covers purpose, parameter usage, and return format. An agent has enough information to call it correctly without needing to inspect other sources.

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 normative guidance beyond the neutral schema text, telling the agent that project_id should normally be provided and that omitting it is rarely desirable. This meaningfully shapes parameter usage.

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

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

States a specific verb and resource: 'Get the field schema for test cases for a specific project.' This clearly distinguishes it from siblings like get_case, get_cases, and resolve_case_field, which deal with case data rather than field metadata.

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

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

Gives explicit guidance on when to provide project_id versus omitting it, including the normative warning that omitting is 'rarely what you want.' It does not name alternative tools or conditions for using them, so it falls short of full when/when-not/alternatives coverage.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds the return shape (case IDs, titles, requested fields), which is mildly useful, but the significant behavioral caveat — that 'where' fetches all cases first and filters client-side — lives only in the schema, and no auth or rate-limit context is given.

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

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

Three tight sentences, front-loaded with purpose followed by filtering and return shape. No filler, though the return-shape sentence is the only non-redundant addition.

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

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

No output schema exists, so the description correctly compensates by naming the guaranteed return fields (IDs, titles) plus requested extras. With 100% schema coverage on parameters and annotations covering safety, the definition is nearly self-sufficient; only the client-side filtering cost is left undocumented in 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?

Schema description coverage is 100%, so the schema already documents all seven parameters thoroughly. The description summarizes the same filters (section, priority, type, custom fields via 'where') without adding syntax, format, or constraint detail beyond the schema — the baseline 3.

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

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

States a specific verb and resource ('Get all test cases for a project') with scope, then names the filter dimensions and the return contents. An agent can distinguish this from the singular sibling get_case and from get_tests/get_results without opening any schema.

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

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

The description enumerates the filtering mechanisms (section, API params, 'where') but never says when to prefer this tool over get_case or get_tests, nor when to use the API-side 'filter' versus the client-side 'where'. Usage is implied by the filter 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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds only that the result is scoped to a single project and includes both groups and their configurations; it says nothing about ordering, pagination, or what happens if the project has no configurations. With annotations carrying the behavioral burden, a 3 is appropriate.

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

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

One sentence, zero filler, with the resource and scope front-loaded. Nothing could be removed without losing information.

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

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

For a low-complexity, single-required-parameter read tool with a full schema and no output schema, the description covers what is needed to call it correctly. The one modest gap is that it does not sketch the shape of the returned data (groups each containing configurations), which would help an agent plan the follow-up call.

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 has a single parameter with 100% description coverage ('The ID of the project'), so the schema does the heavy lifting. The description reinforces the project scoping but adds no syntax, format, or lookup guidance beyond it. Baseline 3 for a fully documented single-parameter schema.

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

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

States a specific verb-and-resource pair: 'Get all configuration groups and configurations for a project.' It also names the scope (project) and the system (TestRail), which cleanly separates it from metadata siblings like get_priorities, get_statuses, and get_templates. It stops short of explicitly distinguishing itself from any specific alternative, which keeps it at 4 rather than 5.

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

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

There is no explicit when-to-use or when-not-to-use statement, but the purpose is transparent enough that usage is implied: call it when you need the configuration groups available in a project. Given the sibling set is a group of orthogonal read-only lookups, no routing guidance is strictly needed, so this is minimum-viable rather than deficient.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds information annotations do not carry: what the call returns (label IDs and titles) and its project scope. It still omits pagination or empty-result behavior, so it is not a 5.

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

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

Two short sentences with no filler, and the core purpose is front-loaded before the return-value detail. Every clause earns its place.

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

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

With no output schema, the description usefully compensates by describing the return payload (label IDs and titles). For a single-parameter read-only lookup this is essentially complete, though a note on ordering, pagination, or empty results would close the last gap.

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

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

Schema description coverage is 100% with a single, well-documented project_id parameter, so the schema carries the burden. The description only echoes the project scoping ('for a project') and adds no format or edge-case detail beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Get all available test case labels ... for a project') and disambiguates terminology by noting labels are 'sometimes called tags'. It does not distinguish itself from similar lookup siblings like get_case_fields, get_priorities, or get_statuses, 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?

Usage is implied rather than explicit: the description notes the returned IDs and titles 'can be used when creating or updating test cases', which hints at why an agent would call it. There is no statement of when-not to use it or which sibling would be more appropriate for related lookups.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds useful linkage context — that the output feeds mutating calls — but says nothing about result size, ordering, or the fact that it takes no arguments.

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

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

Two sentences, zero waste: the first names the resource and gives examples, the second explains the value of the return. The most actionable information (what it returns and why) 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 simple, no-argument, read-only lookup with no output schema, the description gives enough to invoke correctly and use the result. It stops short of describing the exact response shape (ID/name field names) or whether an empty list is possible.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. It correctly implies a parameterless global lookup rather than a filtered query.

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

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

States a specific verb+resource ('Get all available test case priorities') and even enumerates representative values (Critical, High, Medium, Low), so the agent immediately knows what comes back. It does not explicitly differentiate itself from similar lookup siblings like get_labels, get_statuses, or get_templates, though the parallel pattern makes the distinction inferable.

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 clear context: the returned priority IDs and names 'can be used when creating or updating test cases,' which tells the agent this is a prerequisite lookup for add_case/update_case. There are no explicit exclusions or named alternatives, keeping it 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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered elsewhere. The description adds nothing beyond that — no pagination, filtering behavior, or note on what happens for a nonexistent test_id.

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

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

A single efficient sentence with no filler and the key scope ('specific test') front-loaded. It is appropriately sized, though thin enough that it borders on under-specification rather than true conciseness.

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

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

No output schema exists, so the description could reasonably say what a 'result' contains (status, comment, timestamps), but it does not. With a single fully documented parameter and complete annotations, the definition is minimally viable but not complete.

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

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

With only one parameter and 100% schema description coverage, the schema fully documents test_id, so the baseline is 3. The description contributes no extra meaning about the ID's origin or expected format.

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

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

States a specific verb ('Get') and resource ('results') scoped to 'a specific test in TestRail', which is clear enough to act on. However, it does not distinguish itself from siblings like get_tests, query_test, or get_cases, which an agent could plausibly confuse it with.

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

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

The description gives no when-to-use guidance, no prerequisites, and never names an alternative such as get_tests or add_results_for_cases. The agent must infer the selection context entirely from the tool name.

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

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

Annotations already declare this as a read-only, idempotent, non-destructive operation, so the safety profile is covered. The description adds genuinely useful context beyond that: the shape of the return (status IDs and names) and the fact that those IDs feed into add_result and get_tests.

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

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

Two short sentences, front-loaded with the purpose followed by the return/usage note. No filler, hedging, or redundant restatement of the name.

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

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

For a zero-param, read-only lookup with no output schema, the description covers purpose, returned content, and downstream usage, which is sufficient to call it correctly. It stops short of noting whether the status list is static or project-configurable, a minor gap for this tool class.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; per the baseline this scores 4. The schema itself carries no additional semantics that need explanation.

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

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

States a specific verb and resource ("Get all available test statuses") and makes the resource concrete with examples (Passed, Failed, Blocked). It doesn't explicitly contrast itself with the other lookup siblings (get_labels, get_priorities, get_templates), but the resource is unambiguous.

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

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

The second sentence implies usage by naming downstream consumers (add_result, get_tests), which tells the agent this is a prerequisite lookup step. There is no explicit when-to-use/when-not guidance or mention of alternatives, so usage 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?

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds the semantic role of template IDs, but says nothing about error behavior for an invalid project_id, permissions, or whether the list is paginated or filtered.

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

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

Two sentences, zero filler, and the core purpose is front-loaded before the explanatory clause. 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 simple, read-only, single-parameter lookup there is no output schema, so the description carries some burden for describing returns; it partially does so by explaining what template IDs mean. A brief note on what a template record contains would make it fully complete, but nothing essential to invoking it correctly is missing.

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

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

With a single parameter and 100% schema description coverage (including the 'use query_project to find available projects' hint), the schema already carries parameter semantics. The description adds no further format or constraint detail beyond what the schema provides, so the baseline 3 applies.

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

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

The description gives a specific verb and resource ('Get available test case templates for a project') and clarifies the value of the result by tying template IDs to the fields available when creating/updating cases. That implicitly separates it from siblings like get_case_fields or get_configurations, though no sibling is named outright.

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

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

The second sentence implies when an agent would care about templates (before creating or updating a test case), which is useful implied usage. However, there is no explicit when-to-use, no stated prerequisite beyond project_id, and no routing away from alternatives such as get_case_fields.

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 non-destructive behavior, so the safety profile is covered. The description adds only the deprecation status; it does not describe return format, pagination, or any permission constraints, so added value beyond annotations is modest.

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

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

A single front-loaded sentence states the primary action, then the optional filter, with the deprecation note in a concise parenthetical. There is 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?

For a simple read-only tool with fully documented parameters and annotations covering safety, the description plus schema is nearly complete. The only minor gap is that it does not hint at the return shape, though no output schema exists and deprecation reduces the need.

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

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

Schema coverage is 100% and both parameters are fully documented in the schema. The description mentions the optional status filter but adds no syntax, format, or behavioral detail 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?

States a specific verb ('Get') and resource ('tests') scoped to a test run, and names its replacement (query_test with action 'many'). It is clear, but the generic term 'tests' is not explicitly contrasted with siblings like get_cases or get_results, leaving some ambiguity about what entity is returned.

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 marks the tool as deprecated and names the alternative call to use instead (query_test with action 'many'). That is direct when-not and alternative guidance, which is exactly what an agent needs to avoid invoking it.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered; the description goes further by disclosing an authorization constraint (non-admin accounts cannot fetch globally) and the compensating behavior of merging users across all active projects. That is exactly the kind of permission-dependent behavior an agent needs.

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

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

Three sentences, front-loaded with the core action, then scope, then fallback rationale. Every sentence carries information, though the third sentence partially restates the second's fallback concept.

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 no-required-param read tool with full annotation coverage, the definition is nearly complete: it explains scope, permission limits, and fallback. It does not describe the shape or fields of the returned user objects, which is the main residual gap given there is no 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 coverage is 100%, so the schema already documents both project_id and fallback_all_projects, including defaults. The description restates the global-vs-project choice and the fallback rationale but adds no format or syntax detail beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb and resource (get active users) plus the scope it operates over (global or per-project). No sibling retrieves users, so it is trivially distinguishable, but the description does not explicitly contrast itself with any other tool.

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

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

Gives clear context for use — resolving users referenced as reviewers or assignees — and explains the exact condition that triggers the fallback path (global fetch forbidden for non-admin accounts). It stops short of stating when not to use the tool or naming alternatives.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the safety profile is covered. The description adds only that this is a create/update mutation; it omits update semantics (does an update replace or merge unspecified fields?) and any permission or side-effect notes.

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

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

Two short sentences, front-loaded with the operation and followed by the discriminator hint. Nothing redundant or padded.

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

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

Annotations cover safety and the schema fully covers inputs, so the core is adequate. Still, for a non-idempotent mutation the description leaves the update behavior and the divergence in required fields between create and update unexplained, which an agent must infer from the schema.

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

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

Schema description coverage is 100%, and the schema itself documents action consts, project_id, run_id, case_ids and name more precisely than the description. The description's single sentence about payload.action adds nothing beyond the structured oneOf discriminator, so the baseline 3 applies.

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

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

States a specific verb (create/update) and resource (test run) and names the platform (TestRail). It clearly reads as the write counterpart to the sibling query_run, though it never explicitly contrasts itself with that sibling or with mutate_suite/mutate_section.

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 tells the agent that payload.action must be 'create' or 'update', which is a real usage hint for selecting the mode. However, it gives no guidance on when to prefer this tool over query_run, no prerequisites, and no warning about the two actions having different required fields.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the safety profile is covered structurally. The description adds that a single tool handles both create and update, which is useful context, but it does not disclose side effects like hierarchy changes from parent_id or how updates treat omitted 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?

Two tight sentences with zero filler, and the core purpose is front-loaded ahead of the action-selection detail. 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?

With a fully documented schema and no output schema to explain, the description is nearly sufficient. It could be slightly stronger by noting the read sibling or that suite_id is conditionally required, but for a discriminated-union mutation tool the essentials 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 description coverage is 100% and the discriminated union already documents every field, including action constants, suite_id requirements, and parent_id. The description merely restates the action mechanism, adding no semantics beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb pair (create/update) and resource (section), and clearly frames this as the mutation counterpart to the read tools. It is unambiguous what the tool does, though it never names a sibling (e.g. query_section) to help an agent pick between reading and mutating.

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 tells the agent how to select the operation via payload.action ('create' or 'update'), which is genuine usage mechanics. However, it gives no when-to-use conditions, prerequisites (e.g. needing a suite_id for multi-suite projects), or alternatives to consider instead.

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

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

Annotations already declare readOnlyHint=false and non-idempotent, so the description's mutation framing adds little. It discloses nothing about permissions, whether update overwrites unspecified fields, error behavior, or side effects — all relevant for a non-idempotent write tool. No contradiction with annotations (create/update is not destructive).

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

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

Two short sentences, front-loaded with the purpose and followed by the mode selector. No filler; both sentences earn their 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?

Adequate for a simple one-parameter mutation with no output schema, but it omits what an update actually changes and whether omitted fields are preserved — the main behavioral question an agent would have. Nothing about auth or failure modes either.

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

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

Schema description coverage is 100% and the single payload parameter is fully documented with per-variant required fields, so the schema does the heavy lifting. The description only restates the action values already encoded as const in the schema, adding no extra semantics.

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

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

States specific verbs and resource ("Create a new test suite or update an existing one in TestRail") and names the discriminator between the two modes. It does not explicitly contrast with the read-only sibling query_suite, but the mutation intent is unambiguous.

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

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

Tells the agent how to select the operation via payload.action='create'|'update', which is useful routing information. It gives no when-to-use vs when-not-to-use guidance (e.g., prefer query_suite to read, or which sibling to use for sections/runs).

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 only the two operating modes, which the schema already describes; it does not mention that the 'one' mode writes to the local filesystem or any permission/size constraints. Modest added context, hence a 3.

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

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

Two tight sentences, front-loaded with the operation and followed by the mode selector. No wasted clauses, though the second sentence largely duplicates what the schema's const enums already convey.

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 adequately signals the two outcomes (downloaded file vs. attachment list) and the mode discriminator. Annotations cover the safety profile. It stops short of noting where downloads land or what the list contains, but nothing essential to calling it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents action, attachment_id, entity_type, entity_id and output_file in detail. The description only restates the action discriminator values that the schema already fixates as consts, adding no format or semantics beyond it. Baseline 3 applies.

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

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

The description states specific verbs and resource: 'Download a single attachment or list all attachments for a test case or test run in TestRail.' This cleanly contrasts with the sibling add_attachment, though it never names or explicitly excludes it. An agent can identify the operation without opening the schema.

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

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

It explains how to select the operation ('set payload.action to one or many') but gives no guidance on when to prefer one mode over the other, nor any exclusions relative to siblings like add_attachment. Usage is implied by the enum values rather than stated as 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 adds nothing beyond that – no mention of pagination, result ordering, or filtering behavior for the 'many' case – so it does not enrich the structured 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 short sentences, front-loaded with what is retrieved and then the operation selector. No filler and no redundancy.

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

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

For a read-only, single-parameter query tool whose annotations cover safety and whose schema fully documents the payload, the description is essentially sufficient. Minor gap: with no output schema, it does not hint at what a project record contains, but this is not strictly required for correct invocation.

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

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

Schema description coverage is 100%: the payload oneOf branches document 'one' (with project_id) and 'many' in full detail. The description restates the action values already enumerated in the schema and adds no new meaning, which fits the baseline 3.

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

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

The description states a specific verb ('Retrieve') and resource ('project'), and clarifies the two scopes: a single project or all projects. It clearly separates query_project from resource-differentiating siblings like query_suite, query_run, and query_test without needing the schema.

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

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

It tells the agent how to select the operation ('Set payload.action to one or many') but gives no guidance on when to use each mode, no prerequisites, and no reference to alternative tools. Usage is implied rather than explained.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safe read-only profile is covered. The description adds the operation-mode distinction, but says nothing about pagination, return volume for 'many', authentication needs, or what happens when a run is not found.

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 retrieval purpose and followed immediately by the operation selector. There is no redundant or wasted language.

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

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

For a simple read-only retrieval tool with a richly described schema and complete annotations, the description is nearly sufficient. It omits no critical call-time requirement, though it could note the list-return behavior for 'many', which is the only 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 description coverage is 100%, and the nested schema documents action, run_id, project_id, suite_id, and is_completed in detail. The description merely restates that action should be 'one' or 'many', adding no meaning beyond the structured parameters, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: retrieve test run(s) in TestRail. It also distinguishes the two supported scopes, single run versus all runs for a project, so an agent can quickly identify what the tool does without opening the schema.

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

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

The description explains how to select the operation via payload.action ('one' or 'many'), which is useful in-tool usage guidance. However, it does not state when to use this tool versus siblings like query_test, get_results, or mutate_run, so alternative selection is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world scope, so the safety profile is fully covered elsewhere. The description adds no behavioral context beyond that—no mention of nested-tree return, large-result handling, or filtering behavior—so it earns little credit here.

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

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

Two short, front-loaded sentences with no filler. The second sentence is marginally redundant with the schema's const values, but it keeps the definition compact.

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

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

For a low-complexity read tool with complete annotations, 100% schema coverage and no output schema, the description plus schema give an agent everything needed to invoke it correctly. Sibling routing remains the only real gap, and that is minor for a straightforward query operation.

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

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

Schema description coverage is 100% and the nested oneOf documents action, IDs, include_child, output_file, and name_pattern in detail. The description's restatement of 'one'/'many' duplicates the schema's const entries rather than extending them, so baseline 3 applies.

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

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

States a specific verb (Retrieve) and resource (section) and covers both modes of operation. It does not explicitly differentiate itself from mutate_section or the other query_* siblings, but the read-only intent is unambiguous.

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

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

The second sentence only explains how to encode the operation via payload.action; it never says when to choose this tool over a sibling such as mutate_section or how it relates to query_project/query_suite. Any prerequisites ('use query_suite/query_project to find IDs') live in the schema, not the description.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds nothing beyond the schema-mandated action switch — no pagination, auth, or result-shape context.

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

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

Two sentences, zero waste, with the core purpose front-loaded before the parameter hint. Nothing is padded or repeated.

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

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

For a simple read-only retrieval tool with 100% schema coverage and annotations carrying the safety profile, the description is largely sufficient. The only gap is the absence of an output schema paired with no mention of what the retrieval returns.

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

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

Schema description coverage is 100%, including per-branch docs for action, suite_id and project_id, so the schema does the heavy lifting. The description restates the 'one'/'many' mechanism without adding syntax or constraint detail, so the baseline 3 applies.

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

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

States a specific verb ('Retrieve') and resource ('test suite'/'test suites') in TestRail, and explicitly covers both the single and list modes. It distinguishes itself from 'mutate_suite' implicitly via the read verb, but never names an alternative sibling, 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 ties each mode to a need (one suite vs. all suites for a project), which is implied guidance. However it never states when to prefer this tool over siblings like mutate_suite or query_project, and offers no exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and a closed world, so safety is fully covered elsewhere. The description adds only the action-based dispatch model, which the schema already encodes via const values, and says nothing about pagination or result size handling.

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

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

Two tight sentences with the operation description front-loaded and no filler. It is efficient, though it spends its second sentence on a fact the schema already states, leaving little room for genuinely additive 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 read-only query tool with 100% schema coverage and complete annotations, the description is serviceable but thin: it omits the status filtering, field selection, and large-dataset output_file escape hatch that the schema exposes, and leaves the get_tests overlap unresolved.

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

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

Schema description coverage is 100%, so every parameter (test_id, run_id, fields, status_id, output_file) is already documented with examples in the schema. The description only restates the action toggle, adding no meaning beyond structured fields; baseline 3 applies.

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

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

The description gives a specific verb and resource ('Retrieve a single test by ID or all tests for a test run in TestRail') and names the exact dispatching field. It is clear on its own, but it never differentiates itself from the sibling get_tests, which plausibly covers the same ground.

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 how to select the operation ('Set payload.action to one or many'), which is invocation mechanics rather than when-to-use guidance. It offers no exclusions, prerequisites, or comparison to alternative tools like get_tests or get_results.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world behavior, so the safety profile is covered. The description adds useful domain context (this is a lookup/normalization operation on type-12 fields), but says nothing about behavior on unknown/invalid refs, missing fields, or unmapped 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?

A single front-loaded sentence with no filler. The verb, the input (numeric ref IDs), the constraint (type ID 12), the output (textual values) and the scope (specific project) are all delivered 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 three-parameter lookup with no output schema, the description states the essential contract: numeric refs in, textual values out. What is missing is return shape detail (single value vs. mapping when an array is passed) and error behavior, which matters slightly given 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?

Schema coverage is 100%, so refs, field_name and project_id are all documented in the schema with examples. The description only echoes the project scoping and the fact that refs are numeric IDs, adding no syntax or format detail beyond the schema; the baseline of 3 applies.

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

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

The description gives a specific verb (Resolve), a precise resource (numeric reference IDs of a Multi-select case field), and the transformation performed (into textual values). It even pins the field type (type ID 12) and project scope, so an agent can distinguish it from generic field-listing siblings like get_case_fields.

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

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

Usage is implied rather than stated: an agent can infer it is needed when it holds numeric ref IDs and needs their labels. However, no when-not-to-use is given and no alternative is named (e.g., that get_case_fields returns definitions rather than resolved values), so the routing is left to inference.

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

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

Annotations already declare the mutation/safety profile (readOnly=false, destructive=false, idempotent=false), so the bar is lower. The description still adds real behavior: the operation is a partial merge, and unknown field names are rejected because names must come from get_case_fields. Consistent with 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 short lines, zero filler, and the core action is front-loaded before the prerequisite and the partial-update caveat. Every sentence carries information.

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

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

For a two-parameter mutation with no output schema, the description covers the prerequisite tool, the partial-update contract, and the field-name constraint. Return behavior after the update is unaddressed, but that is a minor gap given the schema's 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 description coverage is 100%, including a detailed note on how 'fields' is merged into the request body. The description restates the partial-update rule but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Update a test case in TestRail') with a clear scope qualifier ('partial updates'). It does not distinguish itself from the sibling update_cases (plural), so an agent must infer which one to pick from the singular/plural naming alone.

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

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

Gives a concrete prerequisite and routes the agent to the right helper: valid field names come from get_case_fields, and 'only specify the fields you want to change' tells the agent how to call it. No guidance on when to prefer this over update_cases, and no stated 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=false, destructiveHint=false, and idempotentHint=false, so the safety profile is largely covered structurally. The description adds the prerequisite lookup step, but much of that same detail (system_name requirement, merge-into-root behavior, error on unknown field names) is duplicated in the schema rather than delivering new behavioral context. It never addresses what happens to fields not included in the update or whether a partial failure leaves cases half-updated.

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

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

Three short sentences, front-loaded with the action and scope, then prerequisite, then efficiency rationale. Each sentence earns its place, though the get_case_fields prerequisite is repeated verbatim in the schema's field description.

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

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

For a two-parameter bulk mutation with full schema coverage and annotation coverage, the description supplies the operational context an agent needs: valid field names come from get_case_fields and bulk is preferred over repeated single updates. The remaining gap is batch semantics (all-or-nothing vs partial success), which no output schema exists to cover.

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 nested 'fields' object is thoroughly documented with examples, valid-name rules, and API merge semantics. The description adds no parameter-level information beyond what the schema already states, so the baseline 3 applies.

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

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

States a specific verb and resource ('Bulk update multiple test cases') plus the key constraint that all cases receive the same field values. It also explicitly names the sibling it supersedes ('update_case'), so an agent can route between them without opening 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?

Gives a clear alternative ('More efficient than calling update_case multiple times') and a hard prerequisite ('requires knowing valid field names that are returned by get_case_fields'). It stops short of explicit when-not guidance, e.g. whether single-case edits should still use update_case, but the selection context is easy to infer.

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