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

With no annotations, the description carries the full burden and does well: it discloses that there is no delete endpoint (effectively irreversible), that creation fails with "Type is required" without `test_case_type`, and that the call returns the created object. It omits permission/auth or rate-limit context, but the key risk profile is covered.

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

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

Three compact paragraphs, front-loaded with purpose, then prerequisites, then the parameter gotcha. Every sentence carries actionable information and nothing is repeated from the schema.

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

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

For a mutation tool with no annotations and no output schema, the description covers prerequisites, irreversibility, and the main failure mode. Only the shape of the returned object and any tenancy/permission caveats are left implicit, which is a minor gap.

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

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

Schema coverage is already 100%, so baseline is 3; the description adds real meaning beyond the schema by turning the optional-looking `test_case_type` into a practical requirement and explaining how to obtain a valid ID from the `testCaseTypeId` field of a `list_test_cases` row. That is genuinely useful cross-tool parameter guidance.

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 ("Creates a new test case in a project and returns it") and scopes where it happens. It does not distinguish itself from the close sibling `upsert_test_case`, so an agent still has to infer which one to pick.

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?

Useful prerequisites are given ("The test suite and section must already exist: this tool does not create them") plus a sandbox recommendation for experimentation. However, there is no explicit when-to-use-this-instead-of guidance against `upsert_test_case` or `list_test_cases`, so routing is only implied.

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

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

With no annotations, the description carries the full disclosure burden and does add useful traits: the 10 requests/second rate limit and the fact that one status is applied to every listed test case. However, it never says whether existing results are overwritten, whether the call is idempotent, or what permissions are required for a mutation.

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

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

Three tight sentences: the action first, then the bulk semantics, then the batching directive with the rate-limit rationale. 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?

The description and rich schema together cover how to invoke the tool, but there is no output schema and the description never says what a successful call returns (result IDs, per-case status) or how overwrites behave. For a mutation with eight parameters, that leaves a real gap.

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

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

Schema coverage is 100%, so the schema already documents all eight parameters in detail. The description reinforces the list-vs-single semantics of test_cases but adds little that is not already in the field descriptions, 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 (records) and resource (a result against test cases in a test run), and the bulk-endpoint explanation makes clear it is a write tool rather than a reader like get_test_run_results. It never names a sibling explicitly, which keeps it just below a 5.

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

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

Gives concrete guidance: 'Pass a single test case to record one result, or a list to record many in one request' and 'Always prefer one call with a list over repeated single calls.' It stops short of naming alternatives or stating when not to use the 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?

With no annotations, the description fully carries the burden: it discloses non-destructive behavior ('hides... without deleting'), that the endpoint is bulk, that reversal is not available through this server, and that the response is a bare boolean rather than a run snapshot. That is exactly the context an agent needs before invoking a mutation.

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

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

Front-loaded with the action and its effect, then constraints and the response shape. It runs slightly long across several short paragraphs, but each one contributes a distinct fact (semantics, discoverability, reversibility, return value) with no filler.

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

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

For a one-parameter, unannotated, no-output-schema mutation tool, the description covers everything missing from structured data: effect, bulk nature, irreversibility, and return type. An agent can call this correctly and knows how to verify and revert.

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 already documents that IDs only (no names/keys) are accepted, so the description does not repeat it. It does add adjacent value by naming filter_status values on the follow-up tool, which helps the agent verify results, though nothing further is said about the test_runs parameter itself.

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 ('Archives one or more test runs') and immediately clarifies the semantics of that verb (hides from default list, does not delete). This clearly separates it from destructive siblings and from list/read tools.

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

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

Gives explicit when/when-not guidance: use filter_status='archived' on list_test_runs to see archived runs, 'active' to exclude them, and states that restoring requires the Tuskr UI because no reverse action is wrapped. The boundary against alternatives is unambiguous.

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

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

