Kilotest

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

Annotations cover the safety profile (readOnly, non-destructive), and the description adds behavior they cannot express: the call blocks, it terminates on ready/failure/timeout, it emits no interim notices, and it returns status plus a report identifier when ready. That is exactly the context an agent needs before committing to a blocking call.

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

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

Three tight sentences, front-loaded with the action and the input's origin, then the alternative, then the blocking semantics. No filler or restatement of the name.

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

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

With an output schema present, return values need not be detailed, and the description still summarizes the return shape. Blocking, timeout, and failure termination are all disclosed, leaving nothing an agent needs 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 the single property already documents its provenance and format example, so the description's 'using the report identifier either tool returned' largely repeats structured data. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description names a specific verb and resource ('waits for a job ordered via orderNewTest or orderRetest to finish') and ties the input to the identifier those tools return. It is immediately distinguishable from read-only siblings like listIssues or getReport.

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 routes the agent: 'Use this instead of polling listIssues when an immediate answer is preferred,' naming both the alternative and the condition that selects this tool. No inference is required.

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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the response is the entire report in one JSON payload, and its size is disclosed via listIssues, which usefully warns the agent that the payload may be large. It does not discuss limits or partial-failure behavior, 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-loaded with the core action and the discriminator, and the size caveat lands at the end where it is most useful. 'Returns the complete report data for the specified report identifier' largely restates the opening sentence, so it is slightly redundant but still compact.

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

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

An output schema exists, so return values need no elaboration, yet the description still characterizes the payload contents and points to the tool that reveals its size. Combined with the explicit routing guidance against three siblings, 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 coverage is 100% and the parameter already carries a description plus a concrete example ('260503T0432-x9z'). The description only refers to 'the specified report identifier', adding no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

Specific verb+resource ('Retrieves one entire report as JSON') with explicit scope ('all of its issues, violators, and diagnoses'). It names the sibling tools it replaces – listIssues, listViolators, listDiagnoses – so an agent can distinguish it from the drill-down tools 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?

States the selection condition directly: use this instead of drilling down through the three list tools when the full report is needed in one call. That is an explicit when-to-use with named alternatives, 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?

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, so safety is covered. The description adds that this is a drill-down producing per-rule-engine diagnoses, but says nothing about pagination, ordering, auth, or what happens when the element has no violation (empty result).

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 what-and-scope before the usage note. The second sentence restates the first's content fairly closely (per-rule-engine diagnosis output), which is mild redundancy.

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

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

An output schema exists, so return values need not be explained, and annotations carry the safety profile. The description covers what it returns, at what granularity, and how it fits after listViolators, leaving only edge-case behavior (empty results, error conditions) 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 description coverage is 100%, so issueID, reportID, and catalogIndex are already documented in the schema with examples. The description clarifies the role of catalogIndex ("the issue-exhibiting element") but adds no format or syntax 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?

States a specific verb ("Lists") and resource ("diagnoses") with a precise scope: one element, one issue, one report. An agent can distinguish it from listViolators, though the second sentence largely re-describes the same return content rather than sharpening the 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?

"Use this after listViolators to get details about the element as a violator of the issue" gives explicit sequencing and names the alternative sibling. It lacks a when-not condition, but the workflow position 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 readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior: the response includes the history of all reports about the same page, not just this report's issues, which is real context 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?

