Kilotest

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

Annotations cover read-only and non-destructive behavior, but do not convey that the call blocks. The description adds critical behavior: it blocks until the report is ready, the job fails, or a maximum wait elapses, sends no interim notices, and returns status plus report ID when ready.

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 action and remains compact across two sentences. The alternative routing and blocking caveats each earn their place with no filler.

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

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

With annotations and an output schema available, the description covers the essential blocking semantics, alternative, and return behavior. The only meaningful gap is that 'maximum wait time' is mentioned without a duration or default, leaving the blocking window unspecified.

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 reportID is already documented with its source and an example. The description reinforces that the ID comes from orderNewTest or orderRetest, but adds no format or constraint beyond the schema, so the baseline is 3.

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

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

States a specific verb and resource: waits for an ordered job to finish, identified by reportID. It names orderNewTest/orderRetest as the ordering tools and distinguishes the behavior from polling listIssues, making selection 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?

Explicitly says to use this instead of polling listIssues when an immediate answer is preferred. It also ties usage to report IDs returned by orderNewTest or orderRetest, giving clear prerequisite and alternative 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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the return shape ('prose overview of the Kilotest domain, the tool workflow, and links to further documentation'), which matters since there is no output schema.

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

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

Purpose and usage are correctly front-loaded, but the middle is encyclopedic: the counts of rule engines, rules, and issues describe what the tool returns rather than what the tool is for, so they partly duplicate the payload. The closing sentences restating list/retest capabilities also overlap sibling tool scopes.

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 parameters and no output schema, the description fully carries the burden: it says what the tool is, when to call it, and what it returns (prose overview plus documentation links). Nothing an agent needs in order to invoke a zero-argument informational tool 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate. The baseline of 4 applies; no parameter-level confusion is possible.

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 ('Explains what Kilotest is, what its tools do, and how its results are structured') and clearly positions itself as the orientation tool among the many action-oriented siblings like listPages and orderNewTest. An agent can tell immediately that this is the meta/documentation tool rather than an operation.

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

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

Gives an explicit trigger: 'Use this before any other tool when the available tools or workflow are unclear.' That is clear when-to-use guidance with a workflow position, though it doesn't state an explicit when-not (e.g., skip it if the workflow is already known).

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds value beyond that by disclosing the payload shape (all issues/violators/diagnoses in one response) and a size/cost caveat deferred to listIssues — a useful behavioral trait for a tool that may return very large payloads.

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 well with the core purpose and the routing advice, but the third sentence ('Returns the complete report data for the specified report identifier') largely restates the first and earns little. The size note is useful but plumbed in awkwardly at the end.

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 rich annotations and an output schema present, the description needn't spell out return structure, and it appropriately covers purpose, alternative routing, and a size caveat. The only soft gap is the vague pointer that size is 'disclosed by the listIssues tool' rather than stating a threshold or pagination behavior.

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

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

Schema description coverage is 100% and the single parameter has an example format, so the schema carries the burden. The description only restates it as 'the specified report identifier' and adds no format or validation detail beyond the schema.

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

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

States a specific verb+resource ('Retrieves one entire report as JSON') and enumerates the payload contents (issues, violators, diagnoses), which cleanly separates it from the list* siblings. An agent can distinguish it from listIssues/listViolators/listDiagnoses 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 names the alternatives to avoid ('instead of drilling down through listIssues, listViolators, and listDiagnoses') and the condition that selects this tool (full report needed in one call). It stops short of a hard when-not rule, only hinting via the note that report size is disclosed by listIssues.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed-world scope, so the safety profile needs no restating. The description adds real value by disclosing the result's cardinality rule: one diagnosis per rule engine that reported a violation of a rule belonging to the issue. It does not discuss failure modes or pagination, but those are minor against full annotation coverage.

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

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

The purpose sentence is front-loaded and the workflow hint follows immediately and usefully. The third sentence largely re-expresses the first in per-rule-engine terms, so there is mild redundancy, but nothing 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?

