LexQ

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is carried structurally. The description contributes the prerequisite that the test must be running, but it never explains that the change diverts live traffic immediately, whether the adjustment is reversible, or what a failed adjustment leaves behind — meaningful gaps for a destructive operation.

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 ten-word sentence, front-loaded with the action and the constraint. There is no filler, hedging, or 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?

The tool is simple (two required parameters, flat schema) and annotations cover the safety profile, so the description is close to sufficient. However, there is no output schema, so the agent has no idea what a successful adjustment returns, and a destructive mutation of live traffic deserves at least a note on effect timing and reversibility.

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%: groupId is documented as a policy group ID and trafficRate as a 1-99 challenger traffic percentage, including bounds. The description adds only the framing that the rate belongs to a running test and does not clarify whether trafficRate is absolute or a delta from the current rate, which is the ambiguity the schema does not resolve.

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 ("Adjust") with a specific attribute ("traffic rate") of a specific resource ("a running A/B test"), which separates it from siblings like lexq_ab_test_start and lexq_ab_test_stop. The word "running" adds a state qualifier that further narrows intent, though it never names the sibling tools it contrasts with.

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?

"Running A/B test" implicitly tells the agent this applies only to an already-started test, so start/stop are the implied alternatives. There is no explicit when-not guidance, no statement about what happens if the test is stopped or absent, and no routing language naming the sibling 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?

Goes well beyond the destructiveHint/readOnlyHint annotations: it discloses the P-016 rejection for cross-group versions, the silent 0% outcome when context.trafficKey is missing, the cancellation of a pending scheduled deployment, and that restarting replaces an existing test's challenger and rate. That is exactly the side-effect information an agent needs before invoking 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.

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

Five short sentences, front-loaded with the action and required inputs, then escalating to preconditions, runtime behavior, and restart semantics. No filler and every sentence carries a distinct fact.

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 should cover outcomes; it explains error behavior (P-016) and the 0% degradation case, and covers scheduling side effects. It does not say what the start call returns (e.g., test ID or status), which is a minor remaining 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 baseline is 3, but the description adds real meaning: trafficRate is a split computed per request from context.trafficKey (a field not in the schema at all), and testVersionId must be a published version from the same group. These constraints explain parameter impact rather than restating types.

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 implicitly distinguishes itself from the adjust/stop siblings by describing a start operation with a challenger and traffic rate. 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 strong preconditions (challenger must be a published version of the same group, trafficKey required on execution requests) and notes the replace-on-running semantics. However, it never names the alternatives (lexq_ab_test_adjust, lexq_ab_test_stop) or says when to prefer adjust versus restart, leaving sibling routing to inference.

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

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

The annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is largely covered. The description nevertheless adds real value beyond them by disclosing the concrete post-condition: all traffic is restored to the control (current) version. It stops short of saying whether the test can be resumed, whether variant results are retained, or how in-flight sessions are handled.

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 action stated first and its effect second. Nothing could be removed without losing 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 one-parameter mutation with no output schema, the definition covers what is stopped and what state results, which is what an agent needs before calling it. Minor gaps remain around resumability and result retention, but nothing essential for correct invocation is absent.

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 required groupId parameter ("Policy group ID"), so the schema carries the parameter documentation. The description adds no further meaning about groupId, such as how to obtain one or whether it refers to the policy group owning the test. Baseline 3 applies 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?

"Stop a running A/B test" gives a specific verb plus resource, and the second sentence states the resulting state (traffic back to control). It is clearly distinguishable from lexq_ab_test_start and lexq_ab_test_adjust by verb alone, though it never names those siblings 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?

The phrase "a running A/B test" implies a precondition (the test must be active), which is the only usage signal present. There is no explicit when-not guidance, no mention of what to do if the test is already stopped or not found, and no reference to lexq_ab_test_adjust as the alternative for reweighting instead of halting.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the useful framing that generation is a preparatory step keyed to a version's required facts, but says nothing about whether the template is returned inline, as a downloadable file, or how large/complex versions affect the result.

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

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

Two short sentences with the action first and the motivating use case second; no filler, no repetition of the title or schema fields.

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, three-parameter generation tool, the essentials are present, but with no output schema the description should say what the caller receives (raw template text, file artifact, URL) and whether the format parameter changes the returned content or just its serialization. The title says 'Download' while the description says 'Generate', leaving the delivery mechanism ambiguous.

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 all three parameters are documented, and the description still adds meaning: the template's shape is derived from 'the required facts of a version', which explains why both groupId and versionId are mandatory, and 'CSV or JSON' ties to the format enum. Minor value beyond the schema, but genuinely clarifying.

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 ('Generate') and resource ('sample CSV or JSON template') scoped to a version, and implicitly separates itself from lexq_dataset_upload by framing the output as a format reference rather than an ingest call. An agent can distinguish it from the dataset-upload sibling without opening either schema.

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

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

'Use this to understand the expected data format before uploading a dataset' gives a clear when-to-use condition and points at the follow-up action. It stops short of naming the sibling tool explicitly or stating when-not to use it (e.g., when a dataset already uploaded validates fine).

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 that content is written to S3, that the returned path appears in a "path" field, and that the hosted server at mcp.lexq.io imposes a request-size limit. Those are exactly the side-effect and constraint details an agent needs for a non-readOnly upload.

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 single-sentence purpose, then clearly delineated usage/limit/alternative guidance and examples. The JSON example is long for the value it adds, but nothing is filler.

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

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

With no output schema, the description compensates by naming the returned "path" field and showing how to feed it downstream. Size constraints, side effects, and the alternative for large files are all covered, so an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning by showing worked CSV and JSON samples that demonstrate the expected content shape and the field-per-row structure. The filename parameter's role in choosing .csv vs .json is only implied rather than stated.

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 ("Upload inline CSV or JSON content as a simulation dataset") and immediately distinguishes itself from the file-based variant by qualifying "inline" and naming lexq_dataset_upload_file. An agent can tell this apart from lexq_dataset_template or lexq_simulation_start without opening any schema.

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

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

Explicitly gives the use condition (small datasets, content travels inside the tool call) and the exclusion with named alternatives (larger files go to lexq_dataset_upload_file on the local server, or CLI/console). It even closes the loop by showing the exact dataset object needed to consume the returned path in lexq_simulation_start.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is clear. The description adds useful filtering context (ACTIVE/published, grouped by groupId) but does not disclose return format, ordering, empty-result behavior, or pagination.

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 with zero waste. The core behavior is front-loaded and the workflow hint follows naturally.

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, one-parameter listing tool with rich annotations and no output schema, the description is nearly complete. A minor gap is that it does not describe return shape or whether results are paginated, but the tool's purpose and usage are clear.

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 only parameter is fully documented in the schema. The description's phrase 'for a group' reinforces that groupId scopes the result, but it adds no syntax, format, or edge-case 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?

States a specific verb and resource: lists ACTIVE (published) versions that can be deployed for a group. The 'deployable' scope distinguishes it reasonably well from generic version-listing siblings, but it does not explicitly name or contrast with lexq_versions_list or lexq_deploy_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?

Provides clear when-to-use guidance: find available versions before calling deploy live. This gives the agent a workflow anchor and names the next tool, but it does not state when not to use this tool or mention alternatives such as deploy_detail or versions_list.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description does add useful content signals that the response includes a snapshot hash and an integrity check, but it says nothing about error behavior for unknown IDs or whether the integrity check is computed on demand.

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 front-loaded sentence with the resource and scope stated first and the notable return fields appended. No filler, though 'including' leaves the field list open-ended and slightly hedges what is actually returned.

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 read tool with no output schema, the description gives the essential return highlights (snapshot hash, integrity check) and the lookup scope. Given the annotations cover safety and the schema covers the parameter, this is adequate; a note on failure for missing deployments 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?

There is a single deploymentId parameter with 100% schema description coverage, including uuid format and a validation pattern. The description adds no meaning beyond the schema, which is the expected baseline for this coverage level.

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

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

States a specific verb ('Get detailed info') and resource ('a specific deployment'), making clear this is a single-item lookup rather than a list. It does not explicitly distinguish itself from close siblings such as lexq_deploy_overview, lexq_deploy_history, or lexq_deploy_live, so the differentiation is only implied by '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?

No guidance on when to use this versus lexq_deploy_overview or lexq_deploy_history, and no prerequisites or exclusions. The agent must infer from the name and sibling list that this requires a known deploymentId.

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, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds that both inputs are snapshots of rule versions and that the result is a categorized diff, which is useful, but it says nothing about behavior with invalid/nonexistent version IDs, size limits, or ordering of the returned diff.

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

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

Three short sentences, front-loaded with the action and output shape before the usage note. No filler, though the third sentence is generic advisory content that could have carried more routing value.

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

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

With no output schema, the description carries the burden of describing the return, and it does name the diff categories. For a two-required-parameter read-only comparison this is largely sufficient; the missing piece is any note on diff structure or error behavior for bad version IDs.

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 already document their roles ('typically the current live', 'the one you want to deploy'). The description only reinforces the two-version comparison framing and adds no directionality detail (base vs target) beyond what the schema states, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Compare rule snapshots between two versions') and enumerates what the comparison produces (added, removed, modified rules). However, it never distinguishes itself from near siblings such as lexq_dry_run_compare or lexq_deploy_detail, so an agent must infer which comparison tool applies.

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

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

