Kilotest

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

Annotations cover the safety profile (readOnly, idempotent=false, destructive=false, openWorld=false), and the description adds real behavioral context: it blocks, sends no interim notices, and exits on completion, failure, or timeout. It stops short of saying what the caller observes on timeout/failure or what the maximum wait is.

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 blocking behavior before the domain gloss on Kilotest. Efficient, though the trailing results-hierarchy sentence is background rather than invocation guidance.

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 an output schema present, return values need no explanation, and the input source is documented. The remaining gap is timeout/failure semantics -- what an agent should expect or do when the max wait elapses -- which matters for a blocking call.

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

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

Schema description coverage is 100% and both field descriptions already state they come from the report identifier returned by orderNewTest. The description's 'using the report identifier either tool returned' largely restates that, adding little beyond format examples already 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 and resource -- wait for an ordered job to complete -- and names the sibling tools that produce its input (orderNewTest / orderRetest). An agent can distinguish it from getReport or listReports 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?

Clearly states the trigger condition (a job previously ordered via orderNewTest or orderRetest) and that it blocks. It does not explicitly name an alternative for a report that is already finished (e.g. getReport), so the when-not-to-use case is left to inference.

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

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

Annotations already declare the tool is read-only, idempotent, non-destructive, and closed-world. The description adds valuable domain context by explaining the front-end quality focus and the report → issue → violator element → diagnosis hierarchy, though it does not describe the concrete return format.

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

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

Two tightly written sentences with zero waste. The purpose is front-loaded in the first sentence, and the second sentence supplies only the domain context and result structure needed to orient 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?

For a zero-parameter overview tool with no output schema and rich safety annotations, the description provides everything necessary: what Kilotest tests, what the overview covers, and how results are organized. Additional detail would be redundant or better served by the specific sibling 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?

The tool takes zero parameters, so there are no parameter semantics to document. The baseline for a parameterless tool is 4, and the description does not need to add anything further about inputs.

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 (explain) and resource (Kilotest, its tools, and result structure). It clearly differentiates this overview tool from siblings like getReport and listIssues, which retrieve specific data rather than provide orientation.

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: this is an orientation tool for understanding Kilotest before using the more specific listing and request tools. However, the description does not explicitly say when to call it instead of a sibling, nor does it name any alternatives or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds value beyond that by disclosing the result hierarchy (report → issue → violator element → diagnosis), which helps the agent understand the payload shape. It stops short of mentioning size limits or pagination for large reports.

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 format ('Get one full report in JSON'). The follow-up sentence earns its place by explaining the domain and result structure rather than 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 only two required scalar parameters and an output schema present, the description need not explain return values further; the domain context and result hierarchy it supplies are already more than required. The only minor gap is the absence of guidance on locating the jobID/timeStamp or what happens if a report does not exist.

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 descriptions with concrete format examples (jobID 'x9z', timeStamp '260503T0432'), so the schema does the heavy lifting. The description adds no additional parameter meaning, which is the correct baseline for full coverage.

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

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

States a specific verb and resource ('Get one full report in JSON') and clarifies the scope as a single report rather than a list, which implicitly separates it from listReports. It does not name a sibling directly, but the singular 'one full report' is clear enough to act on.

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

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

The phrase 'one full report' implies retrieval of a specific report versus a listing, but there is no explicit when-to-use, no prerequisites (e.g., a prior test must exist), and no named alternative such as listReports or getKilotestOverview. Usage must be inferred from the singular framing.

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, covering the safety profile. The description adds scope context (single element, single issue, single report) but discloses nothing about pagination, rate limits, or error behavior that annotations don't already signal.

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, but the first sentence is wordy ('one element reported as exhibiting one issue in one report') and the second sentence restates the domain model at length. Every sentence is relevant but not tight.

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

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

With a 100% covered schema, an output schema present, and rich annotations, the description's domain context (Kilotest, the report/issue/violator/diagnosis hierarchy) completes the picture for correct invocation. Return values need not be explained given the output schema.

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

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

Schema description coverage is 100% with examples for all four parameters, so the schema fully documents inputs. The description's hierarchy sentence loosely maps parameters to report/issue/element levels but adds no format or syntax 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?

The description states a specific verb+resource: retrieving diagnoses for one element exhibiting one issue in one report. It distinguishes itself within the report>issue>violator>diagnosis hierarchy implied by siblings listReports/listIssues/listViolators. However, the name 'listDiagnoses' suggests a collection while the description emphasizes a single element, a minor mismatch.

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

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

No explicit when-to-use or when-not-to-use guidance, but the hierarchy sentence ('results are organized as report, then issue, then violator element, then diagnosis') implies the prerequisite chain an agent must navigate. No alternatives are named and no exclusions given.

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 safety is covered. The description adds genuine domain context (Kilotest tests front-end quality; results nest report→issue→violator→diagnosis), but says nothing about volume, pagination, or what 'basics' omits.

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 followed by compact framing context. The second sentence is arguably broader than needed for this one tool, but it is not 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?