An output schema exists, so return-value shape need not be explained, and the description still conveys the per-rule-engine iteration structure and its place in the listViolators workflow. What a 'diagnosis' actually contains is left to the output schema, which is acceptable.

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 all three parameters carry examples, so the schema does the heavy lifting. The narrative maps conceptually onto element, issue and report but adds no format or constraint detail beyond what the schema already provides. Baseline 3 applies.

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

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

The description states a specific verb and resource ('Lists the diagnoses that rule engines gave') and pins the scope to one element, one issue, one report. This clearly separates it from listIssues and listViolators, which operate at issue and violator granularity respectively.

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

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

It explicitly names the prerequisite workflow: 'Use this after listViolators to get details about the element as a violator of the issue.' That is a clear sequencing signal rather than an inferred one. It stops short of stating when not to use the tool or naming a direct alternative for diagnosis data.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive behavior, and closed-world scope. The description adds useful behavioral context by mentioning report history and switching reports, but it does not cover pagination, error conditions, or other operational details.

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 short and front-loads the main purpose before usage guidance. There is minor redundancy between the mention of report history and the final sentence about returning history and basics, but overall it is efficient.

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

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

Given rich annotations, a fully described single parameter, and an output schema, the description is largely complete for an agent to select and invoke the tool. It could be improved by clarifying how it relates to sibling reporting tools, but no critical invocation detail 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% and there is only one parameter, reportID, whose meaning is documented in the schema. The description references 'one report' and 'this report' but adds no format or constraint details beyond the schema.

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

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

The description clearly states the specific action and resource: listing issues in one report, plus report history for the same page. It names listPages as a predecessor but does not explicitly differentiate from siblings such as getReport, listDiagnoses, or listViolators.

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 a clear usage context: call this after listPages to switch between earlier/later reports or begin examining a report. It does not state when not to use this tool versus similar reporting tools, so it stops short of full alternative 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, idempotentHint, and openWorldHint=false, so the safety profile is covered; the description adds the useful behavioral detail that each entry carries its latest report identifier, which is the key signal for the discovery workflow. It stops short of noting whether the list is paginated or ordered, which keeps it from 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 short sentences: what it does, when to use it, and what comes back. Front-loaded with the action and 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?

An output schema exists, so return values need not be fully specified, yet the description still summarizes the key fields (description, URL, latest report identifier). Combined with the workflow guidance and the annotation coverage, an agent has everything needed to call it correctly.

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

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

With zero parameters there is nothing to document, and the description correctly spends no space on inputs, instead describing the shape of each returned item. Baseline for a parameterless tool is 4.

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

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

States a specific verb and resource (lists all pages Kilotest has tested), naming the domain explicitly, which distinguishes it from siblings like listIssues or listViolators that list other entity types.

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

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

Explicitly prescribes when to call it: 'Use this first to discover whether a page already has any reports before requesting a test,' which positions it before requestNewTest/orderNewTest. That is a concrete workflow rule, not an implied one.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered. The description's only addition is that it 'Returns basics about each violating element,' which is thin and partly redundant with the output schema. Useful as a hint about result shape, but no pagination, ordering, or volume expectations are 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?

Three short sentences, zero waste, with the scoping definition front-loaded and the routing guidance immediately after. Nothing repeats the annotations or restates the tool name unproductively.

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, read-only list tool whose safety profile is annotation-covered and whose return shape is defined by an output schema, the description supplies everything needed: what is listed, how it is scoped, and when to reach for it. No material gap remains.

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

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

Schema coverage is 100% and both parameters carry examples ('contrastPoor', '260503T0432-x9z'), so the schema does the heavy lifting. The description adds the relationship between the two parameters – one issue within one report – but no format or provenance detail beyond that. 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 ('Lists') and resource ('elements of a tested page') plus the exact scoping condition: elements exhibiting one issue in one report. It also distinguishes itself from the sibling listIssues by framing itself as the drill-down step from an issue, so an agent can separate the two 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?

