LexQ

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation risk is known. The description adds the precondition that the test must be running, but it does not go deeper into side effects or irreversibility beyond what annotations 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?

One short, front-loaded sentence with no filler. It states the action and target resource immediately, making it easy to parse.

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 tool with complete schema descriptions and annotations covering destructiveness, the description provides the key missing context: the test must already be running. No output schema exists, but that is not a major gap for this simple adjustment operation.

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

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

Schema description coverage is 100%, so both groupId and trafficRate are already documented in the input schema. The description's phrase 'traffic rate' aligns with the trafficRate parameter but adds no meaning 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 ('Adjust') and resource ('traffic rate of a running A/B test'), making the operation unambiguous. It also differentiates from sibling tools like lexq_ab_test_start and lexq_ab_test_stop, since adjusting is neither starting nor stopping.

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

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

The description makes clear that the tool applies to a 'running' A/B test, which is a useful usage condition. It does not explicitly name alternatives or exclusion cases, but the context is clear enough for an agent to select it over start/stop siblings.

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

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

Annotations only mark this as a non-read-only, non-destructive mutation, so the description carries most of the burden and delivers real substance: the P-016 rejection for cross-group versions and the non-obvious failure mode where requests omitting context.trafficKey leave the test at 0%. It does not cover what happens if a test is already active or what side effects/return values follow on success.

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

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

Four sentences, front-loaded with purpose followed by prerequisites and failure modes; every sentence carries information. The final sentence about trafficKey is slightly dense but still 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?

Covers prerequisites, the cross-group rejection, and the traffic-split mechanism, which is strong for a 3-required-param mutation tool with no output schema. Gaps remain around response shape and the behavior when a test is already running, but nothing critical to correct invocation 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 the schema already documents all three parameters, including the "published version of this group" constraint on testVersionId. The description restates those constraints and adds the trafficKey routing detail, which is behavior rather than parameter semantics, so the baseline 3 holds.

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 ("Start an A/B test on a policy group") and is immediately distinguishable from the adjust/stop siblings by name and opening sentence. An agent can tell what this does 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 clear preconditions for use: a challenger version ID and traffic rate are required, and the challenger must be a published version of the same group. It does not explicitly name lexq_ab_test_adjust or lexq_ab_test_stop as the alternatives once a test is running, so routing between siblings is only implied.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: it discloses the specific consequence of the destructive action ('All traffic is restored to the control (current) version'), which is exactly the kind of side-effect information an agent needs before invoking. No contradiction with 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 short sentences with zero waste. The primary action is front-loaded in the first sentence, and the second sentence delivers the one behavioral fact that matters. Both sentences earn their place.

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

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

For a low-complexity tool (one fully documented parameter, annotations present, no nested objects), the description covers the action and its outcome. It does not describe the return value or confirmation behavior, but given the destructive hint and clear consequence statement, nothing critical for correct invocation is missing.

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

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

Schema coverage is 100% and the sole parameter (groupId) is already described as 'Policy group ID'. The description adds nothing about the parameter itself, which matches the baseline of 3 for fully schema-documented parameters. No gaps to compensate for.

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 ('Stop a running A/B test') and adds a precise scope qualifier ('running'), which cleanly distinguishes it from siblings lexq_ab_test_start and lexq_ab_test_adjust. The traffic-restoration clause further clarifies the tool's function rather than merely restating the name.

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 context is implied: an agent can infer this tool is for ending a running A/B test, and sibling naming (start/adjust/stop) supplies the alternative options. However, the description never explicitly states when to choose this over adjust or start, nor does it give any caveat or prerequisite (e.g., test must be running).

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds modest context—that the template is derived from 'required facts' and is a sample (non-mutating) artifact—but contributes little beyond the annotation. No contradiction between description and 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 with zero waste. The action ('Generate a sample CSV or JSON template') is front-loaded, followed by the basis ('based on the required facts of a version') and the usage guidance. Every clause earns its place.

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

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

For a simple, fully-documented 3-parameter tool with a readOnlyHint annotation, the description is largely sufficient—it explains the output type (sample CSV or JSON template) and its role before upload. It does not detail the template's column/key structure, but that is contextual and not required for an agent to invoke the 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%: format ('Template format', csv/json, default csv), groupId ('Policy group ID'), and versionId ('Version ID') are all documented in the schema. The description adds no parameter-level detail beyond the schema, so it meets the baseline but does not exceed it.

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

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

The description uses a specific verb-resource pair ('Generate a sample CSV or JSON template') and ties it to a concrete basis ('required facts of a version'). It implies differentiation from upload/data tools via the phrase 'before uploading a dataset,' but does not explicitly name the sibling (lexq_dataset_upload), which keeps it just shy 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 to understand the expected data format before uploading a dataset' gives clear when-to-use context and positions the tool as a preparatory step in the upload workflow. It does not explicitly name alternatives or state when not to use it, but the placement before upload makes the intended usage 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 indicate readOnlyHint=false and destructiveHint=false, so this is a write operation but not destructive. The description adds context by stating content is uploaded to S3 and a path is returned, which goes beyond the annotations. It doesn't cover rate limits or auth, but those are not critical for this simple tool.

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

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

The description is well-structured with a clear opening statement, a usage note for chaining with lexq_simulation_start, and concrete examples. Each sentence earns its place; there is no fluff. The front-loaded purpose makes it easy to scan.

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 tool with no output schema, the description fully equips an agent: it states what the tool does, how to format input, what the response contains (path), and how to integrate that path into a subsequent tool call. Nothing essential 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 input schema provides 100% coverage for both parameters (content and filename). The description adds value by including CSV and JSON examples that clarify the expected format for the content parameter, and notes the default for filename. This goes beyond the schema's minimal descriptions.

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

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

The description states a specific verb (Upload) and resource (inline CSV or JSON content as a simulation dataset), making the tool's purpose unambiguous. It also distinguishes itself from lexq_dataset_template by focusing on inline content upload rather than template retrieval.

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

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

The description explicitly explains how to use the returned path in lexq_simulation_start, including the exact dataset structure. This gives clear when-to-use context and a direct workflow example, leaving no ambiguity about its intended role.

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

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

The readOnlyHint annotation already covers safety, and the description adds the behavioral nuance of filtering to ACTIVE (published) versions, which is not in the annotation. This provides useful context about what the tool returns without contradicting the annotation.

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 two concise sentences with no wasted words. The main action and scope are front-loaded, and the usage guidance follows naturally. It is well-structured and 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?

For a simple one-parameter read-only tool with no output schema, the description covers all necessary aspects: what it does, what it lists, and when to use it. There is no missing information an agent would need to invoke it correctly.

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

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

Schema description coverage is 100% for groupId, so the schema already fully documents the parameter. The description does not add any extra meaning about the parameter, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists ACTIVE (published) versions for a group, with a specific verb (List) and resource (deployable versions). It differentiates from siblings like lexq_deploy_live and lexq_deploy_detail by focusing on the pre-deployment lookup, making its purpose 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?

The description explicitly says 'Use this to find which versions are available before calling deploy live,' giving a clear when-to-use context. It does not name alternatives or state when not to use it, but the guidance is sufficient for selecting this tool over others.

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

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

The readOnlyHint annotation already declares this a safe read operation, and the description's 'Get' wording is consistent with it — no contradiction. The description adds value beyond the annotation by hinting at the response content (snapshot hash, integrity check), which tells the agent what kind of information it will receive. It does not, however, disclose much else about behavior such as error cases or whether the integrity check is a computed or stored value.

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

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

A single sentence that front-loads the primary purpose ('Get detailed info about a specific deployment') before stating the distinguishing return items. Every word earns its place, and there is zero redundancy 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?

For a low-complexity single-parameter read tool with a readOnlyHint annotation, this is nearly complete. The description partially answers the return-value question by naming snapshot hash and integrity check, which is useful since no output schema exists. It could be more explicit about other fields in the response (e.g., deployment status), but for a simple read operation the coverage is solid.

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 deploymentId parameter is fully documented in the schema (type uuid, format, pattern, description 'Deployment ID'). The description adds nothing about the parameter, but it doesn't need to compensate for any schema gap. Baseline 3 is appropriate when the schema carries the full parameter documentation.

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 clear verb+resource ('Get detailed info about a specific deployment') and adds concrete return specifics (snapshot hash, integrity check) that help pin down what this tool does. It differentiates from siblings via the singular 'deployment' focus and the detail-oriented return content, though it never names an alternative directly. Compared to deploy_overview, deploy_history, and deploy_diff, the intent is reasonably identifiable, but the differentiation is implicit rather than explicit.

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 its many deploy siblings (deploy_overview, deploy_history, deploy_diff, deploy_live). The description implies a use case by mentioning 'specific deployment' but offers no exclusions, no prerequisites, and no named alternatives. Given the large sibling set, this is a notable gap.

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 annotation already declares readOnlyHint=true, and the description adds that the tool shows added, removed, and modified rules. This is useful but modest context; it does not disclose limits, ordering, pagination, or how snapshots are sourced. With annotations lowering the bar, 3 is appropriate.

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 two short sentences that lead with the primary action and output, then give the use case. There is no filler or redundancy; every word contributes.

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?