With no annotations, the description carries the burden and discloses important behavior: large responses can exceed the MCP size limit and return an error with guidance, run fields are passed through with API capitalization, and trim_response/filter_exclude_test_cases affect payload size. It does not mention authentication or permission requirements, but it covers the main operational risks.

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 front-loaded with the core purpose, then supplies the key usage warning and output-shape note. Every sentence contributes useful context for a tool that can return very large responses.

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 complex export tool with no output schema and no annotations, the description explains the return envelope, payload size risk, trimming behavior, and API pass-through. Combined with the fully documented input schema, an agent has enough information to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all eight parameters in detail. The description reinforces narrowing with filter_ids and mentions response shaping, but it adds little parameter 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 states a specific verb and resource: exporting test runs of a project together with their test cases and latest results in one call. It explicitly distinguishes itself from get_test_run_results by explaining that this tool avoids per-run and per-page calls.

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

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

It gives clear context for using this tool: exporting multiple runs with cases in one call, contrasted with get_test_run_results. It also warns to narrow the export with filter_ids or other filters when test cases are included, though it does not compare against every relevant sibling such as list_test_runs or get_test_run_details.

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

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

With no annotations, the description carries the full burden and does well: it discloses that results are NOT carried over (every case starts UNTESTED, verified live), that cross-project copies are impossible, and how unset optional args behave. It stops short of stating permission/auth requirements, whether the copy inherits archived or lock state from the source, and whether the operation is idempotent or retry-safe — all material for a mutation tool with zero annotation coverage.

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

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

Purpose is front-loaded in the first sentence, then constraints are grouped into short topical paragraphs that each carry distinct information. Slightly long, and 'Every optional argument below' is a wasted clause that points at nothing, keeping it from a 5.

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

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

For a no-annotation, no-output-schema mutation tool, the description covers the behaviors an agent most needs — project confinement, selection immutability, result reset, and override semantics. The significant remaining gap is the return value: it never says whether the response includes the new run's ID or name, which an agent needs to chain a follow-up call, and permissions are unaddressed.

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

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

Schema coverage is 100%, so baseline would be 3, and the description earns above that by explaining merge semantics: each optional argument overrides the corresponding attribute on the copy, and leaving one unset preserves the source value rather than clearing it — a critical clarification given the schema shows empty-string defaults that would otherwise read as 'clear this field'. It does not enumerate the five parameters, and 'Every optional argument below' is a dangling reference that adds little per-parameter detail beyond the schema.

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

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

States a specific verb and resource ('Creates a copy of an existing test run along with its test cases') and immediately scopes it against the sibling that competes for the same intent, naming create_test_run explicitly. An agent can distinguish it from create_test_run and list_test_runs 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?

Explicitly says when to use it and when not to: the copy stays in the source project because there is no project parameter, the case selection cannot be narrowed here, and create_test_run is the alternative when a different selection is needed. These are concrete exclusions, not implied ones.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure, and it states only that a record is created. It says nothing about side effects such as whether assigning a user triggers notifications, whether the run starts in an open/locked state, what happens with an empty test set, or whether creation is reversible.

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

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

One short sentence, front-loaded, with no filler. It is efficient but so minimal that it reads as under-specification rather than disciplined concision.

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

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

A 7-parameter mutation tool with no annotations and no output schema needs more: the return value (run ID or object?), failure modes for invalid project or test case names, and interaction between test_case_inclusion_type and test_cases are all left unaddressed.

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

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

Schema description coverage is 100%, so every one of the 7 parameters (including the ALL/SPECIFIC inclusion semantics and the deadline format) is already documented in the schema. Per the baseline rule, the description adding no parameter detail still lands at 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?

Specific verb (creates) plus resource (test run) with the scoping location (in a project). It does not, however, distinguish this from siblings such as copy_test_run, upsert_test_case, or update_test_run, so an agent gets the action but not the boundary.

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 prefer this over copy_test_run or update_test_run, and no prerequisites (project permissions, existing test cases, assignment rules). The single clause 'in a project' is the only contextual hint.

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

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

With no annotations, the description carries the full burden and does so: it discloses the 10 requests/second rate limit, that only one run is fetched per call, and a detailed null-semantics caveat for firstResultAt/lastResultAt/durationInMinutes including the ambiguity that null means unknown rather than 'no results yet'. This is behavior an agent could not infer from the schema.

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

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