'Useful for reviewing changes before deploying a new version' gives a usage context, but it is phrased as a soft recommendation rather than an explicit when-to-use rule. There are no conditions for when not to use it and no named alternative among the many deploy/dry-run 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 already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds essentially nothing beyond that: it does not mention pagination defaults (page 0, size 20, max 100), result ordering, time windowing, or what a deployment record contains. For a list endpoint with no output schema, that leaves real behavioral gaps.

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 single sentence is front-loaded and free of filler, which is good, but it is under-specified rather than concise. The space saved is spent by the agent on guessing scope, ordering, and pagination behavior.

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 six optional parameters, no output schema, and no annotations beyond the safety hints, the description should at least note default pagination and result ordering. Instead it stops at the resource name, leaving the agent to infer how results are paged and sorted from the input schema alone.

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 six parameters (page, size, types, startDate, endDate, groupId) are already fully documented in the schema, including enum-like values for types and timezone semantics for the dates. The description adds no parameter meaning; 'across all groups' arguably sits in mild tension with the existence of a groupId filter parameter. Baseline 3 applies 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 states a specific verb and resource ('List deployment history'), so the agent knows this is a read operation returning past deployments rather than current state. However, it gives no differentiation against the many nearby siblings such as lexq_deploy_detail, lexq_deploy_overview, or lexq_history_list, so the agent cannot tell from the text alone which of these to pick.

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 when-not-to-use guidance, and no naming of an alternative tool. The phrase 'across all groups' hints at a broad-scope listing (as opposed to per-group queries), but that implication is never stated as a 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description is not carrying the safety burden alone; it still adds real value by stating deployment takes effect immediately and by disclosing the two rejection codes (P-037, P-058) and the fact that undefined facts do not block deployment. What it omits is whether the currently live version is replaced or retained, and any permission requirements — meaningful gaps for a destructive operation.

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 its immediacy, followed by failure conditions and the sibling routing. No repetition of the tool name or title and no hedging filler; each sentence supplies a distinct decision-relevant fact.

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

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

For a three-parameter destructive mutation with no output schema, the definition covers preconditions, immediacy, error codes, and alternatives, which is most of what an agent needs. The remaining shortfall is what the caller sees on success or failure and what happens to the previously live version, which the absent output schema leaves undocumented.

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 all three parameters are documented in-schema, so the baseline is 3; the description earns above baseline by constraining versionId to a published/ACTIVE version and implying memo is an audit record of the deployment. It says nothing about groupId semantics or how the two IDs must relate, but the schema already covers their types and formats.

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 (deploy) plus the exact resource state (an ACTIVE/published version) and the target (live traffic). The parenthetical clarifies what 'ACTIVE' means, and the contrasting sibling lexq_deploy_schedule is named, so an agent can distinguish this from the schedule/deployable/publish siblings without opening a schema.

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

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

Gives explicit when-not conditions: versions whose effective start date has not arrived must use lexq_deploy_schedule, and versions whose effective end has passed are rejected. It also routes the agent to lexq_facts_unregistered for reviewing undefined facts, which is a genuine alternative-selection cue rather than a generic disclaimer.

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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered and the description needn't repeat it. What it adds is return-shape semantics – that previousVersionName is the version a rollback restores and that canRollback accompanies it – plus a pointer to lexq_groups_get for field definitions. It stops short of stating scope limits (all environments? all versions? truncation/pagination?), which matters because there is no output schema.

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

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

Two sentences, front-loaded with the core action and scope, then a compact field glossary with a cross-reference. No filler, no restatement of the title, and the rollback detail is placed where it is most useful.

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

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

With no parameters and no output schema, the description must carry the return-value burden, and it does name the salient fields and their meaning, including the rollback pair. It is slightly incomplete about the boundaries of the overview – whether it spans environments, how many versions are reflected, and whether results are truncated.

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

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

The tool takes zero parameters, so the schema sets the baseline at 4 and there is nothing for the description to disambiguate. It correctly spends no words on arguments and instead puts its budget into return-value 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 opens with a specific verb+resource ('Show current deployment status of all groups') and enumerates the payload fields (live version, last deployment type, deployer). It is clearly an aggregate, multi-group read, but it never names the sibling it displaces (e.g. lexq_deploy_live or lexq_deploy_detail), so the distinction must be inferred from the word 'all'.

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

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

Usage is only implied: 'all groups' suggests a fleet-wide overview rather than a per-group detail call, which happens to contrast with lexq_deploy_detail and lexq_deploy_live. There is no explicit statement of when to pick this over those siblings, and no prerequisites or exclusions are given.

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

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

Goes well beyond the destructiveHint=true annotation by explaining what the destruction means concretely: the version is locked from further edits. It also discloses three specific failure conditions with error codes (ACT-032 for unregistered targetVar, 128 KB compiled-rule ceiling, P-058 for an expired effective end) and clarifies that undefined read-only facts do not block publishing.

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 state transition, then prerequisites, then failure modes with remediation. Every sentence carries a distinct operational fact and there is no filler or restatement of the title.

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

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

For a destructive, no-output-schema mutation tool this covers what changes, what is blocked, and how to unblock it. The one gap is the return value: nothing tells the agent whether a success response contains the new version record, a status, or nothing beyond confirmation.

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 groupId, versionId, and memo are already documented in the schema. The description references 'the version' and 'the version's compiled rules' but adds no new per-parameter meaning such as memo conventions or cross-group constraints. 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 plus the exact state transition it performs: 'Publish a DRAFT version (DRAFT → ACTIVE).' That transition, plus the note about locking, separates it from the lexq_deploy_* siblings that operate on already-active versions. It stops short of naming which sibling to reach for instead when the goal is going live.

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 preconditions are stated (at least one rule, and lexq_facts_unregistered as a voluntary pre-check) and a remediation path is named for a specific blocker (lexq_versions_update to move the end date). It gives no explicit exclusions, e.g., when to use lexq_deploy_deployable or lexq_deploy_schedule rather than publishing.

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

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

The annotations only say destructiveHint=true; the description adds substantial context beyond that: the optimistic-concurrency contract via expected ids, the 409 rejection semantics with 'nothing changes', and the distinct P-058/P-062/P-063 failure conditions. It also tells the agent to re-read state and confirm with the user before retrying, which is exactly the behavioral guidance a destructive tool needs.

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

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

Purpose and precondition are front-loaded, then error handling, then retry advice — a logical order. It is dense with error codes and policy references (P-058, P-062, P-063), which is justified for a destructive operation but makes it heavier than strictly necessary for a four-parameter 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 destructive, non-read-only mutation with no output schema, the description covers what is required: preconditions to verify, ids to supply, failure modes, and post-failure protocol. Nothing an agent needs in order to call this safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning by explaining where expectedCurrentVersionId and expectedCurrentDeploymentId come from (the currentVersionId/currentDeploymentId of a prior group read) and what happens when they no longer match. The memo parameter's purpose is left entirely to the schema.

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

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

The first sentence names a specific verb (roll back) and a specific target state (the version live before the current one), which separates it from siblings like lexq_deploy_publish and lexq_deploy_undeploy. An agent knows exactly what state the group ends in after a successful call.

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

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

It gives an explicit prerequisite sequence ('Call lexq_groups_get first') and names the blocking condition (canRollback false, previous version must be ACTIVE with unexpired effective end). It stops short of contrasting directly with lexq_deploy_undeploy or lexq_deploy_publish, so the agent must infer when to prefer rollback over those 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 only declare destructiveHint=true and readOnlyHint=false; the description goes well beyond them by disclosing the sealed snapshot hash re-verified at execution with fail-closed semantics, the one-schedule-per-group invariant, and the exact set of operations that silently cancel the schedule. That is exactly the kind of consequence-of-use context a destructive scheduling tool needs.

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

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

Four sentences, front-loaded with the action and its key constraint, and each sentence contributes a distinct fact (time source, cardinality, cancellation, integrity check). It is dense but not padded; a slightly tighter grouping of the cancellation triggers would be ideal.

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 could say what the call returns (e.g. the created schedule record or its ID), and it does not. Everything else an agent needs to decide and invoke correctly — preconditions, cardinality, cancellation behavior, integrity guarantees — is present.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: there is no time parameter because the fire time comes from the version's effectiveFrom, which must be set on the DRAFT before publishing. Only the required 'memo' parameter gets no elaboration, which is minor.

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

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

Names a specific verb and resource ('Schedule an ACTIVE version ... to auto-deploy at that time') and immediately qualifies the object ('ACTIVE', 'future effective start date'). It is clearly distinguishable from siblings such as lexq_deploy_deployable, lexq_deploy_publish, and lexq_deploy_unschedule without opening any schema.

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

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

States the precondition (version must be ACTIVE with a future effectiveFrom set on the DRAFT before publishing) and the when-not conditions (one pending schedule per group; manual deploy/rollback/undeploy, A/B test start, or group archive cancels it). It never names the cancellation sibling lexq_deploy_unschedule explicitly, so routing to the removal tool is left partly 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?

Beyond the read-only and non-destructive annotations, the description discloses that the listing spans every group, includes PENDING, EXECUTED, CANCELED, and FAILED schedules, and is ordered newest first. These details clarify that the tool is not limited to upcoming schedules, while pagination behavior is already covered by 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?

A single compact sentence front-loads the action and resource, then efficiently communicates scope, supported statuses, and sort order. There is no redundant or unnecessary 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 read-only list with two optional pagination parameters, the scope, status coverage, and ordering provide enough context to invoke the tool correctly. With no output schema, a brief note about the returned schedule or page representation, or clearer differentiation from sibling deployment views, would make the definition more complete.

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

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

Schema description coverage is 100%, with page and size documented along with their defaults and bounds, so the baseline score applies. The description does not add further parameter interpretation or pagination guidance.

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

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