Required parameters are fully documented, the read-only safety is covered by annotations, and the description states the output scope in terms of added/removed/modified rules. Given the tool's moderate complexity, this is nearly complete; only minor expectations about the diff format or prerequisites are not specified.

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 base/target parameter descriptions already explain their meaning. The tool description adds no additional parameter-level semantics beyond what the schema provides, so the baseline of 3 is justified.

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 a specific action — comparing rule snapshots between two versions — and names the output categories (added, removed, modified). This strongly distinguishes the tool from other deployment and comparison siblings, and the verb 'compare' precisely names the behavior.

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 'Useful for reviewing changes before deploying a new version' gives clear usage context and position in the deployment workflow. It does not explicitly exclude alternatives or mention sibling tools, but the context is sufficient for an agent to know 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.

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

The readOnlyHint annotation already establishes that this is a safe, non-mutating read, so the description only needs to add context. 'Across all groups' hints at default scope, but nothing is said about pagination behavior, result ordering, or whether the groupId filter narrows that default scope.

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

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

A single front-loaded sentence with zero padding, which is appropriate for a read-only list tool. It is arguably too terse to be maximally useful, but there is no wasted wording.

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

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

For a six-parameter, paginated, read-only listing tool with no output schema, the definition is minimally sufficient: safety comes from annotations and parameter detail from the schema. What is missing is any statement of return shape, default page sizing, or how the filters interact.

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

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

Schema description coverage is 100% and the schema itself carries unusually rich detail (comma-separated type values, timezone-aware inclusive date semantics, UUID format). The description contributes no parameter 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?

States a clear verb ('List') plus resource ('deployment history') and adds a scope qualifier ('across all groups') that separates it from the per-deployment siblings like lexq_deploy_detail and lexq_deploy_live. It does not, however, distinguish itself from adjacent list-style tools such as lexq_history_list or lexq_deploy_overview.

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

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

There is no when-to-use guidance, no mention of when to prefer lexq_deploy_detail / lexq_deploy_live / lexq_history_list, and no prerequisites. The agent must infer the intended context from the name alone.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation profile is covered. The description adds meaningful context beyond that: 'Takes effect immediately', the two rejection predicates with codes, and the non-obvious fact that undefined facts do not block deployment. It omits auth/permission requirements and confirmation behavior, so it isn't fully exhaustive.

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

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

Front-loaded with the action and its immediacy, then the two rejection cases, then the non-blocking note. Four sentences, each carrying distinct routing or constraint information 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?

No output schema exists, and the description does not say what a successful deployment returns (deployment ID, status, etc.), which would help an agent chain subsequent calls. Otherwise it is complete: preconditions, failure modes, and the relevant sibling routing are all present for a 3-required-param mutation.

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% — memo, groupId, and versionId are all documented in the schema. The description adds no argument-level guidance (e.g., where versionId comes from, memo conventions), so baseline 3 is correct.

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

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

States a specific verb and resource ('Deploy an ACTIVE (published) version to live traffic') and names the sibling it is not (lexq_deploy_schedule). An agent can distinguish this from lexq_deploy_publish, lexq_deploy_schedule, and the other deploy_* siblings 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?

Gives explicit when-not conditions with error codes: versions whose start date has not arrived (P-037) route to lexq_deploy_schedule, and past-end versions (P-058) are rejected outright. It also routes the agent to lexq_facts_unregistered for reviewing undefined references, which is a genuine alternative-selection rule.

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 annotation readOnlyHint=true already signals a safe read operation, and the description aligns by saying 'Show', so no contradiction. The description adds useful context about the specific deployment attributes returned (version, type, deployer), but does not disclose any potential limitations, such as pagination, performance considerations, or whether the status is real-time or cached. With the annotation covering safety, a 3 is fair.

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

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

A single, terse sentence that front-loads the primary action ('Show current deployment status') and packs the specific fields into a clear list. No filler or 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?

For a parameter-less, read-only overview tool with no output schema, the description covers the essential purpose and the returned fields. It stops short of describing the exact response shape or any caveats (e.g., what happens if no groups are deployed), but these are minor given the tool's simplicity and the readOnlyHint annotation.

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 has zero parameters, so the schema carries no burden and the description doesn't need to explain parameters. Per the baseline for zero-parameter tools, a score of 4 is appropriate since the description provides no additional param semantics (there are none to provide).

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 ('Show'), a clear resource ('current deployment status of all groups'), and enumerates the exact fields returned (version, last deployment type, deployer). This clearly distinguishes it from other deploy tools like lexq_deploy_detail or lexq_deploy_history, which imply different scopes.

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

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

No guidance on when to use this tool versus its many deployment siblings. There is no mention of alternatives, prerequisites, or context in which this overview is preferable. The agent is left to infer from the name and description alone.

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

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

Goes well beyond the annotations: it discloses the irreversible lock on the version, the minimum-one-rule constraint, the fact that unread undefined facts do not block publishing, and three distinct failure conditions (ACT-032 targetVar not registered, 128 KB compiled-rule cap, P-058 expired effective end). That is exactly the operational detail an agent needs before invoking a mutation.

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

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

Front-loaded with the action and its side effect, then prerequisites, then failure modes. Highly dense with no filler, though the final sentence packs three failure conditions and a remedy into one long clause, slightly straining readability.

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

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

For a no-output-schema mutation tool, the description covers the transition, the lock, preconditions, and every known failure mode plus the remedy for each. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% and all three parameters (groupId, versionId, memo) are documented in the schema itself. The description adds no additional parameter semantics such as memo formatting expectations or id provenance, 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 with the state transition spelled out ("Publish a DRAFT version (DRAFT → ACTIVE)"), and immediately names the consequence ("Locks the version from further edits"). This is clearly distinguishable from siblings like lexq_deploy_deployable, lexq_versions_update, or lexq_versions_clone.

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

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

Gives concrete prerequisites and routes the agent to sibling tools: call lexq_facts_unregistered first to review undefined facts, or lexq_versions_update to move the end into the future before retrying. It does not, however, contrast this with lexq_deploy_deployable or explain when publishing is the wrong path, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the destructive nature is covered elsewhere. The description adds real behavioral context beyond that: the hard availability constraint referencing policy P-058. It doesn't state what happens to the currently live deployment or whether the action is reversible, 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 tight sentences, zero filler, with the core action front-loaded ahead of the availability caveat. Every clause earns its place.

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

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

For a destructive rollback with no output schema and fully documented parameters, the description covers what it does and the key gating condition. It leaves some minor gaps: effect on the current live version, permission requirements, and error behavior, none of which are blocking for correct invocation.

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

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

Schema description coverage is 100% and both parameters (memo, groupId) carry their own descriptions, so the schema does the heavy lifting. The description adds no additional meaning about the parameter formats or expectations. 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 target: roll back to the previous deployed version. This is clearly distinct from siblings like lexq_deploy_publish, lexq_deploy_undeploy, and lexq_deploy_schedule. It does not explicitly name a sibling it contrasts with, so it falls just 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?

Gives an explicit precondition for use: a previous version must be ACTIVE and its effective end must not have passed (P-058). That is genuine when-to-use guidance. It stops short of naming an alternative action (e.g., redeploy via publish/undeploy) when the precondition fails.

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 mark it as a non-read, non-destructive mutation; the description goes further by disclosing the one-pending-schedule-per-group constraint, the exact actions that cancel it (manual deploy/rollback/undeploy, A/B test start, group archive), and the fail-closed snapshot-hash re-verification. No permission/auth or response detail, but the behavioral disclosure is substantial.

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 dense but front-loaded sentences that lead with the core action and then layer constraints and guarantees. No filler; the parenthetical asides are compact, though the third sentence is information-dense enough to slow a quick scan.

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

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

For a 3-param mutation tool with no output schema and annotations covering only the safety profile, the description supplies the missing constraints, cancellation semantics, and execution guarantee. Only the success/return behavior is unaddressed, which is acceptable given no output schema exists.

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

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

Schema coverage is 100% and each parameter is already described in-schema, so the baseline is 3. The description adds only marginal semantics, clarifying that versionId's future effectiveFrom (not this call) supplies the timing, but nothing new about memo or groupId.

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 ('Schedule an ACTIVE version... to auto-deploy at that time') and contrasts behaviorally with the manual-deploy/rollback/undeploy and A/B-test siblings. An agent can tell this apart from lexq_deploy_schedules (list) and lexq_deploy_unschedule without opening schemas.

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

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

Clear context on applicability: the version must be ACTIVE with a future effective start date, and the time is set on the DRAFT via effectiveFrom rather than passed here. It does not name alternative tools explicitly, so an agent must infer 'use this instead of manual deploy when deferring', leaving one step of inference.

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

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

The readOnlyHint annotation already declares the operation safe, and the description adds valuable behavioral traits: the full set of statuses returned and the newest-first order. This prevents the agent from assuming only pending schedules are shown, exceeding what the structured annotation alone conveys.

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

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

The entire description is a single, efficient sentence. It front-loads the verb and resource, then appends the scope, status list, and ordering without filler or 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?

For a simple paginated list tool with only two fully documented parameters, the description covers scope, status coverage, and sort order. It does not describe the return item fields, but no output schema is defined and the core behavior an agent needs to invoke correctly is fully stated.

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

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

Schema description coverage is 100% for both 'page' and 'size', so the structured schema carries the full parameter meaning. The description adds no additional parameter-level guidance, and the baseline of 3 is appropriate when the schema handles the 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?

The description uses a specific verb ('List') and resource ('scheduled deployments'), then narrows scope with 'across all groups' and an explicit status enum (PENDING, EXECUTED, CANCELED, FAILED) plus an ordering rule (newest first). This fully distinguishes it from siblings like lexq_deploy_schedule (create) or lexq_deploy_history (deployment history).

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

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

