TestDino MCP

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

Annotations only declare readOnlyHint=false and destructiveHint=false. The description goes further by disclosing side effects: the assignee starts watching the test and is notified on state changes, plus the exact error string returned when the target is not a project member.

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 tightly written sentences with no filler; the primary action and identifier options come first and the notification side effect and error condition follow.

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 three-parameter mutation with no output schema, the description covers the action, the identifier forms, the unassign path, side effects, and the principal error case. Only minor items such as permission requirements are left implicit.

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 three parameters, including the "me"/email/null semantics of assignee. The description restates that behavior rather than adding format or edge-case detail beyond it, 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 opens with a specific verb and resource: 'Assign a test to a project member'. It also states the accepted identifiers and the unassign case, which clearly separates it from siblings like watch_test or update_testcase.

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 the three valid modes (email/user id, "me", null to unassign) and the failure condition for non-members. It does not name alternative tools, but the when-to-use conditions for this tool are explicit.

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

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

Goes well beyond the readOnlyHint=false/destructiveHint=false annotations by disclosing the write-permission and plan-feature prerequisites, the per-item result shape, and the critical partial-failure semantics ('one bad row never fails the batch'). The instruction to always check each item's success is exactly the kind of non-obvious 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?

Front-loads purpose and scope, then prerequisites, then return/failure behavior, then the id gotcha. Dense and information-rich with no filler sentences; 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 carries the return contract (per-item success/error/link) and the failure model, plus permission and plan prerequisites and correct id sourcing. Nothing essential for a correct bulk mutation call 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 coverage is 100%, so the baseline is 3, but the description adds real value: it clarifies manualTestCaseId is the internal _id (tcm_tc_…), not the TC-123 key, and specifies the provenance of pwTestId/fullTitle. These are semantic details that prevent mis-population of the links array.

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

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

States a specific verb (Link), the resource (manual case ↔ automated test pairs), and the scope (up to 500 in one call). It is immediately distinguishable from the singular sibling link_automated_test through the bulk framing and the 500-row cap.

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 operational context: requires write permission and the automation_linking plan feature, and directs the agent to source pwTestId + fullTitle from list_automated_tests. It does not explicitly state when to prefer this over the single-item link_automated_test sibling, but the 'up to 500 ... in one call' framing makes the choice inferable.

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 destructiveHint=false, so the mutating-but-safe profile is covered. The description adds real value beyond that: it discloses an internal precondition check and an idempotent early-return path (already_connected), which an agent cannot infer from annotations alone.

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

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

Two tightly written sentences with zero filler, and the core action is front-loaded before the conditional behavior. 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 bears the burden of describing returns, and it only covers the already_connected branch. What the tool returns on a successful OAuth start (e.g., an authorization URL or state token) is unstated, which is a meaningful gap for an agent that must act on the result.

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 the provider enum and the orgId scope note, so the schema carries parameter meaning. The description adds only a generic 'for a TestDino project' reference and no format or scoping details 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 gives a specific verb and resource: 'Start the provider OAuth/connect flow for a TestDino project.' This is unambiguous about what the tool does. It does not, however, name or contrast itself with the closely related sibling get_integration_status, which would have sharpened selection.

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 through the pre-check behavior ('checks current status and returns already_connected instead of starting OAuth when the provider is connected'), which tells the agent the tool is safe to call even when already connected. But there is no explicit when-to-use guidance versus get_integration_status for a pure status check.

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 declare readOnlyHint=false and destructiveHint=false, so the agent already knows this is a non-destructive write; the description adds useful context that a preview mode exists and that provider field requirements should be verified first. It does not, however, state auth needs, what happens on partial failure, or how duplicate creation is prevented beyond what the schema says.

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

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

Three short sentences, front-loaded with the core action and followed by scope and a prerequisite. Zero padding, though the source-type list is partially redundant with the schema enum.

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 9-parameter, nested-object create tool with no output schema and modest annotations, the description covers the action, scope, and the key prerequisite well. The schema carries the heavy lifting on parameters and the preview flag, leaving only return-shape/error details 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 parameter is already documented in the input schema, including the rich 'target' description with provider-specific aliases. The description's enumeration of source types largely restates the schema's enum, so it adds little beyond the 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?

States a specific verb (Create) and resource (external issue/task/item) and pins its scope with 'linked to a TestDino entity'. It enumerates the supported source types, which helps distinguish it from the sibling get_external_issue. It stops short of explicitly naming that sibling as its read counterpart, so it lands 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?

Gives a concrete prerequisite: 'Check get_integration_status first for required provider fields,' naming the sibling and the condition that routes to it. It does not describe when NOT to use this tool (e.g., when only reading existing issues), but the positive usage guidance is explicit.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation profile is known; the description adds the write-permission requirement and the important asymmetry that tags here must be a JSON array rather than the comma-separated filter form used elsewhere. It does not say what happens on duplicate names or whether creation is idempotent, so it falls 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-loads the action and the permission requirement, then groups the selectionMode, releaseId, note and tags details in short clauses. The IMPORTANT tags sentence is slightly redundant with the schema but is deliberately emphasized, so it 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 15-parameter creation tool with no output schema, the description covers the decision-relevant params (selectionMode, releaseId, tags, note) and leaves structural ones like links, linkedIssues, forecast and includeUnsorted to the fully-documented schema. Nothing critical is missing, though the description never indicates what is returned on success.

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 every parameter including the tags array constraint and the selectionMode default. The description restates selectionMode, releaseId and note, and its tags warning duplicates the schema text almost verbatim, so it adds little genuinely new parameter meaning beyond the cross-tool format contrast.

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: "Create a new manual test run." The create-vs-update split against update_manual_run is implicit in the verb, and the closing contrast with list_manual_runs reinforces which sibling it is not, but no sibling is named as an alternative for the create action itself.

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 the key prerequisite ("Requires write permission") and explains when each selectionMode applies, including which params pair with "selected". The tags sentence explicitly contrasts this tool's input form with list_manual_runs' filter form, which is a real cross-tool usage rule, though no explicit "do not use this when…" guidance is 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 only declare readOnlyHint=false and destructiveHint=false, so the description carries extra weight and does add real context: write permission required, exact-match suite resolution, default step format, and the MCP attachment restriction. It stops short of describing what happens on duplicate titles or what the response returns, which keeps it below 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?

Content is front-loaded — purpose first, then the mandatory prerequisite, then format details and the attachment caveat — and every clause conveys actionable information. The dense run-on formatting and all-caps emphasis make it slightly harder to scan than an ideal entry, but nothing is 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 19-parameter mutation tool with no output schema, the description covers the highest-risk gaps: suite resolution, step encoding, permission requirement, and the attachment dead end. It does not explain how to obtain projectId or what the created test case identifier looks like on return, which an agent would otherwise have to discover.

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 68% schema coverage across 19 parameters, the description meaningfully compensates: it documents the two distinct step object shapes ({action, expectedResult, data} vs {event, stepDescription}) that the schema leaves ambiguous via additionalProperties, and explains when to set testStepsDeclarationType="Gherkin". It only lightly covers the many property-style fields (priority, severity, layer), which the schema already enumerates.

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 opening sentence gives a specific verb and resource ("Create a new manual test case"), which cleanly separates it from sibling tools like update_manual_test_case and create_manual_test_suite. The rest of the text reinforces the create semantics by specifying the payload shapes that must be supplied.

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 states an explicit prerequisite — "MANDATORY FIRST STEP: always call list_manual_test_suites()" — plus the reason (suiteName must be an exact match), and it redirects out-of-scope work to the UI when attachments are needed. That is unusually concrete when-to-use and when-not guidance.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered structurally. The description adds value with 'Requires write permission' and the ID-sourcing prerequisite, but says nothing about duplicate-name handling, what happens to existing suites, or whether the new suite ID 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 sentences, zero filler, with the core action front-loaded and the nesting prerequisite second. 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?