The description clearly states the verb and resource—listing scheduled deployments—and adds useful scope, status, and ordering details. It does not explicitly differentiate this tool from siblings such as lexq_deploy_history or lexq_deploy_detail.

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 across-all-groups, all-status scope implies that this is the broad schedule-inventory tool. However, there is no explicit when-to-use guidance or direction to alternatives for deployment history or details of an individual deployment.

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 destructiveHint=true and readOnlyHint=false already given, the description earns credit by narrowing what is actually destroyed: the version stays ACTIVE and only loses traffic. That materially softens the destructive signal. It stops short of saying whether the state is reversible or how to restore traffic.

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 redundant wording, and the primary effect is stated first with the important caveat second. Nothing could be cut without losing 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 two-parameter mutation with no output schema and annotations covering the safety profile, the description supplies enough to act correctly and to predict the post-state. The only gap is the pointer back to which sibling re-deploys the version.

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 only two parameters, both already documented (memo as undeploy reason, groupId as policy group ID). The description adds no further meaning to either parameter, so baseline 3 applies.

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

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

The description uses a specific verb+resource pair ("Remove the live version from traffic") that makes the operation concrete and separable from siblings such as lexq_deploy_publish or lexq_deploy_rollback. It doesn't explicitly name an alternative sibling, but the action is unambiguous.

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

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

Usage is only implied by the effect: an agent can infer this is the way to take a version out of serving without deleting it. The description never says when to choose undeploy versus rollback, publish, or unschedule, which matters given a large sibling surface.

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 destructiveHint=true, and the description qualifies that blast radius by stating 'The version itself is not affected' — a genuinely useful clarification the annotations do not provide. The documented P-039 failure mode is also beyond structured data. It does not cover permissions or idempotency, keeping it short of a 5.

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

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

Two tightly written sentences, front-loaded with the action, followed by the non-impact statement and the error condition. No filler or restated title verbiage.

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 one-parameter mutation with no output schema, the description covers the action, the scope of destruction, and the failure case. A brief note on what a successful response confirms (e.g., that the schedule is removed) would make it complete.

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

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

Schema description coverage is 100% with a single required groupId already documented as 'Policy group ID'. The phrase 'for a group' in the description echoes rather than extends the schema, so the baseline 3 applies.

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

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

States a specific verb and resource: 'Cancel the pending scheduled deployment for a group.' This clearly separates it from lexq_deploy_schedule (create) and lexq_deploy_schedules (list), though neither 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?

Usage is implied rather than stated — the agent can infer this is the undo for lexq_deploy_schedule. The P-039 precondition ('no pending schedule exists') adds a useful guard, but there is no explicit routing such as 'check lexq_deploy_schedules first' or a named alternative.

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 and openWorldHint=false; the description goes well beyond them by disclosing the write effects (facts created, policy group created as DRAFT), the non-destructive merge semantics (an existing key with the same definition is kept as-is, never overwritten), and the atomic failure mode where P-061 means nothing is created.

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 short sentences, each front-loaded with a distinct fact: action, effects, merge semantics, prerequisite, and failure condition. There is no filler or repetition, and the most decision-relevant constraint (preview first) sits before the failure 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 two-parameter mutation tool with no output schema, the description covers effects, prerequisites, and failure modes thoroughly. The one remaining gap is that it never indicates what the call returns (e.g. created group or fact identifiers), which matters for follow-up calls since no output schema exists to fill that in.

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 `template` and `customName` are already documented in the schema, including the default-name fallback behavior. The description adds no format, example, or constraint detail about these parameters beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb and resource ("Apply a domain template to the current tenant") and immediately enumerates the side effects: fact definitions plus a new policy group with sample rules as a DRAFT version. It also distinguishes itself from the sibling lexq_domain_templates_preview and lexq_domain_templates_list by naming the preview tool as a prerequisite step.

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 ordering guidance ("Run lexq_domain_templates_preview first"), a hard precondition (factConflicts must be empty or apply fails with P-061), and an exclusion (a template with isAvailable false cannot be applied). The agent knows both when to call it and when the call will be rejected.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds value beyond that by disclosing the shape of each returned entry, including the isAvailable applicability flag, which is behaviorally meaningful for deciding whether to proceed to apply.

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

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

Three sentences, front-loaded with the action, followed by the definition needed to interpret results and the workflow cue. The ECOMMERCE/FINTECH examples earn their place by making an abstract concept concrete, and nothing is repeated from the schema or annotations.

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

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

With no parameters, no output schema, and a read-only annotation profile, the remaining burden is explaining what a domain template is and what a listing entry contains, and the description does both. An agent has everything needed to call it and to interpret the response before choosing preview or apply.

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

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

The tool takes zero parameters and the schema is an empty object, so per the baseline this sits at 4. The description's account of returned fields is a bonus rather than parameter explanation, and there are no parameters that could be underspecified.

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 then defines the resource concretely as a starter pack of fact definitions and sample rules with named examples (ECOMMERCE checkout pricing, FINTECH transfer approval). It also enumerates what each entry reports (key, isAvailable, fact count, sample rule count), so it is unmistakable against siblings like lexq_domain_templates_apply or 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 positions the tool in the workflow: "Call this before preview or apply to see which templates exist," naming both downstream siblings and the ordering that selects them. It does not state any when-not condition or what to do if isAvailable is false, which keeps it short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so 'read-only dry run; nothing is created' is largely reinforcement. However the description adds behavior the annotations cannot express: the P-061 failure mode on apply, the factConflicts gating condition (type / allowed-value / range mismatches), and that plan is null for a non-applicable template. That failure and precondition disclosure is substantive.

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

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

Front-loaded with the core purpose, then the return contents, then the conflict precondition and error behavior in a logical order. Every sentence carries information, though the factConflicts sentence is dense and slightly run-on with its stacked 'or with different ... or a different' clauses.

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

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

There is no output schema, so the description carries the return-value burden — and it does, naming fact definitions with value domains, sample rules with descriptions, the apply plan, factConflicts, and the null-plan case. Combined with the P-061 gating rule, an agent has everything needed to call this correctly and interpret the result.

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

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

Only one parameter and schema coverage is 100%, with the schema itself documenting that it is a domain template key and pointing at lexq_domain_templates_list for valid values. The description adds no further semantics about the template parameter, so baseline 3 applies. The allowed-values/range detail it does provide concerns output shape, not input 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?

States a specific verb and resource ('Preview exactly what a domain template will provision') and defines the scope as a pre-apply dry run, which cleanly separates it from the mutating sibling lexq_domain_templates_apply. The second sentence enumerates what the preview contains, so an agent knows what it gets back without opening anything else.

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 clearly framed as a step taken 'before applying it' and the description states the exact precondition for the mutating path ('While it is not empty, apply fails with P-061 ... delete those facts or change them to match the template, then apply'). It does not explicitly name lexq_domain_templates_apply or lexq_domain_templates_list as the paired tools, relying on the schema description for key discovery, so it stops short of full 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered by structured data. The description genuinely adds operational behavior the annotations cannot express: no billing or plan-usage consumption, a shared 60 evaluations/minute per-organization limit with compares counting as two, and a 429 (C-007) failure mode until the next minute. Those are solid additions, but the returns block largely duplicates the kind of information an output schema would carry, and it omits the state after failures.

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

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

The purpose is front-loaded in the first sentence, followed by the billing/rate-limit caveats and then a clearly labeled returns breakdown, which is a sensible ordering. The returns list is dense but earns its place given there is no output schema; the trailing example is the weakest part because it conflicts with the schema rather than clarifying it.

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

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

With no output schema, the description carries the burden of explaining the response, and it does so thoroughly, including non-obvious details like the paired {factName}__delta keys in generatedVariables and the SELECTED / NO_MATCH / BLOCKED decision states. Rate limits, billing exemptions, and the 429 error code round out the operational picture. What is missing is the path to a valid versionId and whether input facts must be registered first.

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 versionId, facts, and includeDebugInfo, which would normally justify a baseline 3. The description's only parameter-level contribution is the example input, and that example renders 'facts' as a nested JSON object while the schema types it as a string containing JSON — an inconsistency an agent could easily follow into a validation failure. Because the added material is misleading rather than merely redundant, it falls below the baseline.

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

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

The description states a specific verb and resource: execute a single dry run against a policy version and see how rules evaluate given input facts without side effects. 'Single dry run' implicitly contrasts with the sibling lexq_dry_run_compare, and the rate-limit sentence names compares and single-decision replays, so an agent can distinguish the family. It stops short of an explicit one-line distinction from those siblings.

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

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

The 'without side effects... not billed and not counted toward the plan's usage' framing implies when to reach for this tool rather than a live evaluation. However, it never states when to prefer lexq_dry_run_compare or lexq_replay_decision, nor any prerequisites such as whether facts must be pre-registered (the presence of lexq_facts_unregistered suggests a real prerequisite worth naming).

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

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

The annotations already state that this is a read-only, non-destructive, closed-world call, and the description adds genuinely new behavioral facts: it is not billed, does not count toward plan usage, shares a 60-evaluations-per-minute org limit, costs two evaluations per compare, and fails with 429 (C-007) past the limit. That is concrete context the annotations cannot convey. It stops short of explaining failure modes such as version-not-found behavior, which keeps it below 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?

The purpose comes first, followed by cost, rate limits, and a structured Returns block. Every section is useful, especially the Returns block, since no output schema exists. The rate-limit paragraph is dense but earns its place given the 429 behavior.

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, yet the description explains the return shape: full DryRunResponse for each version plus mutatedFacts and generatedVariables diffs keyed by field. Combined with billing and rate-limit disclosure, an agent has everything needed to call this correctly and interpret the response.

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

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

The schema documents all three parameters at 100% coverage, including 'Baseline version ID' and 'Candidate version ID', so the baseline is already set. The description adds only that both versions are fed the same facts string, which clarifies intent but does not add syntax or format detail beyond the schema. This is the baseline-three case described in the rubric.

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 and resource: 'Compare dry run results between two versions using the same input facts.' This clearly distinguishes a diff-style operation from the single-version sibling lexq_dry_run, but the distinction is implied rather than stated by naming the 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?