Explicit sequencing guidance: 'Use this after listIssues to drill down from an issue to the elements violating rules belonging to that issue.' That names the alternative and the condition that selects this tool. It stops short of any when-not-to-use case (e.g. what to do if you lack an issueID), so it is a 4 rather than a 5.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, openWorldHint=true and destructiveHint=false, so the description's job is to add process context — which it does: automated approval/rejection, immediate enqueueing on approval, and a 2-4 minute expected duration. It stops short of saying what a rejected order returns or what happens on duplicate orders, which keeps it from 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, front-loaded with the action and its precondition before the sibling comparison. Dense but every clause carries information; the return-shape sentence is slightly long but not redundant.

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?

An output schema exists, so the brief mention of the confirmation and disposition is bonus rather than required. Preconditions, timing, approval behavior, and the awaitTest follow-up are all covered; only edge behavior (rejection outcome, re-ordering the same page given idempotentHint=false) 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% with all three required parameters documented (URL length/scheme, reason length, description naming convention), so the schema carries parameter semantics. The description adds nothing about the parameters beyond what is already in the schema; 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 ('Orders testing of a page') and narrows scope with a precondition ('that has no report yet'), which separates it from orderRetest and getReport. It also names requestNewTest as the contrasting sibling, so an agent can pick between them without reading 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 says to use this 'instead of requestNewTest when immediate testing is wanted', giving both the alternative and the condition that selects it. It also points to awaitTest for the wait-for-completion follow-up, covering the next step an agent would otherwise have to guess.

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 it is not read-only, is open-world, and is non-idempotent; the description adds what the annotations cannot — automated approval/rejection, immediate enqueuing on approval, and a 2-4 minute runtime. It does not disclose that repeat calls create duplicate orders despite idempotentHint=false, which would be useful for a non-idempotent mutation.

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

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

The purpose and the sibling alternative are front-loaded in the first clause. The sentences are dense and mostly earn their place, though the trailing return-value sentence runs long and could be trimmed.

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

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

Given an output schema exists, the description need not explain return values, yet it usefully flags that approval yields a report identifier and an awaitTest decision. It covers the approval flow and timing, leaving only duplicate-order behavior and approval prerequisites unstated.

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 both parameters (reportID and reason, including the 20-100 character constraint) are already documented in the schema. The description adds only the framing that reportID refers to a page's obsolete latest report, which is marginal value over the structured fields. Baseline 3 applies.

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

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

States a specific verb and resource ("Orders a retest of a page") plus the qualifying condition that the existing report is obsolete. It distinguishes itself from requestRetest by name, so an agent can tell the two apart 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?

"Use this instead of requestRetest when immediate retesting is wanted" gives an explicit alternative and the condition that selects it. It also points to awaitTest as the follow-up for waiting on completion, covering the main decision path.

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 tell the agent this is a non-read-only, non-destructive, non-idempotent mutation. The description adds beyond that by disclosing the side effect: the disagreement is queued for manager review and a confirmation with disposition details is returned. It doesn't clarify permission requirements or rate limits, but the operational consequence is clear.

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 packed sentences: the action and effect come first, followed by the usage condition and required inputs. No wasted phrasing.

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

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

For a six-param mutation with 100% schema coverage, an output schema, and annotations covering safety, the description supplies what's missing: the queueing behavior, the trigger condition, and the return confirmation. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds value by naming engineID and ruleID as 'shown in the diagnosis' and requesting 'your reason,' linking the parameters to the listDiagnoses output. It omits issueID, reportID, and catalogIndex, so it doesn't fully compensate beyond the schema.

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

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