For a simple create tool with annotations covering the write/non-destructive profile and no output schema, the description covers purpose, permission, and the nesting workflow. It omits what the call returns (notably the new suite ID, which an agent would need for follow-on creates) and leaves the description parameter unexplained.

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 50%: name and projectId are documented, but parentSuiteId has no schema description. The description compensates by explaining nesting semantics for parentSuiteId and where to obtain a valid ID, which is real meaning beyond the schema. The 'description' parameter remains undocumented in both places, keeping it from a 5.

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 suite folder for organizing manual test cases'), which cleanly distinguishes it from create_manual_test_case and create_manual_run in the sibling list. The scoping phrase 'organizing manual test cases' tells the agent this is a container, not a case.

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

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

Gives a clear conditional path: use parentSuiteId to nest under an existing suite and fetch that ID from list_manual_test_suites() first. This routes the agent to the right sibling for the dependency. It does not state when NOT to nest (e.g., root-level suites) or address duplicate-name situations, so it stops 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 only tell the agent this is a non-read-only, non-destructive write; the description adds substantive behavior beyond that: write permission is required, nesting is capped at 3 levels, isStarted/isCompleted are independent of startedAt/completedAt, and testers must be org members passed as User _ids. It does not describe the returned resource or any conflict/failure behavior, keeping it out of the top band.

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-loads the core action and permission requirement, then groups the remaining guidance in a compact set of sentences where each clause carries a distinct constraint. The final sentence is slightly run-on, but no sentence is 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 17-parameter mutation tool with nested objects and no output schema, the description covers the non-obvious fields (nesting depth, flags vs timestamps, tester identity rules) while the schema handles the rest at 76% coverage. Return-shape and failure behavior are absent, but the agent has enough 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?

With 76% schema coverage the schema already documents most fields, yet the description adds genuine semantics: the 3-level nesting limit for parentReleaseId, the independence of isStarted/isCompleted from the timestamp fields, the ISO format for startDate/endDate, and the org-membership plus User _id requirement for testers. It leaves the type, note, linkedIssues and buildTarget sub-fields to the schema, so it does not fully compensate but adds clear value.

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 release"), which distinguishes it clearly from the read/update siblings list_releases, get_release and update_release. It stops short of explicitly naming an alternative, but the verb+resource pairing 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?

Provides real prerequisites ("Requires write permission") and a structural constraint (nesting via parentReleaseId, max 3 levels), which implies when the tool applies. It never says when to use this versus update_release or what conditions would make creation inappropriate, so guidance is present but incomplete.

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

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

Annotations only declare readOnlyHint=false / destructiveHint=false, so the description carries real added weight: write-permission requirement, server-side email resolution for assigneeUserId, automatic normalization of state values so UI colors render, and the fact that findings and attachments are simply not available over MCP (400 refusal). These are non-obvious behaviors an agent would otherwise discover only by failing.

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, then prerequisites, then per-parameter gotchas, ending on the highest-risk warning (tags format). A couple of clauses restate schema text verbatim ("estimate is in minutes", the tags example), which is mild redundancy, but nothing is 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 13-parameter mutation with no output schema, the description covers the highest-risk unknowns: permissions, unsupported fields, and the tags format trap. It does not say what the call returns (e.g. whether the new session _id comes back), and the config/environment parameters are undocumented in both schema and description, leaving a small 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 85%, so the schema already does most of the work; the description still adds value by explaining that mission accepts rich HTML, that assigneeUserId takes either a User _id or an email resolved against TestDino users, and that estimate is in minutes. The tags array-vs-comma-separated warning is repeated from the schema but is framed as a failure mode, which is useful reinforcement.

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: "Create a new exploratory testing session." It is immediately distinguishable from siblings like list_sessions, get_session, and update_session, and the mention of list_sessions' comma-separated tag filter further separates the create path from the list path.

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?

States a hard prerequisite ("Requires write permission") and gives explicit fallback routing for unsupported work: findings must be added in the UI, attachments are refused. It does not explicitly say when to call this versus update_session, but the create-vs-update distinction is inferable from the name and the rest of the guidance is concrete.

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?

Goes far beyond the lone readOnlyHint annotation: discloses the 409 AMBIGUOUS_IDENTITY ambiguity protocol, lazy AI generation with 'in_progress' polling via get_ai_insights, transient-5xx vs terminal-4xx handling, that fixes are recommendations to validate against live code, and that the debugging_prompt must be read first. Rich operational context the annotations do not carry.

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-loads purpose and the key alternative, but at roughly 350 words it sprawls and repeats itself — the guidance that get_debug_evidence 'is the first call' appears both mid-description and again in the trailing Workflow paragraph. The IMPORTANT block and disambiguation protocol also overlap 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 6-parameter tool with no output schema, the description compensates fully: it enumerates the returned evidence (execution history, failure patterns, error messages, debugging_prompt, ai_fixes) and the error/status paths. Nothing an agent needs to invoke 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: testcase_id is the pw_test_id and wins over name/path, a title can match several tests across projects/files, testrun_id only applies with include_ai_insights, and how to resolve ambiguity via the returned candidates.

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 with scope: 'AI-assisted root cause analysis for a failing or flaky test', and enumerates what it returns. It explicitly distinguishes itself from get_debug_evidence and get_ai_insights, so an agent can route among siblings 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 explicit when-to-use triggers ('why is test X failing?', 'debug test X', 'is test X flaky?'), names the alternative to call first (get_debug_evidence), and states the narrow condition for using this tool instead ('only for the stored AI suggestions or the full execution history').

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

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

Annotations only declare readOnlyHint=true, so the description carries the behavioral burden and does so thoroughly: lazy generation, the full status vocabulary ('not_generated'/'queued'/'processing'/'failed'/'completed'/'disabled'/'in_progress'/'unavailable'), which statuses are terminal, polling cadence, and transient-vs-terminal error interpretation via upstream statusCode.

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 three-mode frame and dense with actionable detail, with no filler sentences. It is long, and the polling advice ('poll this tool every few seconds') is restated later as 'each also serves as the poll target', a minor redundancy that keeps it out of the top band.

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?