Two sentences, front-loaded with the core action and result, and the second sentence earns its place by giving the usage sequence. Slightly dense phrasing ('the history and the basics about this report's issues') but no wasted 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?

An output schema exists, so return-value detail is not required in the description. Given the single-parameter, read-only nature and full annotation coverage, the description supplies enough to call it correctly, though the relationship to the other list* siblings remains 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?

There is a single required parameter with 100% schema coverage and an example format, so the schema carries the semantic load. The description only says 'one report,' adding nothing about format or valid values beyond what the schema provides — 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?

States a specific verb and resource ('Lists the issues reported in one report') and adds the notable scope detail that it also returns report history for the same page. It does not explicitly distinguish itself from siblings like listDiagnoses or listViolators, which also sound issue-adjacent, so it falls 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?

'Use this after listPages to switch to an earlier or later report or to begin examining this report' gives a clear entry condition and workflow position. It lacks explicit when-not guidance or a named alternative, so it is strong but not complete.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description adds the shape of the returned records, but says nothing about pagination, result size limits, or authorization needs for a potentially unbounded 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?

Three short sentences, front-loaded with the purpose, then the timing guidance, then the return shape. Every sentence contributes and nothing is 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?

Coverage of safety (annotations), return values (output schema) and inputs (none) is complete, and the description supplies the workflow context those structured fields cannot. The only gap is behavior when the page list is large, which is not addressed anywhere.

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 semantics to explain and the schema needs no compensation. This is the baseline for a parameterless tool, with no misleading or missing parameter guidance.

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

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

States a specific verb and resource ("Lists all pages Kilotest has tested") and immediately constrains the scope to tested pages, which distinguishes it from report- or issue-oriented siblings. An agent can tell what it returns and why it exists 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?

Gives explicit sequencing guidance: "Use this first to discover whether a page already has any reports before requesting a test." It establishes the precondition for the test-requesting tools but does not name the specific alternatives (orderNewTest, requestRetest, etc.), leaving the agent to map the generic phrasing to the right sibling.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds only the scoping constraint (one issue, one report) and a light hint that it 'returns basics about each violating element'. With the annotation bar this is 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, zero padding, and the primary scope statement is front-loaded ahead of the usage guidance. Every clause carries information.

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

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

An output schema exists, so return values need not be spelled out, and the description still notes the response contains 'basics about each violating element'. Combined with full annotation coverage and a 100% documented 2-param schema, 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 description coverage is 100% and both parameters carry examples ('contrastPoor', '260503T0432-x9z'), so the schema does the heavy lifting. The description only implies that issueID and reportID come from the preceding listIssues call; it adds no format or constraint detail beyond the schema, which is the correct baseline of 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 ('lists the elements of a tested page') with an explicit scope: one issue in one report. It also implicitly distinguishes itself from the sibling listIssues by positioning this as the drill-down step, 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 after listIssues to drill down from an issue to the elements violating rules belonging to that issue' gives explicit sequencing and the governing tool. It does not name a when-not case or an alternative for a different drill-down path, but the prerequisite relationship 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?

Adds substantial context beyond the annotations: the request may be auto-rejected, approval means immediate enqueueing, and a run takes 2-4 minutes. Annotations already cover readOnly/destructive/openWorld, so the remaining gap (auth requirements, quota/cost of ordering, what rejection returns) is modest.

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

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

Front-loads the core action in the first clause and keeps to two sentences with no filler. The second sentence is dense, stacking return contents, timing, and the awaitTest hand-off into one long construction, but nothing is wasted.

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?

Covers precondition, alternatives, latency expectations, and outcome shape for a non-idempotent write tool whose output schema exists. Minor omissions are what happens on rejection and whether re-invocation creates a duplicate order, but an agent has enough 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%, with character limits and URL/description conventions documented in the schema itself. The description adds no parameter-level meaning (e.g., why a reason is required, what naming convention listPages uses), 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 (orders testing of a page) plus the key precondition (page has no report yet), which separates it from orderRetest. The automated approval/rejection and immediate enqueueing behavior further pins down what the call actually does.

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

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

Explicitly routes the agent: 'Use this instead of requestNewTest when immediate testing is wanted', and points to awaitTest for waiting. It also implies the page must have no prior report, though it never names orderRetest as the path for pages that already have one, leaving that exclusion to inference.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, and the description adds genuinely new context: the request goes through an automated approval/rejection gate, enqueuing only happens if approved, and typical latency is 2-4 minutes. It does not mention quota/credit consumption or what happens to the superseded report, which would be the remaining gap for a mutating 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?

Front-loaded with purpose, then the alternative-routing guidance, then the return summary. The final clause about "a question about whether to wait for completion with the awaitTest tool" is slightly convoluted, but every sentence carries information.

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

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

An output schema exists, yet the description still usefully sketches the return shape (order confirmation, disposition, report identifier on approval). Combined with the explicit timing and the awaitTest handoff, an agent has everything needed to call this correctly and know what to do next.

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 fully documented in the schema (reason length bounds, reportID format and example). The description adds only the framing that the report should be about the obsolete page, no additional format or validation detail, so the baseline 3 applies.

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

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

States a specific verb and resource ("Orders a retest of a page") plus the precondition ("whose existing report is considered obsolete") and the outcome ("automated approval or rejection and immediate enqueuing if approved"). It also names the sibling it is not, requestRetest, so an agent can distinguish the two without reading 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 "Use this instead of requestRetest when immediate retesting is wanted," giving both the alternative and the selecting condition. It further routes the agent to awaitTest for the wait-for-completion case, and sets an expectation of 2-4 minutes.

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

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

Annotations already declare the mutation/safety profile (readOnlyHint false, idempotentHint false, destructiveHint false), so the bar is lower. The description adds genuinely useful context beyond that: the request is queued for asynchronous manager review, and a confirmation with disposition details 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?

Three tight clauses with the core action front-loaded and no filler. The final sentence about the return confirmation is partly redundant given an output schema exists, 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?

For a single-parameter tool with a full schema, output schema, and mutation annotations, the description supplies the one thing the structured data cannot: that approval is deferred to a manager. Nothing needed 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% for the single 'feature' parameter, including its 20-1000 character constraint, so the schema carries the load. The description adds no additional meaning about the parameter, which is the expected baseline when the schema is complete.

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?

A specific verb+resource ('Submits a request to add a new feature or improve an existing one') makes the action unambiguous, and the scope is clearly feature requests rather than tests. It does not explicitly name or contrast with the sibling request tools (requestNewTest, requestRetest), so it stops short of full sibling differentiation.

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

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

'Queued for manager review' plus 'There is no immediate-approval alternative for feature requests' tells the agent when to use this and preempts a search for a faster path. It stops short of a 5 because no explicit when-not-use case or named alternative 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?

The annotations already disclose that this is a non-read-only, open-world, non-idempotent, non-destructive operation. The description adds useful workflow context by noting the request is queued for manager approval and returns a confirmation with disposition 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 three tight sentences: purpose, alternative routing hint, and return behavior. It is front-loaded and every sentence contributes useful 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?

Given the rich annotations, complete parameter schema, and presence of an output schema, the description provides enough context for correct selection and invocation. It explains the approval workflow and distinguishes the tool from its main sibling.

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 three required parameters are fully documented in the schema itself. The description adds no additional parameter guidance beyond the schema, which is acceptable at 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 gives a specific verb and resource: submitting a test request for a page without an existing report. It clearly distinguishes this from orderNewTest by explaining the approval queue versus immediate approval.

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 the key condition for use ('a page that has no report yet') and explicitly names the alternative tool, orderNewTest, for immediate automatically approved testing. This gives an agent concrete 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 readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond that: the call only queues a request pending manager approval rather than executing the retest, and it returns a confirmation with disposition details. It could go further on rate limits or what happens if a request is rejected, but the approval-gating disclosure is the key information.

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 with zero waste: the core action and its approval gating come first, the sibling routing second, the return behavior last. 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 shape needn't be detailed, yet the description still flags the confirmation/disposition response. For a two-parameter, approval-gated mutation tool, an agent has everything needed to decide between this and orderRetest and 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%, with both reportID and the 20–100 character reason constraint fully documented in the schema. The description adds nothing about parameters beyond that, 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?

States a specific verb and resource ('Submits a request to retest a page') plus the qualifying condition (existing report obsolete) and the downstream behavior (queued for manager approval). It explicitly names the sibling it is not (orderRetest), so an agent can distinguish the two 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?

Names the alternative tool explicitly and the condition that selects it: use orderRetest when you want immediate, automatically approved retesting; use this when the report is obsolete and approval is acceptable. This is the when/when-not/alternatives pattern executed cleanly.

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