'Useful for validating changes' gives an implied context for use, and the rate-limit paragraph explains the operational ceiling. However, the description never says when to prefer this over lexq_dry_run or lexq_deploy_diff, and it gives no prerequisites such as whether both versions must share a ruleset.

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 and destructiveHint already covering safety, the description adds real value: it explains that required facts absent at runtime throw and that the engine never defaults to 0, cites P-015 and ACT-032, and explicitly marks the data as static and cacheable in-session. It stops short of describing the response shape, which matters since there is no output schema.

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

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

The purpose is front-loaded in the first sentence and each subsequent sentence contributes a distinct rule (conditional facts, no-default behavior, P-015, SET_FACT exemption, caching). It is dense with internal error codes and jargon, but no sentence is redundant.

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

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

For a zero-parameter, read-only metadata lookup with no output schema, the description supplies enough for correct use: what is returned conceptually, the meaning of factRequired, and the failure mode. The remaining gap is the literal structure of the returned data, which an agent must discover at call time.

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

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

The tool takes zero parameters, so the schema carries no semantic load and the baseline of 4 applies. The description correctly does not invent parameter guidance, instead spending its words on output semantics such as the factRequired flag and conditional refVar behavior.

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 ('Retrieve runtime fact requirements per Action type') and elaborates on the exact content returned: which input facts must be present per action, with MUTATE_FACT and SET_FACT as concrete examples. It does not name sibling tools such as lexq_facts_list or lexq_requirements to disambiguate, so it falls short of a 5.

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

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

Usage is implied rather than stated: an agent infers it should call this to learn which facts a payload must carry. The only explicit guidance is 'Static data, safe to cache in-session', with no mention of when to prefer a sibling lookup or any preconditions for calling.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds nothing behavioral beyond that: it does not say what happens when the key already exists (reject vs overwrite), whether the new definition is immediately active for rules or requires a publish step, or what is returned. For a mutation tool in a versioned rule engine, that missing lifecycle context is a real 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?

It is short and front-loaded, with the core action in the first sentence. However, the second and third sentences are pure duplication of the schema's regex pattern and type enum, so those sentences do not earn their place. Trimming them would free room for the lifecycle information that is actually missing.

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?

Seven parameters, a nested valueDomain object, and no output schema make this a moderately complex definition. The rich schema compensates for most of the description's silence, but the description never touches the PII flag, the value domain, or how the created fact interacts with rules and versions. Adequate as a label, thin as guidance for a schema of this depth.

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 every parameter thoroughly, including the valueDomain type-constraint matrix and the isRequired caveat that the engine ignores it. The description's key pattern and type enum merely restate what the schema already encodes, adding no new meaning. Baseline 3 applies because the schema carries the load.

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 concrete verb and resource: "Register a new input variable." That is clear enough to act on, though it uses "input variable" while the tool name says "Fact Definition," and it never names the sibling it is distinct from (lexq_facts_update for existing definitions, lexq_facts_list for reading them). Purpose is clear but not differentiated from siblings.

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

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

There is no when-to-use guidance at all — nothing says to use this only for definitions that do not yet exist, or to call lexq_facts_update for existing ones. No prerequisites are stated, such as whether a draft version must exist or which scope the new fact lands in. The agent must infer the create-vs-update boundary purely from the tool name.

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

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

Beyond the annotations' destructive operation signal, the description discloses referential-integrity blocking, the FD-006 failure code, the reported reference count, and the deleted-group exception. These are substantial failure and scope details that help an agent predict and handle the call's behavior.

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

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

The description is front-loaded with the operation and uses short sentences for the restrictions, error behavior, exception, and remedy. Every sentence earns its place, with no filler or repetition of structured parameter 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 destructive tool with one required parameter, it covers the resource, deletion blockers, precise failure behavior, an important exception, and the corrective action. Together with the complete parameter schema and destructive annotations, this is sufficient for correct 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?

The schema fully documents the sole factId parameter, including its purpose and UUID constraints. The description adds no further parameter meaning, so the high schema coverage supports the baseline score of 3.

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

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

The opening sentence states the exact operation and resource: deleting a fact definition. This clearly distinguishes the tool from fact creation, update, and listing siblings, as well as from the rule and group deletion 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?

It gives explicit when-not conditions: system facts and facts referenced by applicable rules cannot be deleted. "Remove the references first" supplies the prerequisite remediation, while the deleted-group exception clarifies which references matter.

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

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

Annotations already declare readOnly/non-destructive/closed-world, so the safety profile is covered. The description still adds real context the annotations don't: the return is file contents as text, the export is capped and refused above 100,000 characters, and CSV omits value domains while JSON omits IDs — exactly the kind of content-shape detail an agent needs.

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

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

Three tight sentences, purpose front-loaded, followed by the format-difference detail and the size limit. No filler, though the dense clause listing JSON fields is slightly hard to parse in one read.

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

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

With no output schema, the description correctly states the return is raw file text, and it discloses the size cap. What's missing is any guidance on recovering from the 100,000-character refusal, which matters for a tool whose only filter is keyword.

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

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

Schema coverage is 100%, so baseline would be 3, but the description goes well beyond the terse 'Export format' field by spelling out exactly what each enum value contains and excludes. The keyword parameter is not mentioned in the description, but the schema documents it adequately ('Filter by key or name').

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

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

Opens with a specific verb+resource: 'Export the fact catalog,' which an agent can distinguish from the sibling read tools like lexq_facts_list. It does not explicitly name which sibling it differs from (e.g., lexq_facts_list vs. the other *_export tools), so it stops short of full sibling differentiation.

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

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

It gives useful selection guidance between the two formats ('for reading in a spreadsheet' vs. 'only the fields a new definition takes'), which implies the JSON export feeds definition creation. However, it never states when to use this tool instead of lexq_facts_list or how to handle the 100,000-character refusal (e.g., narrow with keyword), leaving the when-not to inference.

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

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

The annotations already establish that the operation is read-only and non-destructive. The description adds the returned fields and the non-obvious caveat that isRequired is stored only on the definition and ignored by the engine, though it does not clarify that the catalog is accessed through paginated responses.

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

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

Two compact sentences front-load the operation and resource, enumerate the relevant definition fields, and then state a focused semantic caveat. There is no filler or unnecessary repetition of the input 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 simple three-parameter read, the schema and annotations cover basic invocation and safety, while the description supplies result content and an important domain caveat. It is nearly complete, but the unqualified "all" alongside paginated inputs could lead an agent to expect the entire catalog in one call, and sibling selection remains unaddressed.

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

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

Schema description coverage is 100%, with page, size, and keyword already documented, so the baseline of 3 applies. The description adds no further detail about pagination defaults, result limits, or keyword matching.

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

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

The opening "List all fact definitions" provides a clear verb and resource, while "input variable schema" clarifies what the definitions represent. It does not explicitly differentiate this tool from siblings such as lexq_facts_unregistered or lexq_facts_action_metadata.

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 wording implies use when inspecting the fact-definition catalog, but provides no explicit when-to-use or when-not-to-use guidance. It does not explain when keyword filtering is useful or when a sibling such as lexq_facts_unregistered is more 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?

Annotations already cover read-only and non-destructive status, so the description uses its space well by disclosing behavior the annotations cannot: the ACT-032 rejection path at save/publish, the fact that read-only references do not block deployment, and the downstream effect that registering before publish enables P-060 type checks and P-052 domain checks. This is exactly the kind of publish-gating rule an agent cannot infer from structured fields.

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

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

The lead sentence front-loads what the tool returns and its read-only nature, followed by the operational consequence and then the shape of each entry. It is dense with domain jargon (ACT-032, P-060, P-052) but every clause carries behavioral information; only minor tightening would improve it.

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 compensates by describing each entry (inferred type, suggested name, reference location in condition/action), which is exactly what an agent needs to interpret results. Combined with the publish-blocking semantics and the follow-up registration path, nothing essential for calling this correctly is missing.

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

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