The description clearly establishes its purpose as listing all scheduled deployments, with no exclusions for group or status, and states the ordering. It does not reference alternative tools for specific cases (e.g., deploy_history), but the context is clear enough that an agent knows when this list is needed.

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

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

Annotations already mark destructiveHint=true, and the description adds valuable nuance by explaining the version 'stays ACTIVE but no longer serves requests.' This clarifies the destructive nature is limited to traffic removal, not deletion, which is beyond the annotation's binary hint.

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 a single, front-loaded sentence that immediately conveys the core action and the crucial caveat. No filler or redundant wording.

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

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

For a simple tool with two documented required parameters and no output schema, the description covers the key behavioral outcome. It could mention whether the operation is immediate or reversible, but that is a minor gap given annotations already flag destructiveness.

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 params (memo and groupId) clearly described in the schema. The description adds no additional parameter meaning, so per the baseline for high coverage, a 3 is appropriate.

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

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

The description clearly states the action: 'Remove the live version from traffic' and clarifies the effect by noting the version stays ACTIVE. It distinguishes from deploy_publish and rollback by focusing on traffic removal, though it doesn't explicitly name alternatives.

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

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

No guidance is provided on when to use this tool versus related tools like deploy_publish, deploy_rollback, or deploy_schedule. The description only explains what it does, leaving the agent to infer the appropriate context.

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?

Discloses meaningful behavior beyond the destructiveHint: the deployed version remains unaffected)Skip and the call fails with a specific error code when no schedule exists. This is more transparent than most definitions for a mutation tool.

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

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

Two short sentences, front-loaded with the action, followed by the key caveat and error condition. No filler or repetition.

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

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

Adequate for a single-parameter tool with no output schema: the action, affected scope, non-affected scope, and failure mode are all covered. Lacks only explicit mention of when to choose this over related deploy-scheduling 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?

There is only one parameter and schema coverage is 100%, so the description adds little beyond the schema. The phrase 'for a group' does confirm the groupId semantics, but no deeper guidance is provided.

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 ('Cancel') and a specific resource ('pending scheduled deployment for a group'), making the action unmistakable. It also disambiguates scope by noting the version itself is not affected.

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 intended use is implied: cancel a group's pending scheduled deployment. The failure condition helps the agent know when not to call it, but it does not explicitly name sibling alternatives like lexq_deploy_schedule or lexq_deploy_schedules.

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

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

Annotations only declare readOnlyHint=false / destructiveHint=false. The description goes well beyond: it discloses non-destructive merge semantics ('never overwrites existing schema'), draft-only creation of the policy group, the specific error code and all-or-nothing failure behavior, and the isAvailable gate.

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?

Five tight sentences, front-loaded with the action and its side effects, then prerequisites and failure modes. No filler and every sentence carries operational information.

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

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

For a mutation tool with no output schema, the description covers the side effects, the merge semantics, the prerequisite sibling call, and the failure conditions an agent needs to call it safely.

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 are documented there, so the baseline of 3 applies. The description adds only indirect meaning (the policy group that customName names), without new syntax or constraint 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 (Apply) and resource (domain template) scoped to the current tenant, and immediately describes the concrete side effects (creates fact definitions and a draft policy group). It is clearly distinguishable from lexq_domain_templates_list and lexq_domain_templates_preview.

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 tells the agent to run lexq_domain_templates_preview first, states the exact condition under which apply fails (factConflicts non-empty → P-061, creates nothing) and the precondition that isAvailable must be true. When-to-use and when-not is fully covered.

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

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

Annotations already declare readOnlyHint=true, and the description adds genuinely useful context beyond that: what a domain template contains (facts + sample rules), the domain examples, and the shape of each entry (key, isAvailable, fact/rule counts). It does not mention pagination or ordering, keeping it short of a 5 for a list endpoint with 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?

Three sentences, zero waste: purpose first, domain concept second, return fields and workflow placement 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?

With no output schema, the description carries the return-value burden and does so by naming the per-entry fields. It is nearly complete, though ordering/pagination behavior and whether the list can be empty are left 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?

Zero parameters, so there is nothing to document; the schema is trivially complete. Baseline for a no-parameter tool, with no misleading param claims.

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

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

States a specific verb and resource ('List all domain templates') and immediately defines the domain-specific concept, distinguishing it from the apply/preview siblings. An agent can identify this as the discovery step without opening the schema.

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

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

Explicitly instructs 'Call this before preview or apply to see which templates exist,' naming the downstream alternatives (lexq_domain_templates_preview / _apply) and the condition that selects this tool. Nothing is left to inference.

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

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

Annotations only declare readOnlyHint=true; the description goes well beyond that by confirming 'nothing is created', explaining the semantics of factConflicts, the P-061 failure contract, and why plan may be null. This is exactly the kind of behavioral context annotations cannot carry.

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

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

Every sentence is load-bearing: the first defines the output, the second the dry-run guarantee, the third the conflict semantics and remediation, the fourth an edge case. Information is front-loaded 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?

There is no output schema, so the description must carry the return contract, and it does: it names the fact definitions, sample rules with descriptions, apply plan, and factConflicts, plus the P-061 failure mode. Nothing an agent needs to invoke or interpret the result 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 the single template parameter is already documented with a format example and a pointer to lexq_domain_templates_list. The description adds no new parameter-level detail, so the baseline of 3 applies.

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

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

The description opens with a specific verb+resource ('Preview exactly what a domain template will provision') and then enumerates the concrete payload: fact definitions, sample rules, and an apply plan. This clearly separates it from lexq_domain_templates_apply and lexq_domain_templates_list.

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 establishes the workflow context ('before applying it') and states the blocking condition clearly: while factConflicts is non-empty, apply fails with P-061 and nothing is created, so the user must delete or change those facts. It stops short of naming lexq_domain_templates_apply explicitly as the follow-up tool, but the implied usage 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?

Even with readOnlyHint=true already set, the description adds valuable behavioral context: 'without side effects,' normalized outputs, mutatedFacts delta keys, and per-rule traces. This goes well beyond the annotation and helps an agent understand exactly what a dry run does and returns.

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

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

The description is front-loaded with the core purpose and uses a clear bulleted return-value breakdown plus an example input. Every section earns its place; it is detailed without being bloated.

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

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

With no output schema, the description fully compensates by enumerating all return fields and their meanings. It also provides an example and usage guidance, making the tool callable correctly with minimal inference.

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 facts, versionId, and includeDebugInfo. The description contributes an example input and explains return behavior, but does not add much parameter-level meaning 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: 'Execute a single dry run against a version.' It clearly explains what the tool does and implicitly distinguishes itself from lexq_dry_run_compare by focusing on a single execution rather than comparison.

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

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

The description gives explicit when-to-use guidance: 'Always dry-run before publishing to validate rule behavior.' It does not name alternative tools or state when not to use it, but the single-run framing provides enough context to separate it from compare and simulation tools.

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

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

Annotations declare readOnlyHint=true, so safety is covered. The description adds value by detailing the return structure (resultA/resultB and diff fields), which is beyond annotations. It doesn't contradict annotations; no contradictions found.

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 concise, front-loading the purpose in the first sentence and then listing return fields. It is not overly verbose, and every sentence contributes relevant information, making it efficient for an agent to parse.

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 absence of an output schema, the description compensates by clearly outlining the return format and what the diff contains. It covers purpose, usage context, and expected results, leaving no critical gaps 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%, with each parameter individually described (e.g., 'Baseline version ID' and 'Candidate version ID'). The description adds a valuable semantic that 'facts' are the same for both versions, but it doesn't provide additional syntax or format 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?

States a specific verb ('Compare'), resource ('dry run results between two versions'), and scope ('using the same input facts'). Clearly distinguishes from lexq_dry_run (single run) and other diff tools like lexq_deploy_diff, as it is specifically for dry run comparisons.

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

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

The description includes 'Useful for validating changes,' which provides context for when to use it. However, it does not explicitly mention alternatives or conditions when not to use it, though the purpose itself is clear enough for an agent to select it over siblings.

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

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

Although readOnlyHint=true already signals a safe read, the description adds substantial behavioral context: a missing required fact throws rather than defaulting to 0, the P-015 error applies even when an earlier action wrote the fact, SET_FACT is the sole exception with no input fact, and its targetVar must be registered (ACT-032). It also labels the data as static and cacheable. This is well beyond what the annotation provides.

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

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

Purpose is front-loaded in sentence one, followed by dense but relevant clarification of the returned metadata's semantics. The description is long and reads partly as system documentation, but for a tool with no output schema each section helps interpret the response. Slightly sprawling, so not a 5.

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

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

With no output schema and no parameters, the description carries the full burden of explaining what the tool returns, and it does so: per-Action fact requirements, the meaning of factRequired, and the key exception cases. It is complete for the core semantics, though it does not enumerate the full shape of the returned metadata.

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?

This tool takes zero parameters, so the baseline is 4. The description's discussion of refVar/targetVar refers to the Action definitions being described, not this tool's own inputs, so it neither helps nor harms parameter semantics. No additional meaning is needed for a no-arg tool.

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 states a specific verb and resource: 'Retrieve runtime fact requirements per Action type.' It is clearly a read-only metadata lookup, distinct from the mutation siblings like lexq_facts_create/update/delete. It stops short of explicitly naming which sibling to prefer, so it lands at a strong 4 rather than 5.

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

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