There is no output schema, so the description must describe returns — and it does, enumerating recommendations/quick fixes, failure categorization, clusters, new-failure cards, the error-analysis table, and the LLM run summary per mode. Nothing needed to call it correctly, or to interpret its gaps, 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 coverage is 100% and each parameter already names its mode, so the baseline is 3. The description adds composite meaning the per-parameter schema cannot express: which parameter combinations yield which payload, and that testrun_id is shared between run mode and case mode.

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 ('TestDino's AI Insights') and immediately decomposes it into three unambiguous modes keyed on parameter combination. An agent can distinguish case mode, run mode, and project-overview mode without opening the schema, and the mention of get_run_details/debug_testcase positions it against siblings.

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 routes each mode to a task: 'Use the project overview to answer "what should we fix first?"; the run mode to triage one run; the case mode to get fixes for one failing test.' It also states the prerequisite (AI features enabled in Settings → AI) and that this tool is the poll target after the other tools report a pending status.

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 declare readOnlyHint=true and the description's 'Read-only' framing is consistent with that. Beyond the annotation, it discloses workflow constraints (must call context first before writing findings, health() prerequisite) and that action='get' can write a local markdown file resolved from TESTDINO_MCP_WORKSPACE or cwd. It does not contradict the read-only hint; the local file write is a genuine behavioral detail annotations don't capture.

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 purpose and modes, then trigger rules, then the flow. Dense but purposeful, though there is mild redundancy in the emphatic phrasing around not calling the tool and not mentioning TestDino even for Playwright code.

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 multi-mode read tool with no output schema, the description supplies the complete operating picture: mode selection, trigger gating, prerequisites, and the three-step flow ending in the sibling submission tool. Nothing an agent needs to invoke 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 all 8 params, establishing a baseline of 3. The description adds value beyond the schema by tying actions to a numbered flow and clarifying branch semantics (required for context unless detected from git, optional filter for list) and the FIRST-action requirement for context mode.

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 ('read-only TestDino Playwright audit reads') and enumerates the three modes with distinct semantics for each action value. It clearly separates this tool from siblings like submit_audit_report and health by naming when each alternative applies.

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?

Explicit TRIGGER RULE defines when to use this tool (user must EXPLICITLY name TestDino) and when NOT to (generic 'audit', 'code review', 'security audit'), including a fallback behavior for non-Playwright targets. It also names the prerequisite (health() when projectId is unknown) and the exact ordered flow through the sibling submit_audit_report.

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

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

The readOnlyHint annotation only tells the agent the tool is safe to call. The description adds substantial behavioral context beyond that: the verdict says whether a failure repeats but never why, so it rules out fixes rather than pointing at a cause; the boundary reframes the question as 'what changed between these two runs'; artifact links expire on a minutes scale, so agents should download immediately and call again for fresh links rather than treating expiry as missing artifacts.

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 most important guidance ('Start every failing-test investigation here'), followed by a tight enumeration of returns and behavioral caveats. Every sentence earns its place: none repeat the schema or annotations, and each adds actionable context for an agent.

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 carries the burden of explaining what the tool returns, and it does so completely: verdict, failure signatures, regression boundary, and artifact links. It also discloses key constraints (verdict limits, boundary utility, link expiry) that an agent needs to use the tool correctly, making it sufficient for this complex, eight-parameter tool.

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

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

Schema description coverage is 100%, so the schema itself fully documents all eight parameters, including enums and format trade-offs. The description does not add per-parameter meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb-plus-resource framing ('One call returns the whole cheap tier of the evidence ladder') and enumerates exactly what the tool returns: flake verdict, per-attempt signatures, regression boundary, and artifact links. It also positions itself as the entry point for failing-test investigations, which clearly distinguishes it from siblings like get_flake_verdict or get_trace_analysis that return narrower slices.

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?

Strong guidance is given: 'Start every failing-test investigation here' and 'Read all of it before forming a hypothesis.' It also explains when to call again ('call this again to mint fresh ones'), which is a useful workflow cue. However, it does not explicitly name alternatives or when-not-to-use this tool, so a 4 rather than 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?

The readOnlyHint annotation already establishes the safe-read profile, so the description only needs to add context beyond that. It adds the 'previously linked' prerequisite, which is genuine value, but says nothing about the return payload, partial-failure behavior across multiple IDs, or per-provider quirks (e.g., Jira site selection via target).

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

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

One tight sentence with the action and resource front-loaded and no filler. The trailing example clause ('Jira keys TD-17 or Linear issue identifiers') borders on redundant with 'provider IDs or keys', but it earns its place as illustration.

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

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

For a 4-param tool with a nested object and no output schema, the description is minimally adequate. It explains the lookup contract but not what comes back (issue detail shape), how batch results are ordered or how failures surface, and it never touches the Jira `target`/Atlassian site dimension, which is a real usage decision for callers.

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 100% schema description coverage, the schema already documents all four parameters including the enum, the 20-item cap, and the Jira `target` object. The description adds key-format examples (Jira 'TD-17', Linear identifiers) that go slightly beyond the schema, but it omits `target`, `projectId`, and the batching limit entirely. 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 (fetch) and resource (external issue/task details) plus the lookup mechanism (provider IDs or keys previously linked to TestDino). The 'fetch' vs. the sibling 'create_external_issue' is implicitly distinguishable, but the description never names the sibling to sharpen 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?

'Previously linked to TestDino' implies the prerequisite that the issue must already be linked, which is useful when-to-use context. However, there is no explicit when-not guidance, no mention of the alternative create_external_issue for unlinked issues, and no handling guidance for unsupported providers.

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

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

Annotations only declare readOnlyHint=true, and the description adds substantial context beyond that: the exact semantics of each verdict, the precondition about retries, and an explicit scope limit stating the verdict describes behaviour and not cause, and cannot tell you where the fix goes. This is exactly the disclosure that helps an agent avoid over-reading the output.

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 core definition and the routing instruction are front-loaded, and the verdict semantics follow in a compact parenthetical. It is somewhat long for a three-parameter tool and the closing sentences about cause-vs-behaviour are a little repetitive, but each part carries real 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?

There is no output schema, so the description carries the return-value burden, and it does: it names all three verdicts, explains what each means, and mentions the per-attempt signatures returned alongside. Prerequisites and the relationship to get_debug_evidence are covered, leaving nothing an agent needs 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% and testrun_id already documents its omit-to-default behaviour, so the baseline is 3. The description adds meaning by framing the whole comparison as happening 'within one run', which explains why the run-scoping parameter matters, but it does not add format or edge-case detail beyond that.

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: it decides whether a failing test behaves the same way every time by comparing retry attempts within a run. It is clearly distinguishable from siblings like get_trace_analysis and get_debug_evidence, and it even enumerates the three possible verdicts so the agent knows exactly what decision this tool yields.

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 routes the agent: if debugging a failing test, call get_debug_evidence first because it returns this verdict plus the regression boundary and artifact links, and calling this separately afterwards repeats work. It also states a prerequisite (a test that ran with retries enabled) and the inconclusive condition for single attempts.

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

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

Annotations already declare readOnlyHint=true, so the safe-read nature is covered structurally. The description adds the useful framing that this is a precondition probe spanning five providers, but discloses nothing about the response shape or the behavior of includeCreateOptions (which triggers provider metadata resolution).

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; the what is front-loaded and the sequencing instruction follows immediately. Every clause earns its place.

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

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

For a read-only probe with no output schema, the description covers purpose and invocation timing but never hints at what the status result contains or that includeCreateOptions returns create metadata (projects, issue types, required fields). That omission is the main gap in an otherwise adequate definition.

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

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

Schema description coverage is 100% and the nested 'target' object, provider enum, and includeCreateOptions flag are all documented in the schema. The description adds no parameter-level detail beyond the provider list, 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 (check) and resource (integration connection status) scoped to a TestDino project, and enumerates all five supported providers (Jira, Linear, Asana, monday.com, GitHub). An agent can distinguish it immediately from connect_integration and create_external_issue.

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 'Call this before connect_integration or create_external_issue,' naming the two sibling tools it gates and the sequencing condition that selects it. This is exactly the when-to-use 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?

Annotations already declare readOnlyHint=true, so the safe-read profile is covered by structured data. The description adds the shape of the response (stats, contributors, attachments, linked issues), which is genuine value, but it discloses nothing about permissions, rate limits, or behavior for missing/archived runs. Adequate but not rich.

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

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

Two sentences, no filler, with the resource and its returned contents front-loaded and the parameter caveat placed last where it belongs. The field enumeration is dense but each item earns its place given there is no output schema.

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

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

With no output schema, the description carries the burden of telling the agent what comes back, and it does so with a concrete field list plus the accepted ID formats. The main remaining gap is disambiguation from sibling run-detail tools.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, including the dual-format runId. The description repeats that same runId detail rather than adding new meaning (e.g., what happens if a RUN-N id is ambiguous across projects). Baseline 3 is correct.

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

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

Names a specific verb and resource ('Get the full details of one manual test run') and enumerates the returned fields, so the agent knows exactly what payload to expect. It does not, however, distinguish itself from close siblings like get_run_details or list_manual_runs, 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?

The singular 'one manual test run' implies this is the single-run fetch as opposed to list_manual_runs, which is a reasonable implicit cue. But there is no explicit when-to-use, no exclusions, and no routing guidance against get_run_details or get_run_error_clusters.

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, but the description adds real behavioral detail beyond that: version history and execution results are read-only and cannot be mutated, and comments/linked issues are added through update_manual_test_case instead. This clarifies the mutation boundary that the bare annotation does not, though it says nothing about result size, pagination, or auth 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?

Front-loads what the tool returns, then moves to the caseId affordance and the read-only/mutation boundary. Four sentences, all functional, though the opening enumeration is dense and the caseId sentence partially duplicates 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?

With no output schema, the description carries the burden of describing the return payload, and it does so thoroughly (including activity sub-collections). It is nearly complete for a 2-param read tool; only pagination/volume behavior for 'execution results across all manual runs' is 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 both parameters (caseId, projectId) are already documented. The description's note that caseId accepts either the internal _id or a 'TC-123' style ID merely restates the schema, adding no syntax or constraint the agent cannot already read. Baseline 3 applies.

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

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

Specific verb+resource ('Get the full details of one manual test case') followed by an explicit field enumeration (steps, preconditions, postconditions, metadata, linkedIssues, activity). The 'one' scope implicitly separates it from list_manual_test_cases, but the sibling is never named, so the differentiation is left to inference rather than stated.

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

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

Gives a clear workflow directive: 'Call this before update_manual_test_case to see current steps, comments, and linked issues before modifying them.' That is actionable context for when to reach for this tool. It does not state when NOT to use it (e.g., enumerating many cases), so it stops 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?

Goes well beyond the readOnlyHint annotation: it explains that any section may be {status:"unavailable"} and that this means the read failed rather than zero/none, warns that a partial-coverage token sees only some projects and no org-wide totals, and instructs the agent to relay quota.message verbatim. This is exactly the behavioral context 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?

Front-loaded with the core purpose and densely packed with non-redundant detail; every sentence carries weight (return shape, unavailable semantics, token scoping, read-only boundary). It is a long single block, but not 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?

With no output schema, the description carries the full description burden and does so: it describes the return fields, the unavailable-status edge case, the token-scoping caveat, and the quota.message contract. Nothing needed to call or interpret it 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 coverage is 100% (baseline 3), but the description adds meaning: orgId is taken from health, and `window` scopes the org test health pass/fail/flaky view. These details exceed the schema's terse field descriptions.

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

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

States a specific verb+resource ('Answer plan and quota questions for one organization') and enumerates exactly what it returns (plan, executions limit/used/remaining, reset date, seats, projects, top-ups, org test health). This clearly distinguishes it from siblings like get_project_details and health.

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 ('answer plan and quota questions'), a prerequisite (takes orgId from health), and an explicit exclusion (buying executions or changing the plan happens on the billing page, never through this tool). It does not name a sibling alternative, so it falls short of a 5.

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

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

Beyond the readOnlyHint annotation (restated as 'Read-only', which earns no credit), it discloses non-obvious behavior: the three health.dataState values and what each means for reporting, the {status:'unavailable'} convention for failed section reads, and an explicit prompt-injection warning about test titles/error excerpts. These are exactly the traits an agent cannot infer from structured fields.

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

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

The purpose and routing are front-loaded before the long content enumeration, and nearly every clause carries information. The drawback is that the core is one very dense run-on sentence, which makes it slower to parse than a short bulleted breakdown would be.

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?

There is no output schema, so the description must carry return-value semantics, and it does: it lists every section, defines dataState states, and explains the unavailable status. An agent has enough to answer project-level questions and to report missing data 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 projectId and window are already documented, and the description's branch note ('narrows the flaky list and CI suggestions only') essentially restates the schema's branch description. No new syntax or format detail is added 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?

Opens with a concrete framing ('how is this project set up and doing') and then enumerates the exact contents: health summary, executions, integrations, branch→environment mapping, top-10 flaky/slow/failing tests, tag health, CI suggestions. It explicitly contrasts itself with get_testcase_details and list_testcase, so an agent can distinguish it from siblings without opening a 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?

States 'Use it for project-level questions' and names the two alternatives with their selecting conditions ('drill into one test with get_testcase_details or list more with list_testcase'). It also scopes the branch parameter ('narrows the flaky list and CI suggestions only'), which tells the agent when filtering actually applies.

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

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

Annotations only give readOnlyHint, and the description confirms 'Read-only' while adding substantial non-obvious behavior: null/runCount semantics, the distinction between 'no runs' and a failed lookup, the {status:'unavailable'} sentinel with an instruction never to report 'no runs', and a prompt-injection warning about PR titles. This is far beyond what the annotation conveys.

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 purpose, then mode-specific behavior, then edge-case semantics. Dense but nearly every clause carries actionable information; the prompt-injection warning is justified given PR titles are user-controlled, though the text is close to the upper bound of comfortable length.

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 carries the return-shape burden and does so: it names the fields returned in both list mode (status, author, latest test run) and detail mode (branches, merge state, size, latest test runs), and explains the failure sentinels. Nothing an agent needs to call this 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 coverage is 100%, so baseline is 3, but the description adds real disambiguation: pr_id is the `prId` from the list and explicitly 'not the PR number', which the schema alone only hints at via the example format. The 20-PR cap and default listing behavior are also stated, though limit/status semantics stay in 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+resource ('Pull requests of the project's connected GitHub/GitLab repo') and splits into two clearly distinct modes (list vs. single-PR detail). An agent can tell exactly what comes back in each mode 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?

Explicitly says to omit pr_id to list and to pass a pr_id for detail, plus a concrete recovery path: when latestRun is null, 'call again with its pr_id' for a definite answer. It also explains when the list may be short (syncing: true). No sibling tool overlaps this resource, so no alternative-tool routing is needed.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description goes beyond that by disclosing return-side behavior: it includes a full change history (events) and a scoped 90-day window of coveredRuns (total plus the 10 latest), which is genuinely useful context about result scope and completeness.

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 verb+resource summary before the field enumeration, with no filler. The trailing explanatory clause about why runs were covered is slightly dense but earns its place by clarifying the coveredRuns 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?

With no output schema, the description carries the return-value burden and does so reasonably well by naming the fields, the event history, and the coveredRuns window and count. For a simple two-parameter read tool this is nearly complete, though pagination or linking guidance would round it out.

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

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

Schema description coverage is 100% for both parameters, including the origin of quarantine_id ("as list_test_controls returns it"), so the schema does the heavy lifting. The description adds no parameter-level meaning, making the baseline 3 appropriate.

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

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

The description gives a specific verb and resource ("Read one quarantine") and enumerates the returned fields (reason, assignee, end date, coverage, state, event history), so an agent immediately knows this is a single-record read rather than a list or mutation. It does not explicitly name sibling alternatives (list_test_controls, update_quarantine), so it falls short of the 5-level sibling differentiation.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no routing to alternatives such as list_test_controls or get_test_controls for other views. The only hint of usage is the schema note that the id comes from list_test_controls, which is not guidance on when to reach for 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?

With readOnlyHint=true already covering the safety profile, the description adds genuinely useful behavior: stats are rolled up across 'all runs in this release and its descendants', and releaseId tolerates two identifier formats. It stops short of disclosing permissions or size/aggregation limits, so 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 sentences, zero filler, and the payload description is front-loaded ahead of the identifier note. Every clause carries information an agent needs.

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 describe the return value — and it does so thoroughly by enumerating the returned fields and the roll-up semantics. For a two-parameter read-only tool, nothing required to call 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 coverage is 100%, so the baseline is 3, but the description earns extra credit by spelling out the accepted ID formats and giving a concrete example ('MS-12') for releaseId, which the terse schema field description lacks. projectId receives no additional explanation, keeping it out of 5 territory.

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

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

States a specific verb (Get) and resource (one release) and enumerates exactly what is returned: dates, status, linked issues, parent/root, and rolled-up progress stats. The 'one release' framing cleanly separates it from the sibling list_releases and release-mutation tools without needing to name them.

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

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

Usage is only implied: an agent can infer this is for fetching details of a known release, but the description never says when to prefer it over list_releases or get_run_details, nor any preconditions. Adequate but with a clear gap in routing 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 only declare readOnlyHint; the description supplies the real behavioral payload beyond that: the returned fields (selected/in_scope, lines, missing ids, unusable titles, null command), what rerun_mechanism values ('in-run' vs 'new-workflow', only_failed_tests, reason codes) imply, and the two distinct 409 conditions with retry guidance. Nothing is contradicted and a great deal of non-obvious behavior is disclosed.

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

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

The tool-specific content is front-loaded and dense with signal, but it is followed by a large generic approval-policy block about editing files, running tests and committing that applies to any tool and is largely irrelevant to a read-only resolver. That appended boilerplate dilutes an otherwise tight opening paragraph.

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?

There is no output schema, so the description must carry the return contract, and it does: it names the fields, explains the null-command case, defines rerun_mechanism values and their conditions, and enumerates the 409 error codes. For a read-only, five-parameter, selector-style tool, an agent has everything needed to call it and interpret the result.

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 runId, scope, testIds (override semantics) and excludeTestIds (ignored when testIds set); the baseline is 3. The description restates the scope choices ('its failed tests, its flaky tests, both, or an explicit list') but adds no format, default, or boundary detail beyond what the schema already carries.

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

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

States a precise verb and resource: 'Resolve which of a finished run's tests a re-run should execute', and enumerates the selection modes (failed, flaky, both, explicit list). It explicitly differentiates itself from the sibling rerun_test ('To start the run in CI, call rerun_test'), so an agent can route correctly 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 clear routing to the alternative (rerun_test starts the run; this tool only resolves) and states the precondition that the run must be finished via the 409/RUN_NOT_FINALIZED and SELECTION_NOT_READY cases with a retry hint. It does not explicitly exclude other read siblings such as get_run_details, so it falls just short of a full when/when-not map.

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?

Read-only annotation is consistent, and the description adds substantial behavioral context annotations cannot carry: is_swarm semantics (distributed CI, machines[], imbalance_ratio, could_not_execute_specs meaning the run is not a clean pass), lazy AI payload generation with status values ('processing'/'not_generated'/'unavailable'), and the 5xx/4xx transient-vs-terminal retry rule.

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?

Long but front-loaded: the core purpose and lookup modes come first, then swarm specifics, then AI-insight polling. Each block carries non-redundant information, though density is high and a few clauses (e.g. the hard-floor aside about spec files) could be trimmed 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?

With no output schema, the description carries the full burden of describing returns and does so thoroughly for every mode: standard run contents, swarm-specific fields, and the ai_insights payload structure. An agent has everything needed to call it correctly and interpret the response.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by illustrating syntax (counter="47", testrun_id="id1,id2,id3") and restating the batching cap of 20. It also clarifies that include_ai_insights is single-ID only, but most of this is already present in the schema descriptions.

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

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

Opens with a specific verb+resource ('Get the full breakdown of one or more test runs') and enumerates exactly what comes back: test statistics, error category breakdown, suite list, and all test cases. This clearly separates it from list_testruns (which lists) and get_ai_insights (which drills into AI payloads).

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 an explicit workflow ('list_testruns() → pick IDs → get_run_details()'), tells the agent which parameter to use for ID vs human-readable lookup, and routes to alternatives when appropriate ('poll get_ai_insights(...) until completed instead of re-calling this tool'). When-to-use and when-not-to-use are both covered.

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

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

Annotations only declare readOnlyHint=true, so the description carries the behavioral load and does so richly: it discloses clustering semantics (failed/timed-out cluster on final-attempt error, flaky on pre-recovery error), the fixed category set, and the special unclustered bucket for blank/unfingerprintable errors.

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 behavior, then usage, then workflow. It is dense and long, but nearly every sentence adds distinct value; the only mild redundancy is restating categories already implied by the clustering 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?

With no output schema, the description still fully characterizes the return shape: error clusters (signature + affected tests + category), an unclustered bucket, a per-category rollup, and run totals. An agent needs nothing more to call and interpret it.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by explaining what status narrows ('Optionally narrow with status="failed" or status="flaky" (default "all")'), giving the filter operational meaning rather than just an enum list.

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 (group one run's failing tests by shared error signature/fingerprint) and immediately scopes it to a single run with 'computed for that run only'. This scope emphasis distinguishes it from broader siblings like get_run_details and list_run_test_cases.

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

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

Explicitly names the questions it answers ('what are the distinct failures in this run?', 'which error affected the most tests?') and contrasts cost against paging every failed case. It even supplies the workflow: list_testruns() → pick a testrun_id → get_run_error_clusters().

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?

readOnlyHint=true already establishes the safe-read profile, so the description's job is only to add context. It adds the returned-field inventory, which is useful given there is no output schema, but says nothing about whether a missing/unknown sessionId errors, what permissions are required, or how attachments/findings are shaped.

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. The purpose and returned fields come first and the ID-format note follows as a second, clearly bounded sentence.

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

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

With no output schema, the field enumeration meaningfully tells the agent what it will receive, and the readOnly annotation covers the safety dimension. It is missing error/not-found behavior and permission requirements, but for a two-parameter read tool it is close to complete.

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

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

Schema description coverage is 100% and the schema already documents sessionId as "Internal _id or counter-style ID"; the description largely restates this while adding a concrete example ("SES-12"). The projectId parameter receives no additional scoping or format detail, so this is close to the baseline of 3 with a marginal edge from the example.

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

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

Specific verb (Get) plus resource (one exploratory session) with an enumeration of the fields returned, which makes the tool's output easy to anticipate. It implicitly separates itself from list_sessions/create_session/update_session via "one", but never names a sibling or states the boundary explicitly, so it stops short of a 5.

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

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

No when-to-use guidance at all: nothing tells the agent to reach for this instead of list_sessions when scanning, or update_session when mutating. The only implied usage comes from the word "one" and the field list; no prerequisites, no exclusions, no alternatives are stated.

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

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

With only readOnlyHint available as annotation, the description carries real behavioral weight: artifact URLs expire on a minutes scale, expired links are re-minted by re-calling the tool rather than assumed missing, and traceDownloadUrl points at the first FAILING attempt (not the last) on flaky tests. These are non-obvious operating constraints an agent could not derive from the schema or 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 lookup-mode guidance is front-loaded before the artifact caveats, so an agent reading only the first sentences can still call the tool correctly. It is dense and slightly long, but each sentence (expiry, re-minting, first-failing attempt) 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 12-parameter, no-output-schema tool it covers the return payload shape well (evidence[] with attempt index, url, expires_at) and the critical lookup parameters. Legacy aliases (by_title, testcaseid, by_fulltitle), history_limit, and include_history are left to the schema, which is acceptable at 92% coverage but not fully closed.

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 92%, so the schema documents individual parameters, but the description adds genuine semantics beyond it — the resolution path for testcase_name through test history, how testrun_id scopes that lookup, and why steps_filter drops passing setup/hook steps while keeping failed branches and parent context.

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 and enumerates exactly what 'full details' contains — errors, stack traces, steps, console logs, artifacts — which lets an agent distinguish it from a bare lister like list_testcase. It never names a sibling tool explicitly, so the differentiation is inferential rather than stated.

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

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

It gives clear when-to-use conditions for each lookup mode: testcase_id alone vs paired with testrun_id, testcase_name combined with testrun_id or defaulting to latest, and the debugging recommendation to always pass steps_filter="failed_only". It stops short of naming alternative sibling tools (e.g. debug_testcase, get_run_details) that an agent might reach for 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 only declare readOnlyHint=true, so the safety profile is already covered; the description goes further by disclosing what the return entries actually contain (successRate, lastExecution, platforms) and that a linkId is available for downstream unlinking. It does not mention pagination, caps on linked tests, or metric staleness, 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?

Two sentences: the purpose with its enrichment is front-loaded, and the second sentence carries only routing and identifier-format information. No filler, no restatement of the tool 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?

There is no output schema, so the description must carry return-value context; it names the key metric fields and the linkId, which is enough to act on. It stops short of describing the full entry shape (e.g. test name/identifier per link), so it is nearly but not fully complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's caseId note ('internal _id or the "TC-123" key') restates what the schema already documents, and the days window parameter is not addressed at all in the description, so no meaning is added beyond structured data.

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 ('List the automated tests linked to one manual test case') plus the distinguishing enrichment ('recent automation metrics (successRate, lastExecution, platforms)'). It is immediately separable from list_automated_tests and get_manual_test_case without opening a 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 overlapping sibling ('get_manual_test_case also returns the raw linkedTests array') and the exact condition that selects this tool over it: needing metrics or a linkId for unlink_automated_test. That is a full when/when-not/alternative statement.

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

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

Annotations only declare readOnlyHint=true; the description adds real behavioral context beyond that — a 90-day window on affectedRuns, a total plus the 10 latest, and precise definitions of the 'excluded' and 'critical' run categories. It stops short of describing auth requirements or pagination/limits on the rest of the payload.

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 purpose before the dense affectedRuns category explanation. Every sentence carries content, though the middle sentence packing two category definitions with em-dashes is somewhat heavy for a single read.

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?

There is no output schema, so the description must carry the return-value burden, and it largely does: it names the four control fields plus the affectedRuns structure and window. Minor gaps remain about the shape of individual run entries beyond the total-plus-10 count.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds provenance for testcase_id ('the Playwright test id, as list_testcase returns it'), clarifying exactly which identifier to supply. projectId is left entirely to 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 ('Read the Test Controls of one test') and enumerates exactly what is returned: assignee, critical flag, watch status, active quarantine, and affectedRuns. The phrase 'of one test' distinguishes it from the sibling list_test_controls 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?

Usage is only implied — it tells you the id comes from list_testcase, which is a useful invocation hint, but gives no explicit when-to-use/when-not guidance versus list_test_controls or get_quarantine/quarantine_tests siblings. An agent can infer single-test lookup, but nothing is 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?

Goes well beyond the readOnlyHint annotation: it discloses what is returned (a runbook teaching the open→actions→action→snapshot→close protocol), that the URL is short-lived, and crucially that analysis runs on the caller's machine and the agent must download and run the CLI itself before reporting a fix. This is exactly the kind of non-obvious behavioral context annotations cannot carry.

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, then modes, then the operational caveat. Two clauses are slightly redundant ('runs on your machine' and 'download the trace, run the CLI commands yourself'), but the density is justified for a multi-mode, multi-step 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?

There is no output schema, so the description carries the return-value burden and does so — it describes the runbook content and the download URL. Combined with the workflow warning that the analysis happens locally, an agent has everything needed to call and act on this tool.

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

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

Schema coverage is already 100%, so baseline is 3, but the description adds real meaning: projectId+testcase_id together unlock the download URL, testrun_id scopes to a single run, and omitting all ids switches to runbook-only mode. That dependency relationship is not captured by the per-field schema descriptions.

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

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

States a specific verb and resource — 'Debug a failing Playwright test from its trace.zip using the Playwright agent CLI' — and names the mechanism (trace CLI, 1.59+), which sets it apart from generic debug siblings. It never names debug_testcase or get_debug_evidence, so an agent must infer the boundary rather than being told it.

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 spells out the two invocation modes: pass projectId + testcase_id (optionally testrun_id) to get a hosted-trace download URL, or omit the ids to just get the runbook for a local trace.zip. Clear conditional usage, but no exclusions or comparison against the other debug-oriented siblings.

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

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

Annotations only declare readOnlyHint=true, leaving the behavioral burden on the description, which delivers: PAT verification, auth/permission implications ('every other tool requires a projectId'), a 30s staleness window for renamed orgs/projects, the wildcard-scope return shape, and the caveat that `role` is informational rather than a security guarantee. This is genuinely context an agent could not derive elsewhere.

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 imperative 'ALWAYS call this first,' and each subsequent sentence carries distinct operational value (projectId extraction, role semantics, wildcard handling, staleness, error recovery). It is dense and slightly long, but little of it is 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?

No output schema exists, so the description must describe return values itself — and it does, covering identity, orgs, projects, projectId/names, role, and the wildcard `allProjects: true` shape. Combined with the error-recovery guidance, an agent has everything needed to call it correctly and interpret the result.

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?

Zero parameters, so per the baseline this scores 4. The description does imply the response shape (projectId, orgName, projectName, role, allProjects), which is useful even though there are no inputs to document.

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 actions with verbs and resources: verifies the PAT, returns account identity, and lists every organization and project with projectId and human names. This is clearly distinguishable from every sibling tool, all of which concern test cases, runs, sessions, releases, or integrations rather than identity discovery.

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 'ALWAYS call this first — before any other tool in every session' and adds a second trigger: 'Also call this whenever you get a PROJECT_NOT_FOUND or auth error.' It also names the alternative path for wildcard-scope accounts (ask the user or call a listing tool), so both when-to-use and when-to-deviate are covered.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false, so the description carries real weight here: it discloses the 403 permission/plan gate, the three 400 rejection cases (unknown identity, duplicate link, 50-link cap), and the side effect that the case automationStatus flips to Automated. That is exactly the behavioral context annotations cannot express.

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 clause, and the dense paragraph packs prerequisites, param sourcing, error cases, side effects, and the sibling alternative without filler. It is slightly run-on, but essentially every sentence earns its place.

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

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

For a 5-param mutation tool with no output schema, the description covers auth/plan requirements, error behavior, side effects, parameter provenance, and the bulk alternative — nothing an agent needs to invoke 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 coverage is 100%, so the baseline is 3; the description adds sourcing semantics the schema does not — that pwTestId and fullTitle must originate from list_automated_tests and that fullTitle is a server join key that is 'never hand-built'. It doesn't elaborate on displayTitle beyond the schema, keeping it at 4 rather than 5.

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 ('Link one automated (Playwright) test to one manual test case') and even names the downstream effect ('automation results surface on the case'). An agent can distinguish it immediately from sibling tools like bulk_link_automated_tests and unlink_automated_test 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 routes the agent: use bulk_link_automated_tests for many cases in one call, and pull pwTestId + fullTitle from list_automated_tests (noting the list_testcase/pw_test_id caveat). Prerequisites (write permission, automation_linking plan feature) and failure conditions are stated up front.

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

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

Annotations only declare readOnlyHint=true, but the description adds a critical non-obvious behavior: fullTitle is a server-reconstructed join key that fails identity validation if hand-built. It also notes that each row reports its link state, which the absent output schema would otherwise leave dark.

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 fullTitle warning before the filter list, and every clause carries information. The parenthetical join-key example is worth its length, though the middle sentence runs long and could be split for faster scanning.

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 compensates by describing the returned identity pair and the per-row link status, plus paging via cursor. Combined with the downstream-tool linkage, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so all five parameters are already documented, and the description largely restates the filter/paging options ('search (title substring)', 'cursor/limit'). The one added nuance is framing linkStatus as a workflow choice, but that meaning is already present in the schema's enum description, 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 ('Search the automated (Playwright) test identities recorded for a project') and immediately clarifies it as the source of the pwTestId/fullTitle pair, which cleanly separates it from list_manual_test_cases and the other list_* siblings.

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 downstream consumers (link_automated_test / bulk_link_automated_tests) and the hard rule 'ALWAYS take fullTitle from this tool', giving an unambiguous when-to-use condition plus the consequence of not following it. It also enumerates the supported filters, so the agent knows what narrowing is available.

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?

readOnlyHint=true already covers the safety profile. The description adds pagination defaults (page size 25, max 200), which is useful behavioral context the annotation doesn't provide, but omits sort behavior and return characteristics.

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, filter options grouped efficiently, and the pagination default is placed at the end. No wasted words.

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

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

For a 12-parameter list tool with no output schema, the description covers the filter surface but leaves entire parameters (sortBy, sortOrder, isClosed) unexplained and provides no return-format guidance. Adequate but with clear 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 only 50%, and the description restates the status/state/environment/release/tags/search filters already documented in the schema, though it helpfully lists the allowed status and state values. It does not compensate for the undocumented parameters like sortBy, sortOrder, isClosed, or page.

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+resource ('Browse manual test runs for a project') and enumerates the filterable dimensions. It doesn't explicitly differentiate from near-siblings like list_testruns or get_manual_run, 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?

It implies a browsing/listing use case by describing filters, but never states when to use this tool vs list_testruns or get_manual_run for a single run. No when-not guidance is provided.

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

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

readOnlyHint=true already declares the safety profile, so the description's main addition is the default limit of 10 and the advice to raise it, which is genuinely useful behavioral context. It says nothing about ordering, pagination beyond the limit, or the shape of results.

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?

Four tight sentences, front-loaded with the core action and then the highest-value filters. Every sentence carries information; no filler or repetition of the title.

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

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

For a 13-parameter read-only listing tool with no output schema, the description plus the rich schema docs cover what an agent needs to invoke it correctly. The main gap is sibling disambiguation and any indication of result ordering or total count.

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 85%, so the baseline is 3, but the description adds real value: it explains suiteId scopes to a folder, that search matches title or caseId with a concrete 'TC-123' example, and that tags are comma-separated. It leaves type/layer/behavior/priority/severity/time to 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?

Names a specific verb and resource: search and browse manual test cases with filters. Clear what the tool returns, but it never differentiates itself from the similarly named sibling list_testcase, which an agent could easily confuse with this one.

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 filter-usage guidance (scope with suiteId, match with search, filter by status/tags) and a practical nudge to raise the limit. However there is no when-to-use-this-vs-alternatives guidance against list_testcase, list_manual_test_suites, or get_manual_test_case.

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

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

Annotations only declare readOnlyHint=true, so the description carries the rest and does so well: it discloses the return content (IDs, names, parent relationships, child counts) and warns that suite names are case-sensitive, which is a real behavioral constraint beyond the safety hint. It stops short of describing hierarchy depth or pagination behavior.

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

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

Three sentences, front-loaded with the core action, then the critical prerequisite, then the filtering parameter. No filler; each sentence carries distinct operational information.

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

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

With no output schema, the description correctly summarizes the return shape and gives the pre-call dependency on create_manual_test_case. Adequate for a simple read tool, though it could note whether the hierarchy is flat or nested and how deep it traverses.

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 50% – projectId has only a trivial 'Project ID' description and parentSuiteId is undocumented in the schema. The description compensates by explaining exactly what parentSuiteId does ('list only the direct children'), which is the one non-obvious parameter, though projectId semantics and any format constraints remain unstated.

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 test suite folder hierarchy for a project') and enumerates what is returned (suite IDs, names, parent relationships, child counts). It also implicitly separates itself from list_manual_test_cases by scoping to suites rather than cases, and names create_manual_test_case as the downstream consumer.

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 'ALWAYS call this before create_manual_test_case' and gives the reason (need the exact case-sensitive suiteName). It also documents the alternative mode of use: 'Pass parentSuiteId to list only the direct children of a specific suite.' Both when-to-use and how-to-narrow are 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?

Annotation readOnlyHint=true already establishes safe read behavior. Description adds the 3-level nesting depth constraint and pagination defaults (25/200), which is useful behavioral context beyond the annotation. But doesn't mention pagination mechanics or ordering guarantees.

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?

Four tight sentences, front-loaded with purpose, then filters, then the key nesting semantic, then pagination limits. 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?

Complete enough for a 10-param list tool: purpose, main filters, nesting semantics, and pagination defaults all covered. Minor gap: no output schema, so an agent gets no hint about returned release 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 coverage is 60%, and description compensates by naming what filters do (type, completion status, parent release, search on name) and explaining parentReleaseId semantic (direct children, 3 levels). Adds meaning over the terse schema descriptions for several params.

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 (Browse/List) and resource (releases/milestones) with clear scope for a project. Distinguished from siblings like get_release (single) and create_release through the explicit 'list' framing.

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?

Implied usage as a discovery/list tool, with some filtering context. But no explicit when-to-use vs get_release or when to prefer search over parentReleaseId filtering. No exclusions 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?

readOnlyHint=true already covers safety, but the description adds real value the annotation does not: the shape of each returned row (caseKey like "TC-156", title, current assignee, current result/status values such as "untested"/"passed"/"failed"). It does not mention pagination behavior or what a filtered-empty response looks like, so 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?

Three sentences, front-loaded with the core purpose before the return-shape detail and the workflow hint. Slightly dense with parenthetical asides, but no sentence is padding.

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

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

With no output schema and 10 parameters, the description carries the burden of explaining the return payload, and it does so at the row level. It never explicitly states that the field consumed by update_run_test_case is named 'rtcRef' in the response or how paging totals are returned, leaving minor gaps for a tool of this size.

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 70%, which sets a baseline of 3. The description reinforces assignee ('email or User _id') and result/status filtering, matching what the schema already says, but adds nothing about page, limit, search, sortBy, or sortOrder — so no credit beyond the 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?

Specific verb+resource: 'per-case execution records inside a manual run', clarified with the concrete analogue 'rows in the run's test-case table'. That scope distinguishes it cleanly from list_manual_runs (runs) and get_manual_run (run metadata) without needing their 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 an explicit workflow rule: 'Use this before update_run_test_case so you have the rtcRef for each case you want to update', plus the filter conditions it supports. It names the follow-up tool rather than a competing alternative and states no when-not-to-use case, so it falls just 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?

The readOnlyHint annotation already establishes this is a safe read, and the description adds genuine behavioral value by disclosing pagination defaults ('Default page size 25 (max 200)'). It stops short of describing return shape, ordering behavior, or whether results are truncated, so it adds context but not a rich behavioral picture.

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 resource scope is front-loaded, followed by the filter inventory and the pagination constraint. No filler, no restatement of the name or title.

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

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

For a 13-parameter, no-output-schema tool, the description covers the primary filtering use case adequately but is not complete: it never mentions the page parameter, sorting controls, or anything about what the response contains. An agent can call it, but the pagination and ordering story is only half told.

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?

At 54% schema coverage, the description carries real weight by mapping filters to names (status, state, sessionType, assignee, release/releaseId, tags, search) and the page-size limit. But it omits meaningful parameters — page, sortBy, sortOrder, and isClosed — leaving those unglossed in both the description and parts of 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 ('Browse exploratory sessions for a project') and pins the collection scope. It clearly implies a multi-session listing, distinguishing it in spirit from the singular get_session, but never names the sibling or explicitly contrasts the two.

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?

Enumerating the filterable dimensions implies 'use this to find/filter sessions,' which is reasonable context. However there is no when-to-use versus alternative statement and no prerequisites, so the agent must infer the conditions from the filter list 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 only declare readOnlyHint=true; the description adds behavior the annotations cannot carry — silent empty-result-with-warning semantics, internal run resolution for branch/time/author/commit filters, the 20-ID batch cap, and non-erroring behavior for unknown machine ids. The "KEY INSIGHT" about avoiding a redundant list_testruns call is exactly the kind of operational context that changes how an agent sequences calls.

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 gating rule and KEY INSIGHT are front-loaded, and the example filters make the guidance actionable. It is a dense block of prose that runs long, but each sentence carries a distinct constraint or affordance rather than restating 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 22-parameter read-only list tool with no output schema, the definition covers the critical gating rule, filter interaction, and pagination preference, and it notes that returned cases carry machine_id. It does not describe the shape of the returned case list or paging metadata, so an agent must infer result structure.

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 only 68%, and the description compensates for the cross-cutting parameters: it explains that by_branch/by_time_interval/by_author/by_commit implicitly resolve runs, how by_testrun_id batches ("id1,id2,id3"), and how by_machine supports failure attribution. Several parameters (by_artifacts, by_environment, by_testsuite_id, by_shard) remain undocumented, and the prose says by_machine scopes to "one machine's cases" while the schema allows a comma-separated list — a minor tension.

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 (list/filter test cases) with an explicit scope ("across runs"), which separates it from the run-scoped and manual-case siblings. It also names other tools it interacts with (list_testruns, search), so an agent can place it without opening a 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 states the precondition (at least one run-context filter), the failure mode when omitted (empty result plus warning), which alternatives to avoid calling first (list_testruns), and the fallback when a filter does not exist ("no spec-file filter: use search with the file name"). It even gives a concrete combined-filter recipe, leaving nothing 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?

The readOnlyHint annotation already establishes the safety profile, but the description adds useful behavior: the default view, view-specific filtering, inclusion of the quarantine budget in the response, and the logic excluding candidates that always pass on retry. It does not describe pagination behavior, which keeps it from being fully comprehensive.

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 tool purpose and then explains the views and filters in a dense but relevant paragraph. It is longer than average but every major clause contributes to selecting a view or interpreting a parameter.

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 listing tool with nine parameters and no output schema, the description covers the view logic, key filters, candidate exclusion rule, and a response detail (quarantine budget). It could do more to describe the returned list shape, but the critical behavioral context is present.

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

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

Schema coverage is high at 89%, so the baseline is 3, but the description meaningfully adds context for view, state, covers, reason, search, and assignee beyond what the schema provides. The page parameter is not explained in the description, but most parameter semantics are clarified.

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: it lists tests under Test Controls in a project. It also distinguishes the available views (quarantined, critical, watched, candidates), so an agent can understand the tool's scope 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 when each view applies and how filters map to the quarantined view, including that settings changes are only done in the app. It does not explicitly name sibling alternatives such as get_test_controls or get_quarantine, so it lacks full alternative routing.

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

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

readOnlyHint=true already covers the safety profile, and the description adds real context on top: which fields the runs carry, that testrun_id values feed follow-up calls, and a guidance to prefer filtered/paginated queries. It stops short of describing pagination limits or result volume behavior, so not a full 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 purpose, then usage, then the sibling exclusion, then time formats — a sensible priority order with no filler. The closing time-value sentence partially duplicates the by_time_interval schema description, which keeps 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?

With no output schema, the description still tells the agent what comes back (run metadata fields and testrun_id) and how to keep result sets manageable. Combined with 100% schema coverage on 13 parameters, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so all 13 parameters are already documented in the schema, which sets the baseline at 3. The description reinforces the time-interval vocabulary ("1d", "3d", "weekly", "monthly", custom range) and names the branch/time/author filter families, but adds no syntax or semantics the schema lacks.

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 ("Browse test runs for a project") and immediately narrows scope to run-level metadata. It distinguishes itself from the closest sibling by explaining that list_testcase resolves runs internally, so an agent can route 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?

Explicitly states when to use it (need run-level metadata such as pass/fail totals, duration, branch, commit, author, or testrun_id values) and when not to ("You do NOT need to call this before list_testcase when you already have branch/time/author filters"). It also advises specific filters plus pagination over broad result sets.

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

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

Goes well past the annotations: it discloses the all-or-nothing limit behavior, that already-quarantined tests are skipped, that assignees start watching and get notified, that dry_run creates nothing and reports skips/limits but omits some real-call checks, and critically that "a quarantine cannot be deleted, only released." That last point is essential behavioral context for a destructiveHint=true tool.

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

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

The action and its effect are front-loaded and every sentence carries information, but the middle section is a dense run of semicolon-linked clauses that takes effort to parse. Slightly tighter grouping of the parameter semantics would improve scanability.

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, non-read-only mutation with no output schema, the description covers the mutation's effect, defaults, limits, skip behavior, dry_run output, and irreversibility. Nothing an agent needs to call 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 71% schema coverage, the description fills the remaining gaps and adds real semantics: reason becomes the quarantine note, ends_in_days falls back to a project default, assignee has tiered defaults (test's assignee for one test, else the caller) plus a watch/notify side effect, and only_this_error is scoped to one test and to the final attempt's error. These are behavioral meanings the schema cannot express.

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 with explicit scope: "Quarantine 1 to 100 tests" and spells out the effect ("their failures stop failing the build (they still run and are reported)"). An agent can distinguish this from update_quarantine or release_quarantine purely from the description.

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 hard usage gate ("Call this only when the user asks for it") and conditions for dry_run ("use it before a large quarantine") and only_this_error (one test only, final attempt error). It does not explicitly name sibling alternatives such as update_quarantine or release_quarantine, so it stops short of full routing 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 destructiveHint=true, and the description adds real context on top: the state transition to Released, the recorded releaser identity, retained history, and the practical consequence that the test's failures will fail the build again. It does not cover idempotency or failure modes, but it goes beyond the annotations.

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

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

Three short sentences, front-loaded with the permission gate and then the state-change consequence. No filler and no restatement of the title or schema.

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

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

For a two-parameter mutation with no output schema, the description covers the essential outcome (Released state, releaser attribution, history retained) and the risk of re-enabling build failures. Minor gaps remain on permissions/error behavior, but nothing critical is missing 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% and both parameters are documented in the schema, including the provenance hint for quarantine_id. The description adds no parameter-level detail (no mention of what identifies the target or how the releaser is derived), 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+resource pair ('End a quarantine') and describes the concrete outcome: build failures resume, quarantine enters the Released state with the caller recorded as releaser. It does not, however, distinguish itself from nearby siblings such as update_quarantine or quarantine_tests.

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 an explicit usage gate ('Call this only when the user asks for it'), which functions as a when-to-use and an implied when-not-to-use rule for an agent acting autonomously. It stops short of naming the alternative tools an agent might otherwise reach for.

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