Schema coverage is 100% and both required parameters (groupId, versionId) are already documented in the schema with UUID formats. The description only adds the scoping note that the result is version-wide across every rule, which is useful but not parameter-level enrichment beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('List facts referenced by a version's rules but not yet defined') and explicitly scopes it to the version, which separates it from the sibling lexq_facts_list of registered facts. An agent can tell what it returns and what it does not return 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 concrete when-to-use context: unregistered read keys do not block publish/deploy, while an unregistered action targetVar causes rejection at save/publish with ACT-032, and it points to lexq_facts_create as the follow-up action. It stops short of explicitly naming lexq_facts_list as the alternative for already-registered facts, so the routing is implied rather than spelled out.

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

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

Beyond the mutation-oriented annotations, it discloses patch semantics, key immutability, the reference-dependent FD-007 failure and reported count, the deleted-group exception, and system-fact FD-003 behavior. These details materially affect whether and how a call succeeds.

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?

Six compact sentences move from the core operation to general update semantics and then special cases. The text is dense but contains no filler, and the most important constraints are 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?

Together with the fully documented schema, the definition covers partial updates, nested value-domain behavior, reference constraints, error codes, and system-fact exceptions. Despite the absence of an output schema, no significant ambiguity remains about how 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?

Although schema description coverage is 100%, the description adds general send-only-fields patch behavior and a consolidated account of which system-fact fields are mutable, ignored, or type-restricted. Some of the type-change guidance repeats the schema, so the added value is strong but not entirely novel.

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

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

The opening “Update a fact definition” supplies a specific verb and resource, clearly distinguishing the operation from sibling fact creation, deletion, and listing tools. The remaining sentences stay focused on the behavior of modifying an existing definition.

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

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

It gives clear situational guidance for partial updates, type changes, and system facts, including when calls fail or fields are ignored. It does not explicitly route agents to an alternative such as lexq_facts_create when a new definition 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?

Beyond the non-destructive, non-open-world annotations, it discloses non-obvious behavior: priority is auto-assigned and appended last tenant-wide, groups sharing an activationGroup form a constrained cluster, and a hard limit of 20 non-ARCHIVED groups applies. What is missing is whether cluster-field mismatches fail the call or what the response 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 creation statement and required field are front-loaded, followed by ordering, cluster constraints, and the quota. It is dense but nearly every clause carries operational consequence; the cluster/quota material could be tightened into one sentence without losing content.

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

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

For a mutation tool with no output schema, the description covers prerequisites, ordering side effects, cluster invariants, and quota pressure, which is most of what an agent needs. The remaining gap is failure behavior and any returned identifier, which the description never mentions.

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 schema by explaining that executionLimit counts groups rather than rules and that a shared activationGroup imposes shared activationMode/activationStrategy/executionLimit. It does not clarify defaults for activationMode or when activationStrategy 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 ('Create a new policy group') and immediately names the required field, so it is unambiguous against siblings such as lexq_groups_update, lexq_groups_delete, and lexq_groups_list. An agent can route to it 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?

It explicitly redirects ordering work to lexq_groups_reorder and tells the agent to archive unused groups when hitting the 20-group cap, which is actionable guidance. It stops short of stating when to prefer this over lexq_groups_update or what the cluster consequences are for choosing activationGroup values.

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

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

The annotations already flag destructiveHint=true, but the description adds genuine context beyond them: irreversibility, immediate name reuse, disappearance from lexq_groups_list, 409 P-059 responses for subsequent mutating calls, and the audit-retention versus 30-day permanent-deletion distinction. None of this is recoverable from the annotations or 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 critical constraint and irreversibility warning are front-loaded, and each sentence carries distinct information. The enumeration of every mutating call type that returns 409 P-059 is somewhat dense, but it is not wasted text.

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

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

For a single-parameter destructive tool with no output schema, the description covers preconditions, side effects, error behavior, and post-deletion visibility and retention. Nothing material an agent needs before invoking it is missing.

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

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

Schema description coverage is 100% for the single groupId parameter, so the schema already carries the parameter meaning. The description adds no further detail about the ID (e.g., where to obtain it), so the baseline of 3 applies.

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

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

The description opens with a specific verb and resource, "Delete (archive) a policy group," and immediately clarifies the archive semantics, which distinguishes it from lexq_groups_update and lexq_groups_list. An agent can identify the operation without consulting 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?

It states an explicit precondition and exclusion (a deployed group cannot be deleted, P-020) and names the alternative tool to use instead (lexq_deploy_undeploy), including the side effect that undeploying ends a running A/B test. This is exactly the when-not-plus-alternative guidance an agent needs.

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

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

Annotations already establish this as a safe, closed-world read, so the bar is lower; the description goes further by naming three returned fields and explaining what each means for rollback. It still doesn't characterize the rest of the returned group object, but the key behavioral context is supplied.

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 core action and followed by the field-level context that justifies the call. 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 read with full annotation coverage, the definition is nearly sufficient; the only gap is that no output schema exists and the description names just three return fields rather than sketching the whole group payload. That is a minor shortfall for such a simple getter.

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 one parameter with 100% schema description coverage ("Policy group ID"), so the schema carries the semantics and baseline 3 applies. The description only restates "by ID" and adds no format, sourcing, or lookup guidance beyond the UUID pattern already declared.

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?

"Get a single policy group by ID" gives a specific verb (get), resource (policy group), and scope (single, by ID), which cleanly separates it from lexq_groups_list, lexq_groups_update, and lexq_groups_create. An agent can pick it out without opening the schema.

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

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

The description implies a usage path by tying currentVersionId/currentDeploymentId to lexq_deploy_rollback, hinting this is the lookup step before a rollback. It never states when to prefer it over lexq_groups_list or any exclusions, so the guidance is implied rather than explicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and a closed-world scope, so the safety profile is covered. The description adds genuinely useful behavior beyond that: results are tenant-wide, sorted by priority ascending, and soft-deleted groups are omitted. It omits pagination or result-size behavior, which keeps it below a 5.

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

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

Two short sentences with no filler; the scope and ordering constraint is front-loaded in the parenthetical and the exclusion rule follows. Every clause carries information an agent needs.

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

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

For a zero-parameter, read-only list with no output schema, the description covers scope, ordering and filtering, which is most of what an agent needs to call it. It does not describe the shape of a returned group or whether results are paginated, a minor gap given there is no output schema to fall back on.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline for a no-parameter tool applies; the description correctly spends no words on input semantics.

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

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

States a specific verb and resource ('List policy groups') plus scope ('tenant-wide') and ordering ('priority ASC'). It is clearly a list operation distinct from lexq_groups_get or lexq_groups_create, though it never names those siblings 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 name and the word 'List', and the parenthetical clarifies scope, but there is no explicit when-to-use versus lexq_groups_get or when-not guidance. An agent can infer the routing but must do so itself.

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 bar is lower. The description does add valuable context beyond them: priority is tenant-wide and flat (1...N continuous), which explains the blast radius of the mutation, and activationGroup is explicitly left untouched. It still does not say what happens to groups omitted from the array, whether the list must be exhaustive, or the response shape.

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 clauses, all load-bearing: the action, the ordering convention, and the scope exclusion. The most decision-relevant fact (index 0 = highest precedence) is front-loaded with zero 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 one-parameter destructive mutation with no output schema, the definition covers the core semantics: ordering convention, tenant-wide flat numbering, and what is not changed. Remaining gaps are exhaustiveness of the array and any permission/response details, which keep it just short of complete.

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

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

Schema coverage is 100% and the schema already states 'index 0 = priority 1'. The description reinforces this and adds the meaningful constraint that priority is tenant-wide and continuous 1...N, hinting the array must be complete, but it never states that requirement outright or covers validation failures for partial lists.

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 ('Reorder policy groups by priority') so the operation is unambiguous. It does not explicitly distinguish itself from nearby siblings such as lexq_rules_reorder (rules vs. groups) or explain why lexq_groups_update cannot achieve the same result, so sibling differentiation is only implied by the resource 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 is implied rather than stated: the agent can infer this is the tool for changing precedence, and the note that activationGroup is unaffected scopes the call. There is no explicit when-to-use/when-not guidance, no alternative named, and no statement of prerequisites such as permissions or whether every tenant group must be supplied.

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 genuinely new behavior: PATCH-style semantics (omitted fields unchanged) and a specific failure mode with status code 409 / P-059 for deleted groups. It does not say whether an update takes effect in production immediately or requires a republish, which matters for a destructive flag.

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

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

Three short sentences, front-loaded with the action, then the update semantics, then the error condition. No filler, no repetition of the title.

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

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

For an eight-parameter mutation tool with no output schema, the definition covers the core semantics (partial update, deleted-group rejection) and the schema richly documents every field. The remaining gap is what a successful call returns and whether changes are staged or live, which an agent would want before invoking 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?

Schema description coverage is 100%, so the schema already carries the meaning of all eight parameters, including the detailed DISABLED side effects, enum values, and executionLimit bounds. The description body itself adds nothing parameter-specific, 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?

"Update a policy group" states a specific verb and resource, and the partial-update sentence clarifies the mutation model. It does not distinguish this from its obvious siblings (lexq_groups_create, lexq_groups_delete, lexq_rules_update); that differentiation only appears incidentally in the status parameter description via the rollback/undeploy pointers.

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 it (partial edits; omit fields to leave them unchanged) and gives one hard precondition (deleted group returns 409 P-059). It never states when to prefer a different tool, e.g. lexq_deploy_rollback or lexq_deploy_undeploy for production changes, which are only mentioned inside the status enum description rather than as routing guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description's contribution is enumerating the returned sections, which is useful given there is no output schema, but it says nothing about payload size, whether traces can be truncated, or behavior when a traceId is unknown or expired.

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 sentence, front-loaded with the verb and scope, with zero filler. The enumerated field list is dense internal jargon but each item conveys real information about the response shape, so it earns its place.

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

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

For a one-parameter read tool with full annotation coverage, the main missing piece was the return payload, which the field list supplies. Still absent are any failure modes (invalid or expired traceId) and the relationship to lexq_history_list and lexq_provenance_get, which an agent choosing among ~70 siblings would benefit from.

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

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

Schema description coverage is 100% and there is a single required traceId parameter whose schema description already explains its origin. The description adds no further meaning about the ID format or scope, so the baseline 3 applies.

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

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

The description names a specific verb ('Get') and resource ('full execution detail') and enumerates the exact payload sections returned (inputFacts, mutatedFacts, generatedVariables, executionTraces, decisionTraces). This clearly separates it from lexq_history_list at a conceptual level, though it never names the sibling to make the distinction 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 when-to-use guidance, no prerequisites, and no mention of the alternative lexq_history_list or lexq_provenance_get. The only hint that this is a follow-up call is the schema note that traceId comes 'from execution history', which lives in the schema rather than the description.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description's added value is the enumeration of returned fields, which compensates for the absent output schema, but it says nothing about ordering, pagination limits, or result volume.

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

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

Two short sentences, front-loaded with the action and followed by the useful return-field summary. Nothing is padded or redundant.

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

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

With 8 optional parameters and no output schema, listing the returned fields is a meaningful completeness contribution. However, guidance on combining filters, default paging behaviour, or how to retrieve full details after finding a trace is missing for a tool of this breadth.

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 detailed semantics for startDate/endDate (tenant time zone, inclusive whole days) and the status enum, so the schema carries the parameter burden. The description adds no filtering or pagination meaning beyond it, making the baseline 3 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 ('List policy execution history') and enumerates the fields returned (trace ID, group, version, status, match result, latency). That is clear enough to separate it from a detail fetcher, but it never contrasts itself with siblings like lexq_history_get or lexq_history_stats.

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 or when-not-to-use guidance, and no mention of the closely related siblings (lexq_history_get for a single record, lexq_history_stats for aggregates). The agent must infer that this is the paginated, filterable list endpoint purely from the name.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful non-annotation behavior: the default rolling window, the 31-day cap, and the specific error code AN-039 for over-long ranges. It stops short of describing result shape or what happens when endDate precedes startDate.

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, and the most decision-relevant facts (what KPIs, default window, range cap) are front-loaded. Nothing needs re-reading.

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

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

With no output schema, the description correctly takes on the burden of naming the returned metrics, and it covers the temporal edge cases an agent is most likely to hit. It is nearly complete for a read-only stats tool; the only gap is clarifying the result type of the aggregate fields or ordering behavior, 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 description coverage is 100%, so all three parameters (startDate, endDate, groupId) are already documented, including the time-zone semantics the description restates. What the description genuinely adds is the defaulting behavior when dates are omitted and the cross-parameter 31-day span constraint, which is not expressible in the schema — modest but real added 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 opens with a specific verb and resource ("Get execution KPIs") and enumerates the exact metrics returned: total executions, success/failure counts, success rate, and average latency. It does not explicitly distinguish itself from aggregate-adjacent siblings like lexq_history_list or lexq_logs_list, which keeps it from 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 clear operating context: with no dates the default window is the last 30 days through today in the organization time zone, and startDate alone runs through today. It also states the hard limit (31 days per call) and the rejection behavior (AN-039), though it never points to an alternative sibling for longer ranges or raw per-execution data.

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

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

Annotations already establish readOnlyHint, non-destructive, and closed-world, so the description is not responsible for the safety profile. It adds genuinely useful behavior beyond them: the hard capability limit (no resolve/ignore) and the human escalation route with an exact console path. It omits what the returned detail contains or what happens on an invalid/unknown ID.

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 operation, followed by the capability limit and escalation target. The full URL is somewhat verbose but earns its place as an actionable pointer for an agent that must redirect the user.

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 read tool with a complete schema and rich annotations, the description covers purpose, limits, and escalation. The remaining gap is minor: it never indicates what the returned 'failure log detail' comprises, which would matter since 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?

With only one parameter at 100% schema description coverage (including a UUID format and pattern constraint), the schema fully documents logId. The description's 'by ID' adds essentially nothing beyond that baseline.

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

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

The description states a specific verb and resource ('Get failure log detail by ID'), which clearly separates it from the list-style sibling lexq_logs_list. It stops short of naming that sibling explicitly, so the differentiation relies on the agent inferring 'by ID' vs. listing.

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

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

It gives a clear usage boundary: this tool reads logs but cannot resolve or ignore them, and it names the escalation path (org admin via the LexQ console URL). It does not explicitly say when to prefer it over lexq_logs_list, but the read-only-by-ID framing makes that implicit.

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 destructiveHint=false, so safety is covered. The description adds useful behavior the annotations do not: the implicit 7-day lookback window evaluated in organization time zone, and the fact that resolving or ignoring is not possible here. It says nothing about pagination behavior or result volume, so it stays a middle score.

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 scoping statement comes first, followed by the default window and then the alternative location, so the most decision-relevant information is front-loaded. The console URL is somewhat bulky but earns its place by giving an actionable path for the operation this tool cannot perform.

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 paged list tool with full schema coverage, the description covers the key gaps: default time window, time zone semantics, and the read-only limitation. However, with no output schema present, it never characterizes the return shape (log fields, ordering, or what pagination metadata comes back), so an agent cannot anticipate results.

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 page, size, status, keyword, taskType, and the date fields are all already documented in the schema. The description contributes only the implicit date-window semantics for omitted dates and the nudge toward startDate, which the schema itself does not state; that is marginal added meaning against a fully 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?

The first sentence gives a specific verb and resource ('List system failure logs') plus the scope of what produces them (platform event webhooks, scheduled deployments), which immediately distinguishes it from the singular sibling lexq_logs_get.

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 default behavior when no dates are supplied and explicitly tells the agent to pass startDate to reach further back, which is real when-to-use guidance. It also rules out mutation by directing resolution to the console, but it never names a sibling tool or covers when to prefer a single-log lookup.

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 readOnly=true, destructive=false and a closed world, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond that: the ledger is metadata only and revealed values are never stored or returned, which tells an agent the response cannot leak secrets. Pagination and retention behavior are still unstated.

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

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

Two sentences, no filler, with the scope and the key distinction (the ledger itself versus the revealed values) front-loaded. Every clause earns its place.

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

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

For a read-only, zero-required-parameter list tool with fully documented filters and a rich privacy statement, an agent has enough to call it correctly without an output schema. Return-field detail is absent, but the description's "who revealed which fact of which trace, and when" implicitly sketches the record shape.

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 careful note that startDate/endDate are whole calendar days in the organization time zone rather than UTC. The description adds no filter semantics of its own, so the baseline 3 for schema-carried parameters 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?

"List the PII reveal audit ledger — who revealed which fact of which trace, and when" names a specific verb, a specific resource, and even enumerates the record shape (actor, fact, trace, timestamp). That detail makes it practically impossible to confuse with nearby list tools such as lexq_logs_list or lexq_history_list, even without an explicit sibling callout.

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 for monthly access-log inspection and SIEM collection" gives concrete usage contexts, which is exactly the 4-level bar of clear context without exclusions. It does not say when to pick this over lexq_logs_list or note that it is not a substitute for general history queries, so it stops short of 5.

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

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

Beyond the readOnly/non-destructive annotations, the description discloses genuinely non-obvious behavior: rule detail comes from a deterministic 1% sample while TOTAL is recorded for every call, percentiles are withheld unless n×(1−q) ≥ 3, and baselines return INSUFFICIENT_COHORT under 3 qualifying rules. That is strong disclosure; a small gap remains on pagination/response shape, which is partly covered by the output enumeration.

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 resource and its three output components, then gated details. Dense and jargon-heavy but nearly every clause (cache-state semantics, gate formulas, sampling) carries actionable information; the parenthetical arithmetic is verbose but purposeful.

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 takes on the burden of describing returns and does so: distribution shape, table contents, flags, null-percentile semantics and cohort failure state. For a read-only analytics tool with five parameters, an agent has enough to call it and interpret the result correctly.

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

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

Schema coverage is 100% and the schema already carries the defaults (now, 24h ago, live version, HIT), so the description's 'Defaults:' sentence largely repeats structured data. It does add the sampling distinction between TOTAL and rule-level data, which helps interpret cacheState and the window, but adds little per-parameter meaning beyond that.

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

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

The description opens with a precise verb+resource phrase: 'Per-rule latency profile of a policy group over a time window,' and enumerates the outputs (TOTAL split by cache state, per-rule CONDITION/ACTION percentile table, slow-rule flags). It is clearly distinct from a per-rule tool, but it never names lexq_profile_rule, leaving the sibling boundary to inference.

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

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

Usage is only implied through defaults ('last 24h, live version, cacheState HIT') and gate conditions (n≥100 judgment gate, INSUFFICIENT_COHORT). Nothing states when to choose this over lexq_profile_rule or how to widen the window if a percentile is withheld; the agent must reason that a null p99 means increasing the time range.

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 readOnly/non-destructive, and the description goes well beyond them with substantive behavior: missing windows are genuine gaps and are never interpolated, series points carry each window's own values rather than being aggregated, percentiles are withheld as null unless n×(1−q) ≥ 3 (with concrete thresholds p50 ≥ 6, p95 ≥ 60, p99 ≥ 300), and 'flagged' means p50 ≥ 10× the median of per-rule p50s within the group. It even states a deliberate non-feature — absolute thresholds are intentionally unsupported — which prevents a whole class of misuse.

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 identity of the tool and its output shape, then progressively narrower caveats. Each clause carries real information — no filler or restated name. It is very dense in the back half (percentile gating thresholds and the flagged rule packed into single clauses), which slightly hurts scanability, but nothing is wasted.

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

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

There is no output schema, so the description must explain the return payload — and it does, covering both merged distributions and the per-window series, null semantics, gap handling, and the flagged marker. With all parameters documented and safety covered by annotations, an agent has everything needed to call this correctly and interpret the result. Only minor omissions (range limits, series point limits) remain.

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 every parameter (from/to defaults, ruleId provenance, groupId, versionId defaulting to live) is already documented in the schema itself. The description contributes no additional parameter-level meaning — it does not mention time-range defaults, the live-version default, or any constraint on window length versus range. Baseline 3 applies when the schema carries the parameter 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 opening clause names the resource precisely — single-rule latency detail — and enumerates the two payload shapes returned: merged phase × cacheState distributions and a 60s-window time series. The word 'single-rule' implicitly separates it from the aggregate/overview sibling, and 'ruleId (from lexq_profile_overview)' reinforces that relationship. It lacks an explicit verb and never names the alternative tool to use when a whole group is wanted, which keeps it from 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?

Usage is only implied: by calling itself 'single-rule' it hints you should not use it for group-level or multi-rule analysis, and the parameter hint points to lexq_profile_overview as the way to discover ruleId. There is no explicit when-to-use / when-not-to-use statement, no guidance on choosing time ranges, and no mention of what tool to reach for instead for aggregate views.

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

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

Annotations already declare the safe read profile, yet the description adds real context the annotations cannot: PII facts are masked as ••••••, maskedKeys lists which keys were masked, and values are revealable only in the console under audit. That is exactly the kind of access-control caveat an agent needs and cannot get from readOnlyHint.

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 front-loaded sentence with the resource stated first, followed by an ordered list of returned components. It is dense but every clause carries information; the masking parenthetical is the only slightly heavy insertion, and it earns its place.

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

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

There is no output schema, so the description must carry the return shape, and it does so by enumerating the five provenance components. Combined with the annotations covering safety and the one-input schema, an agent has enough to call it correctly; only the traceId acquisition path is unaddressed.

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

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

There is a single parameter and schema coverage is 100%, with 'Trace ID of the execution' already documented in the schema. The description adds no format, sourcing, or acquisition guidance for the traceId (e.g. where to obtain one), so baseline 3 applies.

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

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

States a specific verb and resource: 'Get the lineage of a single decision'. The enumerated return contents (why per rule, input facts, responsibility chain, rule snapshot fingerprint) make the scope concrete. It does not name the nearest siblings (e.g. lexq_history_get, lexq_logs_get), so differentiation is left implicit, keeping it below 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?

The phrase 'a single decision' plus the required traceId implies this is the per-execution drill-down rather than the list/aggregate tools, but it never says so explicitly. No when-not-to-use condition or alternative is offered, so the agent must infer routing from the sibling names 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 write/destructive profile is covered structurally. The description adds real behavioral context beyond that: cancellation is cooperative, is state-gated, and is blocked for VIEWER role — auth and eligibility facts an agent could not infer from the annotations.

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

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

Three short sentences, front-loaded with the action and its scope, followed by the state rejection rule and the role restriction. 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 one-parameter mutation with no output schema, the key eligibility and permission facts are present. It omits what the final job state becomes and whether already-processed windows are retained, which would fully close the loop on 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?

There is a single parameter with 100% schema description coverage, so the schema already carries the meaning of jobId. The description only reinforces that the ID refers to a replay job, adding no format, sourcing, or lookup guidance 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 gives a specific verb ('cancel') and resource ('window replay job'), plus the state scope where it applies. It does not explicitly distinguish itself from the sibling lexq_simulation_cancel, but the replay-vs-simulation naming keeps them separable.

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 clearly states the conditions under which cancellation is valid ('PENDING or RUNNING') and that other states are rejected, which tells the agent when not to call it. It stops short of naming an alternative tool or what to do instead when the state is invalid.

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

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

Beyond the read-only and non-destructive annotations, it discloses synchronous execution, no billing or plan-usage consumption, a shared organization-level rate limit, compare weighting, and the 429/C-007 failure and reset behavior. It also explicitly guarantees no webhooks, notifications, events, or other outward rule-action effects, consistent with openWorldHint=false.

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

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

The purpose and returned information are front-loaded, followed by concise operational details. Despite covering several behaviors, each sentence supplies actionable information without filler or unnecessary 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 two-parameter tool, the definition supplies everything needed for correct selection and invocation, including inputs, key outputs, execution mode, cost, throttling, and side-effect behavior. Naming the returned diff fields and determinism verdict is especially valuable because there is no output schema.

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

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

Schema description coverage is 100%, and both parameters already explain their roles clearly. The description usefully places them in the replay workflow but adds no substantive format, validity, or selection guidance 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 precisely states the operation: re-evaluate one past execution identified by traceId against a candidate version. It also distinguishes the result as a decision diff plus determinism verdict, while the references to past executions and single-decision replays help separate it from dry-run and broader replay siblings.

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

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

The past-execution and candidate-version context clearly indicates when this operation applies, and 'Synchronous' sets an important usage expectation. It does not explicitly direct agents to lexq_dry_run, lexq_dry_run_compare, or lexq_replay_start when those alternatives are more 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?

Annotations only declare it is a safe read (readOnlyHint=true, destructiveHint=false); the description adds substantive behavior beyond that — the job must be in a completed state or the call is rejected, output is returned as text rather than a file handle, and exports over 100,000 characters are refused. These are exactly the failure modes an agent needs before calling.

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 the hard precondition, then the format comparison, then the return type and size cap — a sensible information hierarchy. It runs long for a two-parameter tool and the 'The two formats carry different things' clause is a throat-clearing lead-in to the more useful colon list, but no sentence is filler.

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

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

With no output schema, the description correctly takes on the return contract (file contents as text) and the size ceiling that determines whether a call will succeed. Preconditions, format semantics, and limits are all covered, leaving nothing an agent needs in order to invoke this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns extra credit by explaining what each enum value actually yields: CSV carries the fixed-column effect blast radius, JSON carries nested changed samples and action parameters whose keys vary per tenant. That is decision-relevant meaning the schema's 'Export format' string does not convey; jobId itself is left to the schema.

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

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

Names a specific verb and resource — 'Export a COMPLETED window replay job' — and immediately scopes it to a state (completed) that distinguishes it from lexq_replay_status and lexq_replay_list. It also declares the payload shapes per format, so the agent knows exactly what artifact it gets.

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 when-not ('A running job is rejected') and a clear decision rule for choosing between the two formats, including the non-obvious fact that JSON is not a superset of CSV. It does not name sibling tools (e.g., check lexq_replay_status first to confirm completion), which keeps it just short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: results are ordered reverse-chronologically and items are intentionally lightweight (not full job payloads), which sets agent expectations about result shape. It does not mention how deep history goes or how pagination behaves, so it is not 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?

Two short sentences, zero filler. The core purpose and ordering come first, and the disambiguation against the sibling follows, so the most decision-relevant information 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 two-parameter, fully annotated, read-only list tool with complete schema coverage, this is close to sufficient: purpose, ordering, result weight, and the sibling alternative are all present. The only remaining gap is depth of history or pagination behavior, which an agent might want when the list is large.

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

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

Schema description coverage is 100% for both parameters (page, size with defaults and bounds), so the schema does the parameter work. The description contributes only the ordering context, not any meaning about page/size semantics, which is the expected baseline-3 outcome when the schema is already complete.

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

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

States a specific verb and resource ("List window replay job history") plus the ordering guarantee (reverse-chronological), which an agent could not infer from the name alone. It also names a sibling, lexq_replay_status, so the tool is distinguishable within the replay tool family (start/status/cancel/export/decision/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?

Explicitly routes the agent: use this for lightweight list items, use lexq_replay_status for summary and changed samples. That is a clear when-to-use-this-vs-that statement. It stops short of a full 5 because other plausible alternatives (lexq_replay_export for full payloads, or pagination guidance for large histories) are not addressed.

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 destructiveHint=true and openWorldHint=false; the description adds materially new behaviour — the job is asynchronous, it is metered per replayed record under a REPLAY billing metric, and submission is role-gated. It leaves unexplained why the tool is flagged destructive (resource/cost consumption) and says nothing about cancellation via lexq_replay_cancel.

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: the operation and outcome first, then the operational constraints (billing, role, polling) in order of practical importance. No filler or restatement of the title.

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

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

For a job-submission tool with no output schema, the description covers the follow-up path (poll with lexq_replay_status) and the billing model. It omits what the submission returns (a job identifier) and any indication of expected duration or how to abort, which would matter for an agent managing a long-running, billed job.

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 from/to timezone and inclusivity rules and the 50k maxRecords cap all documented in the schema itself. The description adds only high-level framing ('date window of past executions', 'candidate version'), no syntax or format detail beyond what the schema already states.

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

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

The description gives a specific verb chain (submit an async job) plus the resource (a date window of past executions) and the outcome measured (blast radius / how many decisions change). It is unmistakably about replay rather than deployment or simulation, though it never names the near-neighbour lexq_simulation_start or lexq_dry_run_compare to sharpen the boundary.

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

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

It supplies clear operational guidance: this is async and must be polled with lexq_replay_status, and VIEWER role cannot submit. It does not say when to prefer this over lexq_simulation_start or a plain lexq_dry_run, so the exclusion set against siblings is only partial.

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 a safe read-only, non-destructive operation; the description goes well beyond that by disclosing the status state machine (RUNNING/COMPLETED/FAILED), which response fields populate in each state, the 0–100 progress scale, and the meaning of capped=true. That is substantive behavioral context an agent could not get from the structured fields.

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

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

Three tight sentences, front-loaded with the core action, then state semantics, then the cap caveat. No redundant wording and no repetition of the title or annotations.

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 properly assumes the burden of explaining return values and does so per status. Minor gaps remain: no mention of polling cadence/backoff or a pointer to the follow-up tool once COMPLETED, but an agent can call this correctly as-is.

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

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

There is a single parameter with 100% schema description coverage, and the schema already states it is the job ID from lexq_replay_start. The description adds nothing about the parameter itself, which is acceptable given the schema does the work — baseline 3.

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

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

States a specific verb and resource: "Poll a window replay job." This clearly separates it from sibling mutations like lexq_replay_start, lexq_replay_cancel, and lexq_replay_list, though it never names those siblings explicitly, so differentiation is by inference rather than stated.

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

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

The verb "Poll" implies repeated invocation until a terminal state, which is useful implicit guidance. However, there is no explicit statement of when to stop polling, how often to poll, or which sibling to call next once COMPLETED (e.g. lexq_replay_export or lexq_replay_decision) — usage is implied rather than spelled out.

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

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

Annotations already establish that this is a read-only, non-destructive, closed-world operation, so safety behavior needs no restating. The description usefully adds what the call returns (required keys, types, sample body), which matters because there is no output schema. It does not mention whether the version must be published or how it behaves for a nonexistent version ID.

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

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

Two compact sentences with no filler, and the core action is front-loaded before the return-value note. It is efficient, though it is terse enough that a small amount of additional routing context would have been worth the words.

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

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

For a two-parameter, read-only introspection tool with full schema coverage and no output schema, the description covers both the purpose and the shape of the result, which is the main thing an agent needs. Gaps are minor: preconditions such as version state or error behavior are unaddressed.

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

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

Schema description coverage is 100%: groupId is documented as the policy group ID and versionId as the version ID, both required with UUID formats. The description only implies the version scoping ('a version requires') and adds no syntax, format, or sourcing detail beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: it analyzes which input facts a given version requires, and it names the output content (required keys, types, example request body). That is clear enough for an agent to distinguish it from listing/creating facts. It does not, however, explicitly contrast itself with nearby read tools like lexq_versions_get or lexq_rules_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?

There is no explicit when-to-use or when-not-to-use guidance and no named alternative. An agent can infer it belongs before submitting facts for a version, but that workflow position is implied rather than stated, and nothing tells the agent how it differs from fetching the version itself.

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 annotations: it discloses the DRAFT-only guard, that unregistered targetVars trigger ACT-032 while read-only keys may stay unregistered, limits (25 SINGLE conditions, 10 nesting levels, 100 rules/version), and the ACT-033 conflict on BLOCK-owned keys. Crucially it explains execution semantics — conditions evaluate against input facts before any action runs, and BLOCK does not halt later actions or rules. Nothing here contradicts readOnlyHint=false / destructiveHint=false.

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

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

Front-loaded with purpose and scope before the reference material, then organized into labeled blocks (Condition, Limits, Operators, Actions) that are scannable. The operator tables and arithmetic matrix are dense but each row disambiguates real behavior (e.g. PERCENTAGE×MUL vs AMOUNT×MUL); the tradeoff is a very long description that reads like a spec excerpt.

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 creation tool with no output schema, the behavioral and semantic picture is essentially complete — validation rules, limits, error codes, and evaluation order are all given. The remaining gap is the mutex/isEnabled configuration surface, which is referenced only as a bare list in the schema string and never explained.

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 dominant parameter `rule` is a JSON string whose internals are barely sketched in the schema; the description carries that burden with full condition grammar, per-type operator tables, and MUTATE_FACT semantics including the AMOUNT vs PERCENTAGE matrix. It omits the mutexGroup/mutexMode/mutexStrategy/mutexLimit/isEnabled and name fields that the schema's CreateRuleRequest summary lists, leaving those undefined in both places.

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

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

Opens with a specific verb+resource+scope: 'Create a rule in a DRAFT version', and immediately distinguishes itself from the sibling it is not (lexq_rules_reorder changes order). An agent knows from sentence one both what it does and the constraint on where it can write.

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 usage context: creation must target a DRAFT version and the new rule lands last in priority, with an explicit pointer to lexq_rules_reorder for ordering. It does not, however, route to lexq_rules_update for later modification or lexq_rules_get/list for inspection, so sibling selection is only partly closed.

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 known. The description adds one real piece of behavioral context beyond that — the operation is scoped to DRAFT versions — but says nothing about irreversibility, whether the rule must be disabled first, or what happens to references/history after deletion.

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 short sentence with zero filler and the key constraint front-loaded. It is efficient, though the terseness is close to the edge where brevity becomes under-specification.

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

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

For a three-parameter delete with fully documented schema and destructiveness already flagged by annotations, the description covers the essential scope. It still leaves gaps for a destructive mutation: no note on irreversibility, on failure modes for non-draft versions, or on any post-delete state change, and there is no output schema to cover results.

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

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

Schema description coverage is 100% with all three UUID identifiers documented in the schema, so the baseline is 3. The description adds no meaning about how groupId, versionId, and ruleId relate (e.g. that the rule must belong to the given group and version), leaving that inference to the agent.

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 (Delete) and resource (a rule), plus a scope qualifier ('from a DRAFT version') that distinguishes it from the rule-mutating siblings like lexq_rules_update and lexq_rules_toggle. It does not explicitly name any sibling, so it falls short of a 5, but an agent can identify the operation without opening the schema.

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

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

The 'DRAFT version' qualifier implicitly tells the agent when this tool is applicable and implies it cannot be used against published versions, which is useful when-to-use guidance. However, no alternatives are named (e.g. versions_delete, rules_update to remove a rule config differently) and no prerequisites such as required permissions or version state transitions are given.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description contributes the payload shape (condition tree plus action definitions), which matters because no output schema exists, but says nothing about not-found behavior, permission requirements, or version scoping 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?

A single front-loaded sentence with the resource and returned content in immediate view; nothing is padded or repeated. It is efficient, though the terseness leaves no room for the scoping detail an agent would benefit from.

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 partially discharges its burden by naming the two major return components. However, for a tool requiring a three-level identifier path (group, version, rule) with no explanation of that hierarchy or of failure modes, the definition is only minimally sufficient.

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

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

Schema description coverage is 100%, so all three UUID parameters are documented in the schema and the baseline of 3 applies. The description adds no meaning beyond the schema: it never explains that ruleId is resolved within a groupId plus versionId hierarchy, which is the one piece of semantic context the schema cannot express.

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

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

The description names a specific verb and resource ("Get full rule detail") and enumerates what the detail contains ("condition tree and action definitions"), which distinguishes it from lexq_rules_list. It stops short of naming the sibling it supersedes, so the differentiation is inferred rather than stated.

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

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

Use is only implied: an agent can infer this is the drill-down companion to lexq_rules_list because it returns full detail rather than summaries. There is no explicit when-to-use, no mention of prerequisites such as needing groupId/versionId resolution first, and no guidance on when lexq_rules_update or lexq_groups_get would be the better call.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered without the description. The description adds real value by disclosing the sort order (priority ASC) and the returned summary fields (conditionSummary, actionSummary), which matters because there is no output schema — but it omits pagination behavior and whether disabled rules are included.

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, no filler, with the resource, scope, ordering and return shape all stated up front. Nothing could be removed without losing 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 two-required-parameter read tool with no output schema, the description covers ordering and return shape, which is most of what an agent needs. Remaining gaps — pagination/limits and whether the list includes inactive rules — are minor but real for a list 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 coverage is 100%, with both groupId and versionId documented as "Policy group ID" and "Version ID", so the baseline is 3. The description adds nothing about the parameters — not even that both are required to pin the version being listed.

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?

"List all rules in a version" gives a specific verb (list) and resource (rules) plus its scope (a version), which cleanly separates it from lexq_rules_get and lexq_rules_create. It stops short of naming a sibling explicitly, but the intent is unambiguous.

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

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

The description never says when to choose this over lexq_rules_get or lexq_profile_rule, and gives no prerequisites such as needing a published version or group access. Usage is only implied by the verb "List".

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 disclose readOnlyHint=false and destructiveHint=true, so the safety profile is covered. The description does add the priority-assignment model (1...N continuous, index 0 = highest), but it does not say whether omitted rule IDs are reassigned, dropped, or rejected — a meaningful omission for a destructive operation.

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

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

Two short sentences, front-loaded with the action and followed by the semantics that matter; nothing 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 destructive, all-required 3-parameter mutation with no output schema, the definition covers the mechanics but leaves open whether the supplied list must be exhaustive and what happens to rules not included. That gap matters for correct and safe 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%, so baseline is 3. The description adds real value beyond the schema by pinning the ordinal mapping (array index 0 maps to priority 1, continuous 1-based), which removes ambiguity about how ordering translates to stored priorities.

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: "Reorder rules by specifying rule IDs in desired order." An agent can tell this apart from generic update/create siblings, though nothing distinguishes it explicitly from lexq_groups_reorder or 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?

Usage is implied by the operation itself (you supply rule IDs in the order you want), but there is no explicit when-to-use versus lexq_rules_update, nor any stated precondition such as requiring a draft version or full rule 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?

Annotations already declare readOnlyHint=false, openWorldHint=false and destructiveHint=true, so the safety profile is largely supplied. The description adds the useful nuance that the rule is retained rather than removed, but it never explains why the operation is flagged destructive (e.g., disabling a rule changes live enforcement) or what permissions/scope are needed. No annotation contradiction: toggling a policy rule off can legitimately count as a destructive update even though the record survives.

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 filler. It is efficient, though its brevity leaves little room for the scoping or effect details an agent might want.

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-required-parameter mutation with no output schema, the description omits that the rule is addressed within a specific group and version, and says nothing about the result of the call. Annotations cover the safety angle, but scope and outcome are left entirely to 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%, with every field (ruleId, groupId, versionId, isEnabled) documented in the schema itself. The description adds no 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?

"Enable or disable a rule" states a specific verb and resource, and "without deleting it" distinguishes it from lexq_rules_delete. It does not differentiate itself from lexq_rules_update, which plausibly could also flip isEnabled, so the boundary with that closest sibling remains ambiguous.

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 "without deleting it" implies the use case: preserve the rule when you only want to change its active state. However, there is no explicit when-to-use vs. lexq_rules_update or lexq_rules_delete, and no mention of prerequisites such as needing a specific version 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?

Beyond the destructiveHint annotation, the description discloses the validation envelope (25 SINGLE nodes, 10 nesting levels below root) and, critically, that saving re-validates every action including untouched ones and can fail with ACT-032 when a targetVar is not a registered fact. That cross-field side-effect and failure mode is exactly the kind of information an agent cannot get from annotations or 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 tight sentences: scope first, update semantics second, validation and side effects third. No filler, no repetition of the title, and the most load-bearing constraint (re-check of all actions) is not buried.

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 mutation with no output schema, the description covers the version-state requirement, partial-update behavior, and the main failure mode. It leaves out permission requirements and the response shape (e.g., whether the updated rule is returned), which are minor given the strong behavioral coverage.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real meaning by constraining the condition tree inside the `rule` payload and reinforcing that omitted fields are preserved rather than nulled. It does not explain individual fields such as mutexStrategy or mutexLimit, which remain schema-only.

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 an existing rule") and scopes it to a DRAFT version, which immediately separates it from deployment/publish siblings. It also clarifies partial-update semantics ("Only provided fields are changed"). It does not name siblings like lexq_rules_toggle or lexq_rules_create, so differentiation is inferred 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?

"In a DRAFT version" is a concrete precondition that tells the agent when this tool is applicable, and the partial-update note tells it how to call it. There is no explicit statement of what to do when the version is not a draft (e.g., use versions_clone first) and no named alternative, 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 destructiveHint=true, readOnlyHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the useful constraint that only running or pending simulations qualify, but says nothing about whether cancellation is idempotent, whether partial results are discarded, or whether the action 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?

A single eight-word sentence with the resource and scope front-loaded and no filler. Nothing in it could be removed without losing information.

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