Usage is implied by the domain content (call this when you need to know which facts each Action type requires) rather than stated. There is no explicit 'use this instead of X' guidance against neighbors such as lexq_facts_list or lexq_requirements. The caching note ('safe to cache in-session') gives a hint about repeated use but no selection criteria.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is known. The description adds nothing beyond that: it doesn't say what happens on a duplicate key, whether registration is versioned/idempotent, or what a successful call returns. For a creation tool this is a notable 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?

Three tight sentences that front-load the action and then the key format. Every sentence is short, though the key-pattern and type enumeration duplicate the schema rather than earning their space.

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 7 parameters with nested objects but full 100% schema coverage, and no output schema expected to be explained, the description is adequate: it covers the primary identifier format and the type vocabulary. Richer options (isPii, valueDomain) are fully handled by the 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%, so the schema already documents all 7 parameters, including isPii, isRequired, and valueDomain. The description's key-pattern and type-list sentences merely restate schema content (pattern regex, enum values) rather than adding new meaning, so 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 ("Register a new input variable") and follows with concrete constraints. It's unambiguous against lexq_facts_update/delete/list by virtue of the creation framing, though it never explicitly names siblings to distinguish itself.

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

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

No when-to-use guidance, no prerequisites, and no mention of the adjacent lexq_facts_update (for editing an existing fact) or lexq_facts_list. The format rules given are input-shape hints, not usage guidance.

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

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

Annotations already declare destructiveHint=true, but the description goes well beyond them: it explains which facts are protected, the exact error code (FD-006) and that the failure reports a reference count, and the nuance that rules in deleted groups are excluded from that count. This is exactly the failure-mode detail an agent needs before invoking a destructive 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?

Four short sentences, front-loaded with the action and followed by the blocking conditions. Every sentence carries a distinct constraint; nothing is redundant or 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?

For a single-parameter destructive tool with no output schema, the description covers preconditions and error behavior well. It does not address permissions/authorization requirements or whether the deletion is permanent or recoverable, which are the remaining gaps for a destructive operation.

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 (factId) and schema description coverage is 100%, so the schema already documents it as the fact definition UUID. The description adds no syntax, format, or lookup guidance beyond that, which is the expected baseline when the schema does the work.

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 ('Delete a fact definition'), which cleanly separates it from the sibling mutators lexq_facts_create and lexq_facts_update. The added precondition clauses make the scope of the operation 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?

Gives explicit when-not conditions: system facts cannot be deleted, and facts referenced by rules fail with FD-006. It also states the remediation path ('Remove the references first'). It stops short of naming an alternative tool for the cases it rejects, so it falls just below the top band.

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 description clearly discloses that the tool returns file contents as text, which is not obvious from the schema or the readOnly annotation. It also explains a non-obvious behavioral detail: JSON omits fields that the batch-create endpoint does not accept, while CSV includes system facts.

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 two sentences, front-loads the primary purpose, and packs meaningful format-specific behavior into a compact space. There is no repetition of the tool name or title and 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 tool with two parameters, a readOnly annotation, and no output schema, the description fully covers what the agent needs: what it returns (text), the two supported formats, and the behavioral difference between them. Nothing essential 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%, but the description enriches the 'format' parameter by explaining what each format is intended for and how their contents differ. The 'keyword' parameter is not additionally explained, but the schema already covers it adequately.

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 identifies the operation ('Export') and the resource ('the fact catalog'), and it explains what each format returns. However, it does not explicitly differentiate this from sibling tools like lexq_facts_list or lexq_facts_unregistered, relying on the reader to infer the distinction.

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

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

The description gives concrete usage guidance for choosing between CSV and JSON: CSV for spreadsheet reading, JSON for feeding back into the batch-create endpoint. It does not, however, explain when to choose export over other fact-related tools, so no tool-selection guidance is provided.

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

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

The annotation readOnlyHint: true already covers the safety profile, so the description adds modest value by mentioning it lists all definitions and includes PII status in the output. However, it does not add further behavioral details such as pagination behavior, rate limits, or response shape, which is acceptable given the 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 description is three short, purposeful sentences: what it does, what it shows, and when to use it. There is no fluff, and the most important information (lists all fact definitions) is front-loaded.

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

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

For a simple, read-only list operation with 3 optional and a well-documented schema, this description is sufficient: it defines the resource, the output highlights, and the primary usage context. It does not explain return envelope, but that aspect is not critical when the schema and annotations carry the rest.

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%: page, size, and keyword all have descriptive text. The tool description adds no additional meaning about parameter behavior, so the baseline score of 3 is appropriate.

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

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

The description explicitly states the verb 'List' and the resource 'all fact definitions (input variable schema)', and enumerates the fields returned: key, type, required, and PII status. It distinguishes itself from sibling fact operations like create/update/delete/export by focusing on the listing dimension and the schema nature.

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

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

The description gives an explicit use case: 'Always check this before creating rules.' This is a clear directive for when to call the tool. It does not mention when not to call it or alternatives like lexq_facts_unregistered, but the in-context workflow guidance is solid.

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

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

readOnlyHint is already declared, so the bar is lower, yet the description adds genuine value: the version-wide coverage scope, the fact that read-only-referenced keys don't block deploy, the ACT-032 rejection behavior at save/publish, and what each entry carries (inferred type, suggested name, reference site). These behavioral details go well beyond the annotation.

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, then progressively adds remediation and versioning context. Dense but tightly packed; the parenthetical '(read-only)' is slightly redundant given the annotation.

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

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

For a read-only list tool with no output schema, the description usefully enumerates the shape of each entry (inferred type, suggested name, reference location), so an agent knows what to expect without a return schema. Complete enough for correct invocation.

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

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

Schema description coverage is 100% and both required params (groupId, versionId) are documented in the schema, so baseline is 3. The description implies version-scoping but adds no format or semantics beyond what the schema already provides.

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

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

States a specific verb+resource+scope: 'List facts referenced by a version's rules but not yet defined (read-only).' This clearly distinguishes it from the sibling lexq_facts_list (registered facts) and from lexq_facts_create (registration).

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?