An output schema exists, so return values need not be explained, and the hierarchy sentence supplies the missing mental model for a tool in a nested resource family. What remains missing is call ordering relative to listReports, which is a minor gap.

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

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

Schema description coverage is 100% and both required parameters (jobID, timeStamp) carry format and example documentation. The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies.

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

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

The description says it provides details about one report 'including basics about the issues reported in it', which is close to the name listIssues but frames the tool as a report-detail getter. An agent cannot easily tell whether this or getReport returns the report itself, and no sibling is named to distinguish 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?

There is no statement of when to use this tool versus getReport, listReports, listViolators, or listDiagnoses, nor any prerequisites such as needing a jobID/timestamp pair from listReports. The hierarchy sentence implies position in a drill-down but never tells the agent to call this at that step.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so the safety profile is fully covered. The description adds useful context about the domain (Kilotest front-end quality testing) and the report→issue→violator→diagnosis hierarchy, which helps an agent interpret the data model. It does not disclose pagination, limits, or auth requirements.

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

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

Two compact sentences with the action front-loaded and the domain/hierarchy context following. No filler, though the second sentence borders on background rather than operational guidance.

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 explained. For a zero-parameter read-only list tool with full annotation coverage, the description is essentially complete; only explicit sibling differentiation and usage routing are 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 the baseline of 4 applies. The description correctly implies a no-argument call returning all reports, consistent with the empty 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: 'Provide basics about all available reports.' Combined with the domain explanation of what Kilotest does, an agent can tell this is the enumeration tool. However, it does not explicitly distinguish itself from the getReport sibling, which presumably retrieves a single report.

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 infers this is for listing all reports rather than fetching a specific one. No explicit when-to-use, when-not-to-use, or named alternative (e.g., getReport for a single report) is given.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds domain context (what Kilotest is and how results are organized) but nothing about result shape, pagination, or the relationship to the diagnosis level beyond the hierarchy list.

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 output scope stated first and the domain model second. It is appropriately short for a read-only lookup, though the opening sentence could have named the tool's actual resource (violator elements) more directly.

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 needn't be explained, and annotations cover safety, leaving little for the description to carry. Still, it fails to position this tool against listIssues/listDiagnoses, which is the main gap for a crowded sibling set of eleven 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%, with each of jobID, issueID and timeStamp documented including formats and examples, so the schema carries the parameter burden. The description contributes no additional meaning about how these three identifiers combine to scope the query, so baseline 3 applies.

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

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

The description says it provides details about one issue in one report including the elements exhibiting that issue, and it lays out the report→issue→violator→diagnosis hierarchy. However, it never uses the word 'violator' and reads more like a single-issue lookup than a listing tool, so the verb+resource is muddled and it does not distinguish itself from siblings listIssues or 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?

There is no explicit when-to-use guidance and no alternatives named, even though listIssues and listDiagnoses are obvious candidates for confusion. The hierarchy sentence only implicitly hints at when this tool fits (after you have a jobID/issueID/timeStamp).

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 cover the safety profile (readOnlyHint false, destructiveHint false, non-idempotent); the description adds genuinely useful behavior the annotations cannot convey: immediate automatic approval, expected timing (typically 2 minutes, occasionally 4), and the report/issue/violator/diagnosis result hierarchy. That is strong added context.

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

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

Purpose and approval behavior are front-loaded, which is good, but the text is a dense run-on and the closing sentence about the report/issue/violator/diagnosis structure describes general Kilotest output rather than this tool specifically. Some of it does not earn 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 an output schema present, return values need not be explained, yet the description usefully adds timing and approval semantics. Combined with 100% schema coverage, an agent has nearly everything needed to invoke it, though the sibling choice (new vs retest) remains underspecified.

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 URL, reason, and description with their length constraints and conventions. The description adds no parameter-specific meaning beyond that, so the baseline 3 applies.

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

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

The description names a specific action (process my order to test a page) with a scope qualifier (about which no report is available yet), which implicitly separates it from the retest siblings. It is clear what the tool does, but the new-vs-retest distinction against orderRetest 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?

It hints at when to use it ('instead of waiting for manual approval') and mentions the auto-approval benefit, but it never names the actual siblings such as requestNewTest or orderRetest, nor states exclusions. Usage is implied rather than routed explicitly.

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 cover the mutation profile (readOnlyHint=false, not idempotent, not destructive), and the description adds latency expectations (about 2, occasionally up to 4 minutes) plus the auto-approval behavior, which is genuinely useful beyond the structured fields. It does not mention duplicate-order or idempotency risks, which would be the remaining gap.

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 action and the approval/timing details are front-loaded in the first two sentences. The trailing sentence explaining Kilotest's purpose and result hierarchy is largely domain context that is already available elsewhere and slightly dilutes the tool-specific content.

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

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