The description states a specific verb and resource ('Reports that you disagree with a diagnosis shown by the listDiagnoses tool') and adds the consequence ('queued for manager review'). It clearly distinguishes itself from the read-only sibling listDiagnoses.

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 use it 'after listDiagnoses when you believe a rule violation was incorrectly diagnosed or classified.' It names the prior tool, the triggering condition, and the required inputs. The condition for invoking it is unambiguous.

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

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

Annotations already establish readOnlyHint=false, destructiveHint=false, and idempotentHint=false; the description adds genuinely new behavior by disclosing that the request is queued for manager review rather than executed, and that a confirmation with disposition details is returned. It does not cover how long review takes or what a rejection looks like, but the essentials beyond the annotations are there.

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

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

Two short sentences, front-loaded with the action and followed by the queuing/disposition behavior. The return-value clause partially duplicates the output schema, but the description is still tight with no filler.

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

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

For a single-parameter submission tool with full schema coverage and an output schema, the description covers what happens after the call (review queue) which is the only non-obvious aspect. Nothing critical about invocation is missing, though naming the sibling contrast would have made routing airtight.

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?

Only one parameter exists and schema description coverage is 100%, with the 20–1000 character constraint documented in the schema itself. The description adds no constraints, examples, or formatting hints beyond that, so the 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 and resource ("Submits a request to add a new feature or improve an existing one") plus the downstream handling ("queued for manager review"). It implicitly separates itself from test-ordering siblings like orderNewTest by noting there is no immediate-approval path, but it never names a sibling explicitly.

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 condition for use (wanting a new feature or an improvement) and rules out an expectation of instant fulfillment ("no immediate-approval alternative... queued for manager review"). It stops short of explicitly routing the agent away from requestNewTest/orderNewTest by name, so the agent must infer the boundary.

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

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

The annotations already disclose that this is not read-only, is open-world, not idempotent, and not destructive. The description adds meaningful behavior beyond the annotations: requests are queued for manager approval and return a confirmation with disposition details. It does not explain rejection/failure handling, but the core workflow is clear.

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

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

The description is three tight sentences: purpose first, alternative second, return behavior third. Every sentence adds decision-relevant information and there is no repetition or filler.

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

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

Given the rich annotations, complete input schema, and presence of an output schema, the description supplies the key missing context: the manager-approval queue and the contrast with orderNewTest. An agent has enough information to select and invoke this tool correctly.

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

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

Schema description coverage is 100%, so the three parameters and their constraints are fully documented in the schema. The description does not add parameter-level meaning beyond the schema, which is acceptable at the baseline for complete schema coverage.

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

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

The description states a specific verb and resource: submitting a request to test a page that has no report yet. It also distinguishes this tool from the sibling orderNewTest by explaining the approval-queue behavior versus immediate automatically approved testing.

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 an explicit condition for use—pages with no report yet—and names the alternative orderNewTest for immediate, automatically approved testing. The routing decision between the two tools is unambiguous.

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

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

Annotations already declare this is not read-only, not idempotent, and not destructive. The description adds meaningful workflow context beyond annotations: the request is queued for manager approval and returns a confirmation with disposition details. It does not cover auth or rate-limit behavior, but the approval queue is the key behavioral trait.

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 purpose and approval-queue behavior are front-loaded, followed by the alternative tool in the next sentence. There is no redundant or filler text.

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

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

The tool is a request-style mutation with annotations and an output schema. The description covers the queueing behavior, the alternative sibling, and the return confirmation, which is sufficient for an agent 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 description coverage is 100%, and both required parameters are clearly documented in the schema. The description does not add syntax or constraints beyond the schema, so the baseline score of 3 is appropriate when the schema carries parameter semantics.

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

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

States a specific verb and resource: submits a retest request for a page whose existing report is obsolete. It also explicitly distinguishes itself from orderRetest, so an agent can differentiate it from the sibling without inspecting either schema.

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

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

Explicitly says to use orderRetest instead for immediate, automatically approved retesting, which identifies the alternative and the condition that selects it. The queued-for-manager-approval detail also makes clear when this tool is appropriate.

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