Explains when the output matters (read-only keys don't block publish/deploy, but action targets are rejected with ACT-032) and routes the agent to lexq_facts_create to remediate. No explicit when-not or alternative comparison, but the context for using it is clear.

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

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

Goes well beyond the readOnly=false / destructive=true annotations by disclosing error codes (FD-007, FD-003), the key immutability rule, partial-update semantics, and special handling for system facts (isBlocked/blockReason). This is exactly the kind of mutation-behavior context annotations cannot convey.

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?

Dense but front-loaded: purpose first, then immutable field, then the type-change rule with its error code, then partial-update semantics, then system-fact exceptions. Every sentence carries distinct, actionable information 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 mutation tool with a nested valueDomain object and no output schema, the description covers failure modes and field-level constraints well. It stops short of describing the response shape after a successful update, which is a minor gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: key immutability, the conditional nature of type changes, and which fields system facts accept versus ignore. That is useful value on top of an already well-documented 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 ('Update a fact definition'), which is unambiguous against siblings like lexq_facts_create or lexq_facts_delete. It does not explicitly name a sibling to distinguish from, but the name and verb make the intent obvious.

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

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

Gives concrete preconditions that determine whether the call will succeed: type changes require no referencing rule, deleted-group rules don't count, and only sent fields change. It lacks explicit routing to alternatives, but the conditional constraints effectively tell the agent when and how to invoke it.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false. The description adds real behavioral context the annotations cannot: priority is auto-assigned and appended last, the tenant-wide cap of 20 non-ARCHIVED groups, and the cluster constraint that groups sharing an activationGroup must share mode/strategy/executionLimit. It does not describe error responses or what happens on cap violation, so 4 rather than 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?

Four sentences, front-loaded with the core action and the required field, then escalating to optional fields and constraints. Dense but every sentence carries information; the trailing cap/cluster sentence is long though warranted.

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

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

For a mutation tool with no output schema and 100% schema coverage, the description supplies the missing operational context: auto-assigned priority, the quota, and the inter-parameter cluster constraint. Only error/failure behavior remains unstated, which is a minor gap.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by disclosing a cross-parameter constraint (groups sharing an activationGroup must share activationMode/activationStrategy/executionLimit) and by clarifying that executionLimit counts groups rather than rules. That added semantic layer justifies 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 ('Create a new policy group') and immediately differentiates itself from siblings by naming lexq_groups_reorder as the tool for changing order. An agent can distinguish it from lexq_groups_update, lexq_groups_delete and lexq_groups_get 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?

Gives clear usage context: priority is auto-assigned and reorder is the alternative tool, optional fields are enumerated, and the 20-group cap with an archive-to-free-a-slot hint tells the agent when this call will fail. It lacks an explicit when-not-to-use statement (e.g., prefer update for existing groups), which keeps it at 4 rather than 5.

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

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

Goes far beyond the destructiveHint=true annotation: irreversibility ('cannot be undone'), name reuse behavior, visibility change in lexq_groups_list, the full set of conflicting operations returning 409 P-059, audit retention rules, and the 30-day permanent-deletion window.

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, then the blocking precondition, then consequences and error codes. Dense but every sentence carries distinct operational information; nothing is redundant or 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?

For a single-parameter destructive tool with no output schema, the description covers the safety profile, prerequisites, post-conditions, error semantics, and retention behavior. Nothing an agent needs to call it correctly is missing.

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

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

Only one parameter (groupId) and schema description coverage is 100%, so the schema already fully documents it as a UUID with a strict pattern. The description adds no syntax, format, or constraint detail beyond what the schema provides. Baseline 3 per the high-coverage rule.

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 ('Delete (archive) a policy group') with the parenthetical clarifying the actual semantics (archive, not hard delete). Clearly distinguishable from siblings like lexq_groups_update or lexq_groups_reorder.

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

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

Explicitly states the precondition that blocks deletion (deployed groups, P-020) and names the sibling tool to call first (lexq_deploy_undeploy), including the side effect that undeploying also ends a running A/B test. Enumerates the operations that will fail afterwards with 409 P-059.

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 annotation readOnlyHint already describes the safety profile. The description adds no additional behavioral over that, e.g., no mention of not-found behavior, error responses, or any other edge cases. It simply repeats the 'get' conceptual, so it adds little beyond 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?

One short sentence with no excess, the purpose is front-loaded and immediately clear. Perfect for a tool this simple.

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 extremely simple: a single parameter, a read-only annotation, no output schema needed. The description covers all that is required to call it, and nothing additional is needed to be parsed beyond the simplicity.

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 parameter groupId, which has a clear description and strong validation. The description's 'by ID' adds only a lexical echo, no deeper semantic than the schema already provides.

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

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

The description states a specific verb ('Get'), resource ('single policy group'), and key discriminator ('by ID'). This unambiguously distinguishes it from sibling create/update/delete/list/reorder group tools.

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

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

The description clearly implies when to use: when you need one group and know its ID. The sibling list tool covers the alternative, but this description does not explicitly state 'use lexq_groups_list instead for multiple groups', so it loses the point for explicit when-not.

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

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

Annotations only declare readOnlyHint=true, so the description adds genuine behavioral context: results are tenant-wide, sorted by priority ascending, and exclude deleted groups. It omits pagination behavior or result limits, which would be the remaining useful detail.

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, zero filler, with the core scope statement front-loaded before the exclusion detail. Nothing needs trimming or reordering.

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

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

No output schema exists, so the description could say more about what a returned group contains (id, name, priority field shapes) or whether results are paginated. For a simple tenant-wide list with readOnly annotation coverage, the essentials are present.

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

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

The tool takes no parameters, so there is nothing for the description to clarify; the schema is empty and complete. Baseline of 4 applies for a zero-parameter tool.

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

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

States a specific verb and resource ('List policy groups') and adds real scope information (tenant-wide, priority ASC). The verb clearly separates it from lexq_groups_get/create/update/delete siblings, though it never names them 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?

Usage is implied by being a zero-parameter list operation, but the description gives no explicit when-to-use guidance or alternatives (e.g., use lexq_groups_get for a single group). No exclusions are stated beyond deleted groups being absent.

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 indicate destructiveHint=true and readOnlyHint=false, so the tool is known to be a write operation. The description adds valuable context beyond annotations: priority is tenant-wide and flat (continuous), array index 0 maps to priority 1, and activationGroup is unaffected. This explains exactly what changes and what does not, which is more transparent than just 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?

The description is two sentences, front-loaded with the action and key constraints. Every sentence adds essential information: the reordering action, the priority model, and the exclusion of activationGroup. There is no filler or redundancy, making it highly concise and well-structured.

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 tool's simplicity (one parameter, no output schema, no nested objects), the description covers the core requirements: what the tool does, how priority ordering works, and what is not affected. It does not explicitly state whether the groupIds array must contain all groups or if partial reordering is allowed, but this may be inferred from the continuous priority model. Overall, it is sufficiently complete for an agent to call the 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 coverage is 100% because the sole parameter groupIds has a description: 'Group IDs in desired priority order (index 0 = priority 1)'. The description adds further meaning by clarifying that priority is continuous and tenant-wide, and that activationGroup is not affected. This goes beyond the schema's basic ordering semantics, providing useful context for constructing the array correctly.

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 action: 'Reorder policy groups by priority.' It specifies the resource (policy groups), the operation (reorder), and the key constraint (priority is tenant-wide and flat). It also distinguishes itself from sibling tools like lexq_groups_update by clarifying that only priority changes and activationGroup is unaffected. This is specific and 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?

The description provides clear context for when to use the tool: when reordering policy groups by priority. It explicitly states what it does not affect (activationGroup), which helps set expectations. However, it does not explicitly name alternative tools or conditions for choosing this over others, though the scope is so narrow that an agent can infer the appropriate usage.

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

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

Annotations declare readOnlyHint=false and destructiveHint=true, so the safety profile is already covered. The description adds genuinely new behavioral context: only supplied fields change, omitted fields persist, and the update fails with a specific 409/P-059 on deleted groups. It stops short of stating auth requirements or whether the mutation is reversible.

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

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

Three short sentences, zero filler: identity first, then the mutation contract, then the failure case. Every sentence carries decision-relevant information and nothing is repeated from the schema.

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

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

For a mutation tool with no output schema, the description plus annotations cover the essentials — what mutates, what is preserved, and the one documented failure mode. Missing only peripheral detail such as required scopes or what the response returns, which is minor here.

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

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

Schema coverage is 100%, so the baseline would be 3. The description earns above baseline by stating the cross-cutting optional-field contract (omitted fields are left unchanged), which governs how all seven optional parameters behave and is not expressed anywhere in the schema.

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

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

States a specific verb+resource ('Update a policy group') that an agent can immediately place against the sibling CRUD set (lexq_groups_create/delete/get/list/reorder). It also distinguishes this from a full replace by stating partial-update semantics, though it doesn't name a sibling to route away from.

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 real conditional: omitted fields remain unchanged (patch semantics), and a hard exclusion — a deleted group cannot be updated (409 P-059). However, it offers no guidance on when to reach for this tool versus lexq_groups_delete, lexq_groups_reorder, or lexq_deploy_rollback/undeploy for version-level changes.

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

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

The readOnlyHint annotation already signals a safe read operation, so the description doesn't need to repeat that. It does add value by listing the exact fields returned in the detail, which is essential since there is no output schema. This goes beyond the annotation by disclosing the content of the response, though it doesn't mention any other behavioral aspects like pagination or error conditions, which are less critical for a simple fetch.

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 a single concise sentence that efficiently conveys the tool's purpose and the key details of its output. There is no fluff or redundancy; every word adds value, and the list of fields is front-loaded, making it easy to scan.

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 tool with one required parameter and no output schema, the description is fairly complete. It lists all the key returned fields and clearly indicates what the tool does. However, it omits any mention of how to interpret the response (e.g., whether it's a single object or array) or any potential error cases, which would be useful but not essential for a simple read operation. Overall, the description provides enough 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?

The input schema already fully describes the single parameter (traceId) with the explanation 'Trace ID from execution history'. The description does not add any additional semantic meaning beyond repeating that the parameter is a trace ID. Since schema coverage is 100%, a baseline of 3 is appropriate; the description provides no extra clarity 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 (Get) and resource (full execution detail) and enumerates the exact fields returned (inputFacts, mutatedFacts, generatedVariables, executionTraces, decisionTraces). This distinguishes it from sibling tools like lexq_history_list (which likely lists executions) and lexq_history_stats (statistics), so an agent can immediately understand what this tool does and where it fits.

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

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

The description implies usage context by mentioning 'traceId' and 'execution detail', but it does not explicitly state when to use this tool over alternatives like lexq_history_list or lexq_replay_decision. There is no explicit 'use this when' or 'instead of' guidance, so the agent must infer the usage scenario from the name and parameter.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds value by naming the returned fields (trace ID, group, version, status, match result, latency), but says nothing about ordering, pagination behavior, or result volume, which matter for an 8-param list 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?

Two short sentences with the purpose front-loaded and no wasted words. It is efficient, though the second sentence reads more like a field inventory than decision-relevant 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 no output schema present, the description usefully enumerates the returned fields, and readOnlyHint covers safety; the fully-described schema covers inputs. The main gap is the lack of differentiation from sibling history tools, but the definition is broadly complete for calling the tool.

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

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

Schema description coverage is 100%, so all 8 parameters (including enum status and the time-zone-aware date fields) are already documented in the schema. The description adds no parameter-level detail beyond echoing the field names, 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 (List) and resource (policy execution history), so the core intent is clear. However, it does not distinguish itself from the closely-related siblings lexq_history_get and lexq_history_stats, which an agent would need to tell apart.

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

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

The description gives no guidance on when to use this versus lexq_history_get (single record) or lexq_history_stats (aggregated), nor any prerequisites or filtering context. Usage must be inferred from the name alone.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds genuine beyond-annotation context: the implicit default window, the per-call range cap, the error code on violation, and the startDate-only 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?

Four tight sentences; the purpose and returned metrics are front-loaded, followed by the temporal constraints. 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?

No output schema exists, so the description compensates by enumerating the returned KPIs; temporal defaults, limits, and error behavior are all covered. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics the schema lacks: what happens when no dates are supplied and that a lone startDate runs through today.

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

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

Specific verb+resource ('Get execution KPIs') with an enumeration of the exact metrics returned (total executions, success/failure counts, success rate, average latency). An agent can distinguish it from lexq_history_get/lexq_history_list by the aggregate nature, though no sibling is named 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 clear operational context: default 30-day window when dates are omitted, tenant-timezone interpretation, and a 31-day max with the AN-039 rejection. It does not, however, say when to prefer this over the sibling history list/get tools.

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 (readOnlyHint=false, destructiveHint=false) indicate a non-read-only operation, and the description adds the meanings of RESOLVE and IGNORE. But there is no disclosure of downstream side effects: whether RESOLVE affects replay/statistics, whether IGNORE is reversible, or whether the action is idempotent. For a state-changing tool with neutral destructiveHint, the description should explain consequences.

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?

Single sentence, front-loaded with the verb and the two action options. No filler; every word contributes.

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

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

For a simple two-parameter action the description is mostly sufficient, but it does not state side effects (e.g., whether RESOLVE affects statistics or downstream replay/decision behavior) or whether actions are reversible. Given no output schema and generic annotations, a bit more behavioral context would round it out.

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

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

Schema already covers both required params and one enum. The description adds semantic meaning to the enum values — 'mark as manually fixed' vs 'skip intentionally' — which helps an agent choose the correct action. It also clarifies the log scope (single failure log) which disambiguates the logId parameter's granularity.

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 clear verb and resource: process a single failure log, with the two specific actions RESOLVE and IGNORE. It distinguishes this from sibling tools in the lexq_logs_* family by emphasizing 'single' log processing. However, it doesn't explicitly contrast with lexq_logs_bulk_action or lexq_logs_get, so it's strong but not fully differentiated.

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 'Process a single failure log' implies this is for one log at a time, which lightly separates it from the bulk sibling. However, there is no explicit guidance on when to choose RESOLVE vs IGNORE, when to prefer this over lexq_logs_bulk_action, or any 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 establish that this is a write operation (readOnlyHint=false, destructiveHint=false), so the bar is lower. The description adds that an action is applied to the provided logs, which aligns with the annotation profile. However, it discloses nothing beyond that: no side effects, no behavior on invalid or duplicate IDs, and no statement of partial-success semantics.

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 that front-load the purpose. The second sentence ('Provide an array of log IDs and the action') is slightly redundant with the required schema but is harmless and keeps the description lean. Nearly every word earns its place.

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

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

For a bulk mutation tool with no output schema, the description gives no sense of what happens after the call — no confirmation behavior, no partial-failure handling, no indication that all logs must be in a valid state for the action to apply. The minimal instruction is enough to attempt the call, but an agent cannot predict side effects or error modes.

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 fully documents logIds (UUID format) and action (IGNORE/RESOLVE enum). The description's 'Provide an array of log IDs and the action' essentially restates the schema requirements without adding new semantics, 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 uses a specific verb ('Process') with a specific resource ('failure logs') and scope ('multiple... at once'), making the core purpose clear. It differentiates from lexq_logs_action mostly through the 'bulk' naming and the 'multiple' qualifier, though it never names the 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?

No when-to-use or when-not-to-use guidance is given. The description does not direct the agent to lexq_logs_action for single-log cases, does not explain how IGNORE versus RESOLVE should be chosen, and states no exclusions or prerequisites. Usage context must be inferred entirely from the tool name and schema.

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 annotation readOnlyHint already covers the read-only safety profile, lowering the bar. The description adds only that this is a get-by-ID operation and does not mention return format, permissions, or error behavior. It does not contradict the annotation.

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 a single, front-loaded sentence that clearly states the action. No filler words, and it earns its place entirely.

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 has one required parameter and no output schema, so the description is sufficient for its simplicity. However, it does not mention what 'detail' includes or what response to expect, which could a small gap.

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

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

Schema description coverage is 100%, and the schema already documents logId as a required UUID. The description's 'by ID' adds little beyond the schema, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb (Get) and naming the resource (failure log detail) with a clear scope (by ID). It distinguishes from sibling tools like lexq_logs_list (list vs get) and lexq_logs_action, but it does not name an alternative 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?

Usage is implied by the phrase 'by ID' and the parameter name logId, but the description does not state when to use this tool versus alternatives, such as lexq_history_list or lexq_logs_list. No exclusion guidance is provided.

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

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

The readOnlyHint annotation already establishes the safe-read profile, and the description adds meaningful behavioral context on top: the implicit 7-day lookback window and the organization-time-zone interpretation of that window. It stops short of describing pagination or result ordering behavior, 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 tight sentences with no filler, and the core identification of the resource is front-loaded ahead of the date-window detail. Every clause carries information the agent can act on.

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

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

For a read-only list tool with seven fully documented schema parameters and a readOnlyHint, the description covers the essentials and adds the non-obvious default-window rule. The only gap is that it says nothing about the shape of a returned log entry, which with no output schema would have been useful.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the per-parameter text: it explains that omitting dates yields a 7-day window in the organization time zone and that startDate is the lever for going further back. That is date-parameter behavior the schema does not state, though other parameters (status, taskType, keyword) get no mention.

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 ('List system failure logs from background tasks') and narrows the scope with concrete examples ('platform event webhooks, scheduled deployments'), so an agent immediately knows what is returned. It does not distinguish itself from sibling log tools such as lexq_logs_get or lexq_logs_action, which prevents a 5.

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

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

It gives genuine usage context for the date parameters: the default 7-day window and the instruction to 'pass startDate to look further back.' However, it offers no guidance on when to pick this list tool over the sibling log tools (lexq_logs_get, lexq_logs_action, lexq_logs_bulk_action), so usage is only partially framed.

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

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

With readOnlyHint=true already covering the safety profile, the description adds a genuinely important disclosure: 'Metadata only; revealed values are never stored or returned.' This bounds what an agent can expect from a PII-adjacent audit endpoint. Pagination/ordering behavior is not described, but the schema covers paging.

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 waste, and the ledger scope is front-loaded ahead of the usage guidance. Every clause earns its place, including the metadata-only guarantee.

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

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

For a read-only, zero-required-param list endpoint with a fully documented schema and no output schema, the description supplies what the schema cannot: the meaning of the ledger and the privacy guarantee. Return shape and ordering are left implicit, which is a minor gap for an audit-listing tool.

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

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

Schema description coverage is 100%, including the non-obvious timezone semantics for startDate/endDate, so the schema carries the parameter burden. The description adds no filter syntax or date-format detail beyond what is already structured, making the baseline 3 appropriate.

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

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

States a specific verb (List) and resource (PII reveal audit ledger) with a precise enumeration of what it captures — who revealed which fact of which trace, and when. No sibling tool covers this audit surface, so it is distinguishable 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 clear usage context ('monthly access-log inspection and SIEM collection'), which tells an agent the scenario that selects this tool. It does not name an alternative tool or state when not to use it, so it stops short of explicit routing.

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

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

The description goes well beyond the readOnlyHint annotation, disclosing sampling behavior (deterministic 1% sample for rule detail, TOTAL for every call), display gates (n×(1−q) ≥ 3), judgment gates (n ≥ 100), INSUFFICIENT_COHORT behavior, and the slow-rule flag formula. It also explains that percentiles can be null and why. This is rich behavioral context that an agent needs to interpret results correctly.

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 dense but well-organized, front-loading the core purpose and then explaining gates and defaults. Every sentence adds value, though the density of statistical details (display gate formula, thresholds) could be slightly overwhelming. It's appropriately sized for the complexity of the 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?

For a read-only analytics tool with no output schema, the description covers the key things an agent needs: what data is returned, how it's sampled, what gates apply, what edge cases look like (INSUFFICIENT_COHORT), and defaults. The absence of an output schema is compensated by the detailed description of the result structure.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds context about defaults (last 24h, live version, cacheState HIT) and the cacheState meaning (HIT = compiled ruleset cache hit, MISS = deep-load + compile), which enriches the enum semantics. However, it doesn't add much beyond what the schema provides for individual parameters, so 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?

The description clearly states it provides a per-rule latency profile of a policy group over a time window, with specific components: TOTAL distribution split by cache state, per-rule CONDITION/ACTION percentile table, and slow-rule flags. It distinguishes itself from siblings like lexq_profile_rule by focusing on group-level overview with per-rule breakdown.

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

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

The description explains the default time window, version, and cache state, and mentions the judgment gate (n ≥ 100) and display gate. It doesn't explicitly state when to use this vs alternatives like lexq_profile_rule, but the name and content make the group-vs-rule distinction clear. It also notes that absolute thresholds are intentionally not supported, which helps set expectations.

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

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

With readOnlyHint:true already covering the read-only nature, the description adds substantial behavioral context: missing windows are genuine gaps (never interpolated), percentile withholding conditions with exact sample thresholds, and the flagged definition including the explicit note that absolute thresholds are unsupported. These details are not present in annotations or schema and are critical for interpreting results correctly.

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 a single, dense sentence that front-loads the core purpose and then packs in critical data-handling rules. It is efficient with no filler, though the density of clauses makes it slightly harder to parse at a glance. Every piece of information earns its place, so it is highly concise, but the structural density slightly reduces readability.

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 there is no output schema, the description thoroughly explains what the tool returns: the distributions, time series, handling of missing windows, percentile reliability conditions, and the flagged definition. An agent has enough information to understand the result and its caveats without needing additional documentation. The 5-parameter tool with 2 required is well-served by this description.

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 schema has 100% parameter description coverage, so all five parameters are already documented. The description adds no parameter-specific semantics beyond what the schema provides (e.g., from/to as window boundaries are already described). It does reference the 60s window granularity, which subtly reinforces the meaning of from/to, but this is not a significant addition.

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 resource ('Single-rule latency detail') and the exact data it returns (merged phase × cacheState distributions plus a per-window time series). This clearly distinguishes it from siblings like lexq_profile_overview, which is the group-level counterpart. The verb is implicit but the resource and scope are unmistakable.

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

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

The description implies usage through its name and specificity (single-rule detail vs. overview), but it does not explicitly state when to choose this over lexq_profile_overview or any other alternative. No exclusions or alternative routing are mentioned, leaving the agent to infer the intended use case from naming conventions.

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

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

Goes beyond the readOnlyHint by disclosing that PII values are masked, that masking is represented via maskedKeys, and that unmasked values are only available through an audited console path. This is meaningful behavioral information for an agent handling sensitive data.

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

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

One dense sentence front-loaded with the core action and resource, followed by a compact enumeration of response contents. All clauses add information, though the long comma-separated list slightly reduces skimmability.

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

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

With no output schema, the description compensates well by enumerating the major returned components: decision outcome, per-rule rationale, responsibility chain, masking behavior, and snapshot fingerprint. An agent can predict the response shape well enough to call the tool safely. Minor omissions like error behavior are acceptable for a simple get-by-ID tool.

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

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

The single parameter traceId is already documented in the schema, and the description adds little about how to obtain or validate a traceId. Schema coverage is effectively complete, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource ('Get the lineage of a single decision') and enumerates the key components returned. It is clearly distinct from broader history or listing tools, though it does not explicitly name sibling alternatives.

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

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

The description implies usage: an agent should call this when it needs decision-level provenance rather than general history or logs. However, it does not explicitly state when to prefer this over lexq_history_get or lexq_logs_get, so routing to the right sibling 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 mark the tool as destructive, so the description adds value by narrowing behavior: only pending/running jobs are cancellable, other states are rejected, and viewer-role callers cannot invoke it. It also introduces the 'cooperative' nuance, which conveys a graceful cancellation process rather than a hard kill. This exceeds the structured 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?

Two sentences, front-loaded with the action and target, and immediately followed by the two key constraints (state and role). No filler or redundant restatement of the tool name.

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

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

A single-parameter cancellation tool is well-covered by the state and role constraints in the description. Given the destructiveHint annotation, the risks are clear. It could improve by stating what a successful cancellation means for the job's resulting state, but it is adequate for invocation.

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

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

Schema coverage is 100%, with the only parameter already described as 'Replay job ID'. The description does not add param-level detail such as format or origin. This matches the baseline for fully covered 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?

Description states a specific verb ('cancel') and resource ('replay job'), and further scopes to 'PENDING or RUNNING' states, setting it apart from replay list/start/status tools. 'Cooperatively' adds a nuance of graceful cancellation. This is clear and specific.

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

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

The description explicitly says 'PENDING or RUNNING' can be canceled and 'Other states are rejected,' which tells the agent when it should not be invoked. It also gives a role-based precondition ('VIEWER role cannot cancel'), but it does not explicitly name alternatives or when to prefer a different replay tool.

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

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

Adds valuable behavior beyond the readOnlyHint: synchronous execution, free of charge with TPS throttle, and no webhooks/events or outward side effects from rule actions. This materially informs safe invocation.

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 dense sentences, front-loaded with the core purpose and immediately followed by cost and side-effect caveats. No filler or repetition.

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

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

For a 2-parameter, read-only operation with no output schema, the description covers inputs, return contents, safety profile, cost, and sync-ness. Nothing essential is missing for selection and invocation.

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

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

Schema description coverage is high (both params documented). The description restates the role of traceId and candidateVersionId in context but does not add meaningful parameter detail beyond the schema.

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

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

The description names a specific verb and resource ('Re-evaluate a past execution against a candidate version') and specifies what is returned (decision diff plus determinism verdict), clearly distinguishing the action from replay list/status operations.

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

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

Provides clear context for use (synchronous, read-only evaluation of a past trace against a candidate version) and adds cost/behavior notes, but does not explicitly contrast with related sibling tools like dry-run or deploy-diff.

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 description goes well beyond the readOnlyHint annotation by revealing the literal return behavior: the file contents are returned as text, not as a pointer or attachment. It also explains the non-obvious semantic difference between CSV and JSON, including tenant-specific JSON keys, which is exactly the kind of behavior an agent cannot infer from the schema.

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

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

The description front-loads the most important constraint ('COMPLETED') and then spends every sentence on functional distinctions that affect agent decisions: success state, format semantics, and return shape. There is no filler or repetition of the schema's plain parameter descriptions.

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 tool with no output schema, the description compensates well by stating that the result is returned as text and explaining what the text contains per format. It still leaves some ambiguity about exact JSON/CSV structure and error handling for nonexistent jobs or bad job IDs, but an agent can decide whether to call it confidently.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning to the format parameter by explaining exactly what each format contains and by warning that JSON is not a superset of CSV. It does not add much about how to obtain a jobId, but the schema and context make that secondary.

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 resource, a 'COMPLETED window replay job', and a clear action, export, while adding the state qualifier that distinguishes it from still-running jobs. This is far more specific than the title alone and separates it from export tools for simulations or facts.

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

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

The description clearly tells the agent to export only completed jobs and explains that running jobs are rejected, with the underlying reason. It also gives concrete guidance on choosing CSV versus JSON based on what each format contains. It stops short of naming an explicit alternative for non-replay exports, so it earns 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?

The readOnlyHint annotation already conveys that this is a safe, non-mutating operation. The description adds useful context by noting reverse-chronological ordering and that items are lightweight, but it does not describe what shape the returned history entries take or touch on pagination behavior.

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

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

Two short, purposeful sentences with no wasted words. The core operation appears first, followed by ordering and the sibling-tool pointer.

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

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

For a simple paginated list with readOnlyHint and no required parameters, the description covers the essentials: what is listed, the ordering, and when to use a sibling instead. It does not spell out the exact output shape, but the tool is simple enough that this is only 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%, so the page and size parameters are already fully documented. The description does not add per-parameter detail beyond the schema, though the reverse-chronological ordering indirectly clarifies how pages progress.

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 action and resource: listing window replay job history in reverse-chronological order. It also differentiates this tool from lexq_replay_status by noting its lightweight item payload.

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 directs callers to lexq_replay_status when they need a summary and changed samples, giving the agent a clear heuristic for choosing between these sibling tools. The phrase 'use lexq_replay_status for...' makes the alternative and its purpose concrete.

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

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

With annotations only covering readOnlyHint=false and destructiveHint=false, the description adds real behavioral context: the job is asynchronous, it is metered ('Billed per replayed record (REPLAY metric)'), and it is role-gated. It still omits cost magnitude, concurrency limits, and whether the job can be cancelled (lexq_replay_cancel exists as a sibling).

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 dense sentences with the purpose and measurement outcome front-loaded, followed by the operational constraints. No filler, and the routing hint lands last where it is most actionable.

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

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

For a 4-param async job tool with no output schema, the description covers what the job does, that it is async, that it costs money, and how to poll. It does not say where results land or what the job payload looks like on completion, though lexq_replay_status and lexq_replay_export cover that.

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

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

Schema description coverage is 100%, so from/to timezone semantics, the maxRecords cap, and candidateVersionId are already fully documented in the schema. The description adds no parameter-level 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 gives a precise verb and resource ('Submit an async job that replays a date window of past executions against a candidate version') plus the defining output ('measures the blast radius (how many decisions change)'). That outcome framing clearly separates it from the simulation/dry-run siblings without needing to enumerate 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?

It states the follow-up workflow explicitly ('Poll with lexq_replay_status') and a hard precondition ('VIEWER role cannot submit'), which tells the agent both how to proceed and who may call it. It stops short of naming the nearest alternatives (lexq_simulation_start, lexq_dry_run) or when blast-radius replay is preferred over them.

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

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

With readOnlyHint=true already in annotations, the description adds substantial runtime semantics: RUNNING reports progress 0–100, COMPLETED fills summary and changedSamples, FAILED carries errorMessage, and capped=true explains partial replay. These details give an agent a complete contract for interpreting the returned state without needing an 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?

Three sentences deliver the core action, the status mapping, and the capped special case. Every sentence carries functional information; the task is clear in the first sentence and the remaining clauses are dense but essential.

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?

Since there is no output schema, the description must and does explain what state values mean and what fields appear in the COMPLETED and FAILED cases. The capped flag is also clarified. With a single required parameter and all runtime states disclosed, nothing an agent needs to call and interpret this tool correctly is omitted.

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 only parameter jobId already has a 100% descriptive schema reference ('Replay job ID from lexq_replay_start'), so the description adds little beyond reiterating that the tool polls a window replay job. With high schema coverage, baseline 3 applies and no compensation is required.

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

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

The description opens with a specific verb and resource ('Poll a window replay job') and names the outcome states. This clearly distinguishes the tool from action-based replay siblings like lexq_replay_start, lexq_replay_cancel, and lexq_replay_export, as well as from the parallel lexq_simulation_status.

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 'Poll a window replay job' establishes the intended context: the agent is checking the progress or completion of an earlier replay job. It does not explicitly point to lexq_replay_start as the source of jobId or warn against using it for other purposes, but the role of a status poller is unambiguous and the naming matches the sibling set.

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 annotation readOnlyHint=true already signals a safe read operation. The description adds that it returns required keys, types, and an example request body, which is useful but not extensive. No contradictions with annotations, but no additional depth on permissions or response 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?

Two concise sentences, front-loaded with the core purpose and immediately clarifying return value. No fluff or redundant 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 simple read-only tool with two well-documented parameters, the description covers purpose and output. It lacks usage context (when to call it), but that is a minor gap given the straightforward nature and available annotations.

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 both groupId and versionId having descriptive names. The description does not add extra meaning beyond the schema, so 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?

The description clearly states the tool analyzes which input facts a version requires, with a specific verb and resource. It also mentions return content (keys, types, example body). It does not explicitly differentiate from siblings, but the function is distinct enough among the many lexq_* tools.

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

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

No guidance on when to use this tool versus alternatives. There is no mention of exclusions, prerequisites, or sibling tools. The description only states what it does, leaving the agent to infer applicability.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false. The description adds substantial behavior: priority is auto-appended, rules are created in DRAFT versions, unregistered targetVars fail with ACT-032, BLOCK does not halt execution, evaluation order is condition-first-then-actions, and error codes P-015 and ACT-033 are documented.

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 very long, but well structured with front-loaded core behavior followed by condition, action, and evaluation details. Most sentences carry essential constraints, though the length is closer to a specification than a concise tool description.

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

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

Given the complexity of rule creation, the absence of an output schema, and minimal annotations, the description is exceptionally complete. It covers draft scope, fact registration, condition and action schemas, limits, operator validity, evaluation order, and error cases.

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%, but the schema only provides shallow descriptions for groupId, versionId, and a JSON string rule. The description adds deep semantics for the rule object: condition tree grammar, operator constraints by fact type, action schemas, the operator × method matrix, value types, limits, and rounding options.

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

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

The description opens with a specific verb and resource: 'Create a rule in a DRAFT version.' It immediately states required inputs (name, condition tree, actions array) and distinguishes itself from lexq_rules_reorder, which it names for changing priority order.

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 guides when to check facts with lexq_facts_list, when to ask the user before calling lexq_facts_create, when to use lexq_facts_unregistered after saving, and which tool to use for reordering. Alternatives and prerequisites are named directly.

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

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

Annotations already declare destructiveHint: true, so the description only needs to add context beyond that. It adds the draft-version constraint, which is useful. However, it does not disclose that deleting the last rule in a version requires confirmation, nor does it explain the role of the 'force' parameter or any side effects. The description adds some value but misses important behavioral nuances.

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 a single, concise sentence that is entirely front-loaded with the action and the draft-version constraint. There is no fluff, and every word earns its place. It is effectively sized for a simple delete operation.

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

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

The description covers the core requirement (deleting from a draft version) but omits the special behavior around the 'force' parameter—specifically, that deleting the last rule requires confirmation unless force is set to true. With no output schema and a special-case parameter, this missing context could lead to incorrect calls. The annotations cover the destructive nature, so the description is adequate but not complete.

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

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

The schema description coverage is 100%, with all four parameters documented. The tool description provides no additional parameter semantics beyond what the schema already states. Per the rubric, a baseline of 3 is appropriate when the schema covers all parameters and the description adds no extra meaning.

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

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

The description uses a specific verb ('delete') and resource ('rule') and specifies the scope ('from a DRAFT version'), which clearly distinguishes it from other rule operations like create, update, toggle, and reorder. The draft-version constraint is a critical differentiator and is front and center.

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

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

The description provides clear context by restricting the operation to DRAFT versions, implicitly telling the agent when to use this tool. However, it does not explicitly mention alternatives (e.g., using lexq_rules_toggle to disable a rule instead of deleting it) or state that it should not be used on published versions. It gives clear usage context but no explicit 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?

readOnlyHint=true already discloses the non-mutating nature. The description adds what will be returned (condition tree and action definitions), which is mildly useful context but adds little behavioural disclosure beyond annotations. It does not mention auth, rate limits, or error behavior, but with the annotation present, this is acceptable and not a contradiction.

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

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

A single, front-loaded sentence that directly states what the tool retrieves. There is zero redundant phrasing, and the focus on the distinctive return content earns its place.

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

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

For a simple read tool with three fully documented parameters and no output schema, the description supplies what the return payload contains ('condition tree and action definitions'), which is information an agent needs to handle the result. It does not mention expected failure modes or version-interaction nuances, but given the low complexity and annotations, this is reasonably complete.

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

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

All three parameters have 100% schema description coverage with descriptive names ('ruleId', 'groupId', 'versionId') and descriptions like 'Rule ID'. The description adds no additional parameter semantics, e.g., relationship between group/version/rule or format requirements, but the baseline of 3 is appropriate when the schema covers all parameters.

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

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

The description uses a specific verb ('Get'), a precise resource ('full rule detail'), and names the concrete content ('condition tree and action definitions') that distinguishes it from sibling tools like lexq_rules_list (which lists only summaries) and lexq_rules_update (which mutates). An agent can infer this is the fetch-a-single-rule's-complete-definition operation without opening schemas.

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

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

The description implies the intended use case via 'full rule detail', which suggests it is for retrieving complete rule structure rather than a summarised list entry. However, it does not explicitly state when to prefer this over lexq_rules_list or lexq_profile_rule, nor does it give any exclusions or prerequisites beyond what the schema already states.

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

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

Annotations declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds useful behavioral context: it returns a summary with conditionSummary and actionSummary, and orders by priority ASC. It does not disclose pagination, limits, or whether the summary includes rule IDs/names, but for a read-only list tool with annotations covering safety, this is adequate.

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 a single, front-loaded sentence that states the action, resource, ordering, and return summary in under 20 words. Every word earns its place; no filler or repetition of schema details.

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

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

For a simple read-only list tool with two fully documented parameters and no output schema, the description is nearly complete. It tells the agent what it returns (summary with conditionSummary and actionSummary) and the ordering. The only minor gap is not mentioning whether the summary includes rule identifiers or how many rules are returned, but that is not essential for invoking the 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%: both groupId and versionId have descriptions ('Policy group ID', 'Version ID'). The description adds that the tool lists rules in a version, which clarifies the role of versionId, but it doesn't add meaning beyond the schema for the parameters themselves. 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?

The description states a specific verb ('List') and resource ('all rules in a version'), and adds ordering ('priority ASC') and return summary fields. It is clear and distinct from siblings like lexq_rules_get (which likely fetches a single rule) and lexq_rules_create/update/delete. However, it doesn't explicitly name a sibling alternative, so it doesn't fully differentiate itself from other list tools.

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

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

The description implies usage: call this when you need all rules in a version, with required groupId and versionId. It does not state when to prefer this over lexq_rules_get, lexq_profile_rule, or lexq_rules_reorder, nor does it mention any exclusions or prerequisites. The context is clear but not explicit about alternatives.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the agent knows this is a mutating operation. The description adds valuable behavioral context: priorities are assigned 1...N, 1-based and continuous, and array index 0 maps to priority 1 (highest precedence). This clarifies the exact effect of the reorder operation beyond what the annotations provide.

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 with no wasted words. The core action is front-loaded, and the priority assignment semantics are stated compactly. Every sentence earns its place.

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

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

For a mutation tool with no output schema, the description covers the essential behavior: what the tool does, how priorities are assigned, and the mapping from array index to priority. The annotations cover the destructive nature. The only minor gap is that it doesn't state whether the reorder is atomic or what happens to rules not listed in ruleIds, but the continuous 1...N assignment implies all rules are reordered. This is adequate for an agent to invoke the 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 schema already documents all three parameters (groupId, ruleIds, versionId). The description adds meaning to ruleIds by explaining the ordering semantics (index 0 = priority 1), which is useful. However, it doesn't add detail about groupId or versionId beyond their schema descriptions. Baseline 3 is appropriate since the schema carries the parameter documentation burden.

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 action ('Reorder rules') and the mechanism ('specifying rule IDs in desired order'), which distinguishes it from rule creation, deletion, toggling, and updating. It doesn't explicitly name a sibling alternative, but the verb 'reorder' plus the priority semantics make the purpose 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?

The description implies when to use this tool: when the user wants to change rule priority order. It does not explicitly state when not to use it or name alternatives like lexq_rules_update for other rule changes. The context is clear enough for an agent to infer the use case, but explicit exclusions are missing.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows this mutates state. The description adds the nuance that it doesn't delete the rule, which is useful. However, it doesn't disclose whether the change is reversible, whether it affects deployed versions, or any side effects. With annotations covering the mutation profile, a 3 is appropriate.

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

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

A single sentence with zero waste. The core action (enable/disable) and the key non-destructive distinction are both front-loaded. Every word earns its place.

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

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

For a simple toggle operation with full schema coverage and annotations declaring destructive intent, the description is mostly sufficient. However, it doesn't explain why versionId is required or whether toggling affects a specific version vs. the live rule, which could matter for correct invocation. The output schema is absent, but for a toggle that's 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%, so all four parameters (ruleId, groupId, isEnabled, versionId) are documented in the schema. The description adds no parameter-level detail beyond what the schema provides. Baseline 3 is correct 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 'Enable or disable a rule without deleting it' clearly states the verb (enable/disable), the resource (rule), and the key distinction from deletion. It doesn't explicitly name a sibling alternative, but the contrast with deletion helps differentiate it from lexq_rules_delete and lexq_rules_update.

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

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

The description implies when to use this tool: when you want to change a rule's active state without removing it. However, it doesn't explicitly state when not to use it or name alternatives like lexq_rules_update for other modifications. The context is clear but exclusions are not stated.

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

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

Goes well beyond the destructiveHint=true annotation: it discloses partial-update semantics, hard structural limits on a new condition tree (25 SINGLE nodes, 10 nesting levels), the non-obvious side effect that saving re-validates every action including unchanged ones, and the specific failure code ACT-032 for unregistered targetVar. This is exactly the hidden behavior an agent needs before a destructive mutation.

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