With an output schema present, the description need not explain return values, and it does not need to compensate for parameter gaps given full schema coverage. It is nearly complete; the only omission is explicit routing guidance against the requestRetest and orderNewTest siblings.

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 jobID, reason, and timeStamp are already fully documented with formats and constraints. The description adds no parameter-level meaning beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb (order a retest of a page) and resource, and distinguishes the auto-approval path from the manual one. It does not explicitly name the sibling requestRetest, so the differentiation from that sibling is implied 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 the condition for using this tool implicitly ('instead of waiting for manual approval', 'immediately and automatically approved'), which implies it is the fast path. It never names the alternative tool or states when this tool should NOT be used, leaving the routing inference to the agent.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the agent knows this is a non-destructive, closed-world write-like action. The description adds nothing beyond that — it doesn't say what 'process' actually does (creates a ticket? notifies a team? rate limits?), and the report/issue/violator hierarchy sentence describes the product's data model, not this tool's 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?

The first sentence is tight and front-loaded. The second sentence about front-end quality testing and the report/issue/violator/diagnosis hierarchy is tangential to submitting a feature request and consumes half the description without helping the agent invoke this specific 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?

An output schema exists, so return-value explanation is unnecessary, and the single parameter is fully specified. However, for a non-read-only action tool the description omits what processing entails (confirmation, tracking, follow-up), leaving a modest but real gap.

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

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

Schema description coverage is 100% with a single 'feature' parameter fully documented (20-1000 characters), so the schema carries the parameter burden. The description adds no extra meaning about the parameter, which matches the baseline 3 for high 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 first sentence gives a clear verb+resource ('process my request to add or improve a feature'), which is distinguishable from siblings like requestNewTest, requestRetest, and orderNewTest. The second sentence is domain context about Kilotest rather than the tool itself, so it neither adds nor detracts much from purpose clarity.

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 guidance on when to use this tool versus alternatives such as requestNewTest or requestRetest, despite a crowded sibling set of request/order tools. The intent (feature requests) is only implied by the verb 'add or improve a feature'; no conditions, prerequisites, or exclusions 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?

Annotations already declare readOnlyHint=false, idempotentHint=false, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds useful domain context (Kilotest's purpose, the report→issue→violator element→diagnosis hierarchy) but never says whether the request returns immediately or must be awaited, despite an awaitTest sibling implying asynchronous 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?

Two sentences, front-loaded with the action and its condition; the second sentence earns its place by explaining what Kilotest is and how results nest. 'Process my request' is slightly vague phrasing but not wasteful.

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 described. However, for a non-read-only, non-idempotent submission tool sitting next to awaitTest, the absence of any statement about whether the test runs synchronously or must be polled is a meaningful completeness gap.

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

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

Schema description coverage is 100%, so URL, reason and description formats and length bounds are already fully documented. The description's mention of the listReports naming convention is background rather than added parameter guidance, so the baseline 3 applies.

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

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

The description states a concrete action (request a test of a page) and a scoping condition (no report exists yet), which separates it from retest-style siblings. It does not explicitly distinguish itself from orderNewTest or requestRetest, so the agent must infer the boundary from the 'no report available yet' clause alone.

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

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

'a page about which no report is available yet' is a clear when-to-use condition that implicitly routes existing-report cases to requestRetest. No sibling is named explicitly and no prerequisites (e.g. required account/permissions, sync vs async behavior) 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?

Annotations declare readOnlyHint=false, openWorldHint=false, idempotentHint=false and destructiveHint=false, and the description is consistent with a non-destructive write action. It usefully adds the precondition (an existing report) and the result hierarchy (report > issue > violator > diagnosis), but says nothing about what side effects occur, whether a new job is queued, or whether the request is charged/queued.

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 is front-loaded in one sentence with the domain context following. It is only two sentences with no padding, though the second sentence largely restates the title and is background rather than operational guidance.

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 an output schema present, return values need not be explained, and the required-report precondition is covered. The key omission is routing: with both requestRetest and orderRetest in the sibling set, the description leaves the agent unable to decide which one to call.

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

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

Schema description coverage is 100%, so jobID, reason and timeStamp are fully documented in the schema (including formats and examples). The description only indirectly gestures at the report's jobID/timeStamp via 'a page about which a report is available', adding no format or validation detail beyond 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?

The first sentence gives a specific verb+resource ('retest a page') and even states the precondition that a report must already exist. However it does nothing to separate itself from the sibling orderRetest (or requestNewTest), which an agent must choose between; the second sentence is domain background rather than purpose.

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?

'a page about which a report is available' implies when the tool is applicable, so usage is hinted at. But no alternative is named despite the near-identical sibling orderRetest, and there is no guidance on when to retest versus order a new test or request a feature.

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