Front-loaded with purpose and the field list, then bullets for timing fields, with usage guidance and caveats ordered sensibly. Slightly bloated in the caveat section, where the aside about a run that 'still returned real timestamps' is an anecdote that muddies the otherwise crisp null rule.

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 explicit enumeration of returned metadata and timing fields is necessary and present. Combined with the null caveat, rate limit, and single-run constraint, an agent has everything needed to call this, interpret the response, and avoid misreading nulls.

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 test_run parameter already documents that a UUID is required, that a key like 'R-2' is rejected, and how to resolve it via list_test_runs(filter_key=...). The description adds only that 'the endpoint takes one test run per call', so baseline 3 applies.

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

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

States a specific verb and resource ('fetches a test run's details') and enumerates exactly what comes back, including the three timing fields that motivate the tool. It explicitly distinguishes itself from get_test_run_results by calling this 'the direct way' versus deriving timing from per-case resultHistory.

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 concrete triggering questions ('when did this run finish', 'how long did execution take') and names the slower alternative with the reason to avoid it. It also states the precondition to check results before concluding from nulls, which is exactly the decision the agent needs to make after calling.

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

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

No annotations are present, so the description carries the full behavioral burden. 'Fetches' implies a read, and the confirmation-testing framing is genuinely useful, but it says nothing about pagination (100 records/page, fetch_all_pages), the 10 req/s rate limit, or the default response trimming — all disclosed only in the schema 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?

Two short sentences, purpose first and the most actionable hint second. Every sentence earns its place and nothing is buried.

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

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

For a six-parameter retrieval tool with no output schema and no annotations, the description covers what it returns at a high level but omits paging behavior, response shape trimming, and rate-limit pressure — all left to the schema. Adequate, not self-sufficient.

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

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

Schema description coverage is 100%, so the schema already defines status, trim_response, page, and fetch_all_pages in detail. The description adds usage-level meaning for status ('pass FAILED to get only cases needing re-checking') but no format or syntax beyond the schema baseline.

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: fetches the test cases in a test run alongside their latest result. That is clearly distinct from siblings like add_test_run_results or get_test_run_timeline, though it never explicitly differentiates itself from get_test_run_details, 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?

Gives a concrete usage scenario (confirmation testing after a fix) and the exact call pattern that serves it (status='FAILED'). It stops short of naming alternatives or stating when not to use it, so it is clear context without exclusions.

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

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

With no annotations, the description carries the full burden and does: it discloses the cost profile (fetches every results page untrimmed, 100 cases per page vs. one small call), what data source it reads (per-execution timestamps filtered to this run), what is produced, and a real caveat about UTC-day bucketing splitting evening sessions. That is unusually rich behavioral context.

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

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

Front-loaded with the purpose, then the anti-pattern, then the cheaper alternative, then the escalation conditions. Every sentence carries decision-relevant information; length is justified by the risk of picking the wrong 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?

No output schema exists, so the description must explain returns, and it does: first and last execution, the span, distinct active days, daily breakdown, and never-executed cases. Combined with the cost and timezone caveats, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, including a full description of test_run ID format and include_daily_breakdown semantics, so the baseline of 3 applies. The description restates the value of the daily breakdown and mentions never-executed cases but adds no parameter-level format or constraint information beyond the schema.

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

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

States a specific verb and resource: reports when testing in a test run actually started and finished, and immediately separates that from createdAt/lockedAt semantics. An agent can distinguish it from get_test_run_details without opening either schema.

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

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

Explicitly names the wrong approach to avoid (comparing createdAt to lockedAt) and names the sibling alternative (get_test_run_details) with the exact conditions that favor each: null timestamps, distinct-day counts, daily breakdown, or never-executed cases. Nothing 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?

With no annotations, the description carries the full burden. It does not state that this is a read-only operation, how results are ordered, whether archived projects are included by default, or what the pagination/total behaviour is beyond the schema's '100 records per page' note.

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 padding, but it is terse to the point of under-specification rather than efficiently informative.

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

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

For a read-only list tool with full schema coverage the description could reasonably stop early, but with zero annotations an agent gets no confirmation of read-only safety, default (unfiltered) behaviour, or pagination expectations. Those gaps matter here.

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

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

Schema description coverage is 100%, so every parameter is already documented in detail (page semantics, name-contains matching, active/archived values). The description adds no meaning beyond that, which is the baseline-3 case.

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

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

States a clear verb and resource ('Retrives list of projects') and scopes it to filter criteria. Siblings are all test-run/test-case/test-suite resources, so the resource noun alone is enough to separate it; the misspelling 'Retrives' is cosmetic.

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 'based on various filter criteria' gestures at filtering but never says when to use this tool versus other listing tools, nor that all filters are optional and unfiltered calls return everything. No prerequisite or exclusion guidance at all.

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

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

No annotations exist, so the description carries the burden. "Retrieves" implies a read-only operation, but the description says nothing about pagination behavior, result ordering, or what happens with unsupported filters — all of which live in the schema instead.

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: the first front-loads what the tool does, the second front-loads when to use it. No filler or repetition.

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

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

For an 8-parameter list tool with no output schema, the description plus the highly detailed schema is nearly sufficient. It stops short of describing the return shape or page-size limit, but the schema already carries that.

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

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

Schema description coverage is 100% and the schema documents each filter's quirks in detail (suite IDs vs names, custom field types, empty-result semantics). The description itself only says "various filters," adding nothing beyond the structured data, 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 ("Retrieves list of test cases of a project") plus the filtering capability. It carves out a role relative to add_test_run_results, though it does not explicitly distinguish itself from list_test_suites or get_test_run_results, 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?

Gives a concrete scenario ("discover the test case keys a project actually contains before recording results") and names the follow-up tool add_test_run_results. No explicit when-not or alternative-for-the-same-data guidance, so not a 5.

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

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

No annotations are provided, so the description carries the full behavioral burden, yet it discloses nothing about pagination (100 records/page), the special all-pages/trimmed-payload mode of filter_incomplete, or the reduced assignee shape. All of that critical behavior lives only in the schema and is invisible at description level.

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

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

One short sentence, front-loaded and waste-free, but its brevity comes from under-specification rather than economy. It says nothing that the name and schema do not 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?

For a 7-parameter read tool with no annotations and no output schema, the description omits required-parameter context (filter_project), pagination semantics, and the materially different response shape triggered by filter_incomplete. An agent could call it, but would not understand what it gets back.

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 7 parameters well. The description adds nothing beyond 'various filters', landing at the baseline for fully-documented 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?

States a specific verb and resource ('Retrieves list of test runs of a project'), which is clearer than a tautology. However, it does not distinguish this from close siblings like get_test_run_details, bulk_export_test_runs, or archive_test_runs; 'with support for various filters' is too generic to route an agent.

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

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

There is no when-to-use or when-not-to-use guidance, and no alternatives named. The agent has to infer from sibling names whether listing, exporting, or fetching details is appropriate.

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

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

With no annotations, the description carries the burden and does well: it discloses the result shape ('raw rows, count and meta'), the nesting behavior ('Each suite row embeds its sections'), and the pagination limit ('does not fetch further pages'), which is the non-obvious failure mode. It stops short of stating read-only safety, auth requirements, or whether the rows are raw/untransformed in a way that matters for parsing.

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 paragraphs, each front-loaded with its most important claim: what it returns, why to call it, then the pagination caveat. No filler sentences and the limiting constraint comes last where it is easy to catch.

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 read tool with no output schema and no annotations, the description covers purpose, downstream use, return shape, and pagination adequately. It leaves minor ambiguity about whether 'count' is a page count or total, and whether sections themselves can be filtered.

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 page and filter_project are already fully documented in the schema. The description adds no syntax or formatting detail for filter_name or page beyond pointing at the IDs the results yield. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Retrieves list of test suites and their associated sections') with an explicit scope ('in a project'). The following sentence distinguishes it from the sibling list_test_cases by naming it and describing the different job each 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?

Gives a concrete when-to-use ('discover suite and section IDs') and a concrete what-to-do-next ('Pass them to list_test_cases as filter_test_suite and filter_test_suite_section'). It even states an anti-pattern to avoid ('instead of reading the IDs off existing test case rows'), which is exactly the routing guidance an agent needs.

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

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

No annotations exist, so the description carries the full burden and does well: it states the read-only consequence of locking, that results and test-case edits are blocked, the one-run-per-call cardinality, and a concrete rate limit of 10 requests/second. It omits auth/permission requirements and behavior when locking an already-locked run, which are the remaining gaps for a mutation tool.

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

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

Three short paragraphs, front-loaded with the action and its effect, then the workflow rationale, then operational constraints. Every sentence carries information an agent needs — consequences, use case, batching, rate limit — with no filler.

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

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

For a 2-parameter mutation tool with no annotations and no output schema, the description supplies the safety profile (read-only side effect), the operational envelope (rate limit, single-run scope), and the workflow intent. It stops short of error/edge-case behavior — e.g., unlocking a run that isn't locked, or whether unlock fully restores editability — which leaves a small but real gap.

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

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

Schema description coverage is 100% — both 'lock' (boolean toggle) and 'test_run' (ID or name) are already documented in the schema, so the baseline is 3. The description adds only the cardinality constraint ('one test run per call'), which is modest added value rather than new semantics for either parameter.

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

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

Opens with a specific verb and resource: 'Locks or unlocks a test run.' It also clarifies a boundary against the likely-confusable sibling update_test_run by noting that locking is 'otherwise a manual action in the Tuskr UI,' implying this dedicated tool is the only path for lock state. An agent can distinguish it from update_test_run, archive_test_runs, and copy_test_run without reading 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?

Gives a concrete usage context — 'lets an automated workflow seal a run once execution is complete' — rather than a bare when-to-use. It also implies when-not: once locked, results can't be recorded and cases can't be edited, so it shouldn't be called mid-execution. It never explicitly names update_test_run as the alternative for other mutations, which keeps it below 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?

With no annotations, the description carries the full behavioral burden and does so thoroughly: test_cases replaces rather than appends, omitted cases are removed, cases with existing results cannot be removed, the exact HTTP 400 error behavior is disclosed, identifiers must be UUIDs, and the tool does not modify description, deadline, or assignee. This is unusually complete for a mutation tool without 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 long, but the length is justified by the complexity of a mutation tool with no annotations and five parameters. The core behavior and alternatives are front-loaded, and the procedural details are information-dense rather than repetitive.

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 complexity, lack of annotations, and lack of an output schema, the description covers everything an agent needs to invoke the tool correctly: selection semantics, UUID constraints, error behavior, switching rules, unchanged fields, and a brief success 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 already 100%, but the description adds critical meaning beyond the schema: test_cases is the complete selection rather than a delta, switching between ALL and SPECIFIC has different parameter requirements, and every identifier is a UUID rather than a key or name. These are high-value semantics that the schema descriptions alone do not fully convey.

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

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

The description opens with a specific verb and resource: it adds and removes test cases in an existing test run and switches the run's case selection mode. It explicitly distinguishes itself from sibling tools such as add_test_run_results and copy_test_run, so an agent can identify the correct tool without opening another schema.

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

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

It gives explicit when-to-use guidance, including negative guidance not to use add_test_run_results or copy_test_run for this purpose. It also provides step-by-step procedures for adding and removing cases and states exactly when test_cases is required versus omitted for ALL and SPECIFIC modes.

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

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

With no annotations, the description carries the full burden and does most of it well: partial-update semantics ('only the fields you pass are sent'), the inability to clear a field to empty, and the surprising side effect where a mistakenly-passed suite ID plus create_missing_suite creates a new suite. Still silent on permissions/auth requirements and overall idempotency guarantees, which keeps it short of 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?

Front-loaded with the core operation, then bullets the ID modes, then the field-merge and suite-lookup caveats. Slight redundancy in 'This tool can both create new test cases and modify existing ones' restating the opening sentence, but density of useful content is high.

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

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

For a 12-parameter dual-mode mutation with no output schema, it covers the decision-critical semantics: mode selection, merge behavior, name-lookup pitfalls, and required name on create. It does not describe what the returned test case looks like or what error surfaces when both IDs are omitted, leaving minor gaps.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds genuine semantics the schema does not: the mutual-exclusivity/at-least-one constraint on test_case_id and external_id, which one creates vs updates, and the name-only lookup rule for suite and section that the schema flags only as '(not its ID)'.

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

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

Opens with a specific verb+resource ('Creates a test case or updates an existing one') and immediately scopes the dual-mode behavior. It explicitly contrasts itself with the sibling add_test_case, so an agent can route between them without opening either schema.

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

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

Gives explicit selection rules for test_case_id vs external_id, states that name must be passed when a create may occur, and names add_test_case as the alternative for the ID-lookup path. The when-not guidance around create_missing_suite/section with mistaken IDs is exactly the kind of trap an agent needs warned about.

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