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

Annotations only declare readOnlyHint/idempotentHint/openWorldHint; the description adds substantial behavior: it merges args into a cached snapshot session across turns, asks one question at a time, auto-infers license from Auth0 state, soft-warns on demo+airgapped, and is plan-only (emits helm commands the user runs). These traits are not 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?

Front-loaded with the routing directive ('call it first') and the anti-pattern warning, so the most decision-relevant content comes first. It is long, and the log_destination/fleet_default paragraph substantially duplicates the schema text, costing it a point despite the complexity justifying a lengthy definition.

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 14-param, enum-heavy, nested-object wizard with an output schema already present, the description covers everything the agent needs: entry ordering, conflict rules (airgapped vs log10x), demo downgrade warning, license source modes, session persistence, and plan-only semantics. Return values are correctly left to the output schema.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds workflow-level semantics the schema does not: the order the wizard asks questions, which args are auto-picked vs asked, that snapshot_id is 'the one arg the wizard cannot infer', and that omitting license_source on a later call preserves the earlier choice. Fleet-default and log_destination text largely restates the schema, hence not a 5.

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

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

The first sentence states a specific verb+resource (progressive install wizard for Log10x Reporter/Receiver on Kubernetes) and immediately positions it as the single entry point for installs. It explicitly distinguishes itself from siblings log10x_doctor, log10x_login_status, and log10x_discover_env, so an agent can route without opening any schema.

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

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

Gives explicit when-to-use ('call it first'), explicit when-not-to-use ('Do NOT call log10x_doctor or log10x_login_status as a pre-flight') with the reason why, and the prerequisite chain ('Call log10x_discover_env first when there is no snapshot yet'). It also states tier prerequisites ('none, this is a pre-install tool').

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

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

Adds substantial behavior beyond the readOnly/idempotent annotations: `blockers` gating (no steps emitted while non-empty), the preflight table's FAIL row being a report rather than a gate, provider-specific verify probes, and the teardown lifecycle split (Terraform retains S3/SQS/IAM on aws; azure runs `--destroy`). This is exactly the non-obvious signaling an agent needs and is not derivable from 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?

Despite its length, it is front-loaded with purpose and then ordered by provider, blockers/preflight, verify, and teardown. Some clauses (e.g. quoting the provisioning script, repeating Helm/files mechanics) are dense run-ons, but for a 25-parameter tool the size is proportionate and most sentences carry unique information.

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

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

An output schema exists, so return values need no explanation, and the description still covers the parts an agent cannot infer: what the plan contains, how `blockers`/`preflight_summary.fail` behave, provider-specific probes, and teardown semantics. Nothing essential for correct invocation appears 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%, so the baseline is 3. The description goes further by explaining cross-parameter relationships: how `storage_provider` flips the whole aws/azure resource model, that `blockers` reflect missing inputs, and how auto-detection works. It does not cover every one of the 25 parameters, but it adds relational meaning the schema cannot.

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 precise verb+resource: given a DiscoverySnapshot, produce an install/verify/teardown plan for the Log10x Retriever. It explicitly contrasts the Retriever with Reporter + Receiver (no forwarder choice, standalone workloads), so an agent can place it against siblings like log10x_advise_install 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?

Names the prerequisite input (`snapshot_id` from `log10x_discover_env`) and the selection logic for providers (auto-detected, or overridden via `storage_provider`, auto-azure when offload destination is `azure_blob`). It does not explicitly route between this and the sibling advisories (e.g. `log10x_advise_install`), so it is clear on context but lacks exclusion 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 cover readOnly/idempotent/openWorld, so the bar is lower; the description adds real value by disclosing the three gates it checks, the default 7d Reporter age threshold, and the structured not_ready failure shape with the specific failed gates.

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 tool's role, then the checks, then the failure contract. No filler and nothing repeated from structured 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?

With an output schema present and full schema description coverage, the description needn't explain return fields; it still completes the picture by naming the gates and the not_ready envelope. Slightly short on what a passing result yields, but adequate for a read-only gate.

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 each parameter (horizon, destination, statedDailyGb, monthly_volume_gb, effectiveIngestPerGb) is richly documented in-schema. The description adds no parameter-level meaning beyond that, which is the expected baseline 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?

States a specific verb+resource: a 'pre-flight readiness gate' that verifies Reporter age, coverage stability, and anomaly absence. It explicitly positions itself relative to siblings by naming estimate_savings (and configure_engine) as downstream consumers, so an agent can distinguish it 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 a clear sequencing rule: run before configure_engine / estimate_savings. It stops short of stating explicit when-not-to-use conditions or what to do when the gate fails beyond returning not_ready, but the usage context is unambiguous.

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

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

Annotations already establish read-only, idempotent, closed-world behavior, and the description adds the important non-obvious precondition (the tool is useless without a prior configure_engine apply) and the projection methodology (Beta(2,2) prior updated with weekly evidence). It does not discuss rate limits or output size, but the precondition disclosure is the key behavioral context and it is present.

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 with the primary purpose front-loaded, followed by outputs, then the hard precondition. Dense but no filler; the Beta(2,2) methodology detail is arguably more than an agent needs to select the tool, which keeps it just short of a 5.

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

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

With an output schema present, return values need not be explained, and the description covers purpose, outputs, and the critical prerequisite. The only gap is that the one-line summary downplays the format=weekly_digest operational-digest mode, which the schema carries, but nothing required for correct invocation is missing.

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

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

Schema description coverage is 100%, so all seven parameters are already documented in the schema, including the format enum variants and the commitment_id-over-service precedence. The description does not add syntax, defaults, or precedence rules 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?

The description states a specific verb and resource ('Weekly aggregate against a commitment record') plus its three concrete outputs (delivered bytes/dollars, 90-day projection, markdown summary). No sibling tool in the list does commitment-relative reporting, and the description makes that scope obvious 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 gives an explicit precondition ('REQUIRES a commitment record opened by a prior configure_engine apply; without one there is no baseline') and names the sibling that creates it. It does not, however, name an alternative tool for the no-commitment case, so the agent must infer the fallback 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 cover safety (readOnly=false, idempotent=true, destructive=false), but the description adds substantial context beyond them: token requirements per source and the not_configured outcome, the compiler-flavor gate that refuses runtime/runtime-jvm engines, the automatic `--cap-add SYS_ADMIN` grant, output pinning/idempotency semantics, and the .jar-not-scanned caveat. This is unusually rich behavioral disclosure.

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 most decision-relevant behavior (inline wait vs pollable job_id) is front-loaded in sentence one, and nearly every sentence carries operational detail. It is a dense single block though, and a few token/credential points (e.g. the GitHub token requirement) restate what the schema property descriptions already say.

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 23-parameter tool with no required fields, the description supplies the missing decision context: source combination rules, credential prerequisites, backend/flavor eligibility, and the wait/poll lifecycle. An output schema exists, so the description only needs to signal that results include the library plus diagnostics, which it does.

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 baseline is already met; the description still adds cross-parameter meaning the schema can't express, notably the 'at least one source is required' constraint and the combinability rules among source_path, github_repos, docker_images, helm_charts and Artifactory. It does not add much per-parameter syntax beyond what the schema already documents.

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 ('Compile a symbol library from any mix of sources') and immediately names the sibling it hands off to (log10x_compile_status) as well as the polling alternative. An agent can distinguish this from log10x_compile_status, log10x_compile_link and log10x_extract_templates 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?

Explicitly states when the call returns inline (small compiles, every re-run reusing the pinned output folder) versus when it returns a job_id, and names the fallback path (poll log10x_compile_status, or re-call this tool). It also flags the special `max_wait_ms: 0` fire-and-forget mode and the token prerequisites that gate each source type.

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

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

Annotations already mark it as a non-read-only, idempotent, non-destructive write; the description adds substantial context beyond that: it scans 0 new files, merges on-disk units into the library written to the same folder, waits inline up to max_wait_ms (typically returning in one call) and otherwise hands back a job_id, and requires the compiler flavor while refusing the native build. No contradiction with the write/idempotent annotations.

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

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

The purpose, scope, and key constraint are front-loaded in the first sentence, and each subsequent sentence carries real information. It is dense and long for a single paragraph, but there is little filler to cut.

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 an output schema present, the description covers purpose, prerequisites, execution semantics, timing, and fallback behavior. Nothing an agent needs in order to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all five parameters (baseline 3). The description goes further by tying units_path to the compiler's outputSymbolFolder and explaining max_wait_ms's inline-vs-job_id behavior, adding cross-parameter context on top of 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 opening sentence states a specific verb (Link), resource (existing folder of .10x.json symbol units), and output (.10x.tar library), plus a distinguishing constraint (NO source scan). It explicitly contrasts with log10x_compile, so an agent can tell them apart without opening either schema.

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

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

Gives three concrete when-to-use scenarios (re-link after editing/pruning units, assemble from a piecemeal units tree, rebuild from a prior compile's output folder) and names log10x_compile_status as the polling alternative. Restrictions (compiler flavor required, native runtime refused) are stated up front.

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/idempotent annotations, the description discloses substantial behavior: the four job_status states, that the first terminal poll captures the exit code and frees the container while the library is never removed, and that diagnostics degrade on an older engine image. This is exactly the lifecycle context an agent needs and cannot get 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 purpose is front-loaded in the first clause and each sentence carries real content (states, diagnostics, degradation, lifecycle). It is dense and longer than necessary — the diagnostics sentence is heavy — but almost nothing is padding.

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

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

For a job-polling tool with an output schema present, the description covers the full lifecycle: what is returned, terminal-state side effects, degraded behavior on old images, and post-completion readability. Nothing needed to poll correctly is missing.

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

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

Schema description coverage is 100% and the schema already documents view, job_id, and log_lines (including raising log_lines for diagnosis). The description restates that job_id originates from compile and that the log tail is credential-redacted, but adds little parameter-level meaning beyond what the schema provides, 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 opens with a specific verb+resource (poll an async compile) and immediately scopes it to jobs produced by log10x_compile / log10x_compile_link, distinguishing it from those producer siblings. An agent can tell exactly what this tool returns (job_status, units, diagnostics) 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 clearly states the usage context: poll a job started by log10x_compile or log10x_compile_link, keyed by job_id, and it explains that later polls stay readable after the container is freed. It stops short of an explicit when-not condition, but the polling lifecycle is unambiguous.

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

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

Annotations cover read-only/idempotent/open-world, but the description adds substantial behavioral context beyond them: capability gating (receiver tier, SIEM type, offload bucket), the non-observe routing to log10x_explain_mode, the envelope contract (must_render_verbatim, must_ask_user, forbidden_next_actions), and siem_lens provenance stamping (siem_actual vs siem_lens). None of this is in 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?

A dense, front-loaded block with no filler sentences – every clause (tier variants, routing, envelope, lens) carries operational weight. It runs long, but the length is justified by the branching behavior; slightly tighter grouping of the envelope and lens clauses would read better.

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?

Complete for a branching menu tool: entry condition, tier-dependent output shapes, downstream routing, envelope fields, and forbidden actions are all present, and an output schema exists so return-value enumeration is unnecessary. Nothing an agent needs to call it correctly is omitted.

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

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

Schema coverage is 100% so the baseline is 3, but the description meaningfully amplifies it: siem_lens is framed as a what-if lens that keeps measured volumes but re-gates and re-prices at list rates for the lens destination, and destination is described as an override of env-autodetected SIEM carried forward in routes_to.args. That is semantics the schema text alone implies but does not spell out.

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 resource (the cost-reduction option menu) with tier-conditional content, and explicitly distinguishes itself from siblings by naming log10x_start as the trigger and log10x_explain_mode / log10x_estimate_savings / configure_engine / pattern_mitigate as downstream or forbidden tools. An agent can place this tool in the flow 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?

Explicit when-to-use ('CALL THIS after the user picks show me what cutting costs would look like from log10x_start'), variant behavior per tier (6-mode menu at Receiver/Retriever, 2-entry collapse at Reporter-only/Dev), and explicit exclusions ('forbidden_next_actions ... do not call estimate_savings, configure_engine, or pattern_mitigate until the user picks').

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds genuine context beyond that: the backend is env-var configured and the response is the raw Prometheus shape plus backend metadata. It omits auth requirements and rate limits, 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?

Three sentences, front-loaded with what the tool is, then when to use it, then the alternative. Dense but every sentence carries weight; slightly longer than strictly necessary but no filler.

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

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

With an output schema present the description needn't explain return values, yet it helpfully notes the raw Prometheus shape plus backend metadata. Combined with the routing guidance, an agent has enough to invoke it correctly; only permission/limit specifics are 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%, so the schema already documents promql, mode, step, start and end including the mode=range requirements. The description adds only an example PromQL expression and does not clarify parameter semantics 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+resource ('PromQL passthrough to the customer metric backend') and pins the backend to the LOG10X_CUSTOMER_METRICS_URL configuration. It distinguishes itself from siblings by framing its role as 'the escape hatch' vs the deterministic primitives it names.

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-to-use cases (explore the label universe, run a one-off PromQL expression, verify a metric exists) and names the exact alternative chain (`log10x_metrics_that_moved` → `log10x_rank_by_shape_similarity` → `log10x_metric_overlay`) that should be preferred for typical workflows.

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

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

Annotations already declare readOnlyHint/idempotentHint/openWorldHint, yet the description adds real operational context: the Datadog query API is GET-only with DD_API_KEY/DD_APP_KEY/DD_SITE, the engine files are also read, nothing is written, and the tool is stateless so `next_since` carries continuity. It also discloses the source series' tag set and notes the team label appears only once shipped.

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 modes are front-loaded, and the closing sentence covers auth and safety. The middle is a dense, heavily parenthesized run-on describing fields and data sources that takes effort to parse.

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

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

For an 11-parameter, zero-required, multi-mode tool with an output schema, the description covers mode selection, the parameter interactions that matter (since/lookback, team_tag detection, environment for gitops lookup), data provenance, and auth. Return values are delegated correctly to the output schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics the schema does not: the exact definition of 'new' relative to `lookback`, the continuation contract for `since`/`next_since`, and the meaning of `view: "monitors"` as producing applyable definitions. This meaningfully exceeds the schema text.

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 up front: a weekly change report read from the engine's Datadog metric output, plus a `view: "monitors"` mode that emits two Datadog monitor definitions as JSON. The three output modes and the fields each statement carries are spelled out, so an agent can tell this apart from reporting siblings like log10x_commitment_report or log10x_whats_changing.

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

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

Gives clear when-to-use context: continuation via the previous report's `next_since`, `view: "monitors"` for the account owner to apply, and `monitors` reading nothing. It does not, however, name or exclude any sibling tool, so the agent must infer which of the many reporting tools to prefer.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond that: the consequence of skipping the check (silently breaking a live alert). The credential-dependent in-process vs. bash-command fallback behavior lives in the schema rather than the description, so a higher score is not warranted.

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

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

Front-loads purpose, then a bolded imperative warning and additional trigger examples. Every sentence adds decision-relevant information with no filler.

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

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

Output schema exists, so return values need not be described, and the schema covers the credential/fallback mechanics. The description says 'generate commands' but the schema reveals it may also run in-process and return live names/URLs; that nuance is not mirrored in the description, though the schema compensates.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema. The description only restates the pattern input ('Given a pattern identity') and adds nothing on vendor, service, or severity. Baseline 3 is correct 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?

States a specific verb (generate commands to scan) plus the resource (SIEM/observability stack dependencies for a given pattern) and enumerates the concrete targets (Datadog monitors, Splunk saved searches, Grafana dashboards, Prometheus alert rules). An agent can distinguish this from sibling tools like log10x_pattern_mitigate 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?

Gives explicit trigger conditions: call before any mute, drop, or source-code deletion, and call when a developer asks whether a log line is safe to delete or what references a pattern. It names the risk that motivates the call rather than leaving usage to inference.

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

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

Annotations cover readOnly/idempotent/openWorld, and the description adds genuine context beyond them: the snapshot is cached 30 minutes, every shell call is logged in probeLog for audit, only kubectl get and aws describe/list verbs are used, and there are no tier prerequisites. These are behavioral facts an agent cannot 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?

Purpose is front-loaded, but the body is bloated with three separate bolded 'do NOT' warnings and repeated restatement of the account-vs-infra distinction. Each block has routing value, yet the formatting and redundancy cost readability rather than adding information.

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

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

An output schema exists so return values are covered, and the tool's complexity (8 optional params, open-world probes, cache TTL) is fully addressed: the description explains probe scope, caching, audit logging, and prerequisites. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all 8 parameters including defaults and auto-selection behavior. The description adds only the snapshot_id caching detail, which is a return value rather than a parameter. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Read-only discovery of the caller's Kubernetes cluster + AWS account') and explicitly disambiguates from the Log10x ACCOUNT, which is the most likely confusion. An agent can distinguish this from log10x_login_status 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?

Gives explicit when-to-use ('when the user wants to install Log10x: call this FIRST then log10x_advise_install'), explicit when-not-to-use (do not call doctor/login_status/savings before install), and names the alternative tool for account-env questions. This is a textbook routing definition.

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

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

Annotations cover the safety profile (readOnly, idempotent, openWorld), and the description adds substantial context beyond them: per-session caching keyed by (environment, customer-backend-endpoint), the 0.7/0.5 accept and runner-up thresholds, the orchestration role, and the structured `no_join_available` failure shape. This is exactly the cross-cutting behavior annotations cannot express.

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 and mechanism, then the caching rationale and the usage directive. It is dense and slightly long, but nearly every sentence (thresholds, caching key, no_join_available) earns its place; minor redundancy in restating the 0.7 threshold already implied elsewhere.

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 9-param, zero-required tool with an output schema and full annotation coverage, the description supplies everything an agent needs: purpose, mechanism, caching semantics, orchestration position, and failure behavior. Nothing material is missing.

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

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

Schema description coverage is 100% and the parameter docs are already rich (window, force_refresh, minimum_jaccard, overrides), so the schema carries the semantics. The description restates the 0.7/0.5 threshold behavior but adds no syntax or format detail beyond the schema; baseline 3 applies.

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

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

States a precise verb+resource: 'Auto-discover the structural join label between Log10x pattern metrics and the customer metric backend.' It names the mechanism (Jaccard on label value sets) and distinguishes itself from the sibling primitives that consume its result, so an agent can place 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?

Explicitly routes the agent: 'Agents should normally NOT need to call this tool directly: the primitives call it internally,' then names the exception cases (inspecting the join universe, forcing re-discovery after backend changes). This is a textbook when/when-not statement.

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

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

Annotations already declare readOnly, idempotent, and openWorld, so the safety profile is covered. The description adds real value beyond that: it discloses the dual behavior (full label list vs. distinct values when a label is passed) and the motivating failure mode (guessing "namespace" instead of "k8s_namespace").

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 purpose, then usage, then the mode switch. The concrete "namespace" vs "k8s_namespace" example earns its place by making the anti-guessing rationale vivid, and nothing is padded.

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

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

Output schema exists, so return formats need no explanation, and annotations carry the safety profile. Purpose, session-start usage, and the label-mode distinction are all present – an agent has everything needed to call it correctly.

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

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

Schema coverage is 100% and the properties already document label, limit (default/max), and environment in detail. "Pass a label name to get its distinct values" largely restates the schema's own text, so the description adds little beyond the structured fields – baseline 3 is appropriate.

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

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

States a specific verb and resource: "List the labels Log10x metrics can be filtered or grouped by." The resource (labels for metric filtering/grouping) is precise and clearly distinct from the other discover_* siblings (discover_env, discover_join), and it also reveals the second mode (distinct values per label).

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

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

Gives a concrete trigger: "Call at the start of a session, or before calling any tool that takes a label/filter argument," which is exactly the context an agent needs. It does not name when-not-to-use or explicitly route to an alternative tool, so it falls just short of the 5 bar.

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

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

Annotations already declare readOnly/idempotent/openWorld, and the description adds substantial behavior beyond them: the specific external endpoint probed (prometheus.log10x.com) including auth, which checks are informational (Retriever endpoint, Datadog credentials) versus gating, and the pass/warn/fail output with remediation hints. It also discloses the LOG10X_CUSTOMER_METRICS_URL precondition for the enrichment-floor check, with no contradiction of 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?

Front-loaded with purpose and usage, then a probe list that is dense but each clause names a real check rather than padding. It is on the longer side and reads as a run-on enumeration, but nearly every phrase carries information.

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

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

For a read-only diagnostic with an output schema, the description is thorough: probes covered, output format, and usage timing. The one gap is routing against the several overlapping diagnostic siblings (env_validate, dependency_check, login_status), which an agent must resolve on its own.

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 optional parameter at 100% schema description coverage, and the schema already explains the multi-env omit-vs-nickname behavior in full. The description adds no further parameter semantics 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 ('Run a startup health check on the Log10x MCP installation') and enumerates the exact probes performed, so the agent knows precisely what it does. However, it never differentiates from overlapping siblings that also perform validation, such as log10x_env_validate or log10x_dependency_check, so sibling disambiguation is left 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?

Gives two concrete trigger conditions: 'once at the start of a session to verify the install' and 'any time a tool returns an unexpected error to isolate whether the problem is configuration or transient.' That is clear context for when to reach for it, but no explicit when-not or named alternative (e.g., a narrower env-only check) is offered.

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 past the annotations (readOnlyHint/openWorldHint/idempotentHint): it explains the `--network none` container fence, that the emitted script carries no log10x hostname and the server refuses otherwise, the sampling equivalence to the SIEM path, and the exact return payload. It also discloses the only side effect, one 0755 script file, which is the sole tension with a strict reading of readOnlyHint, and the description surfaces it rather than hiding it.

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 correctly: the read-only/renders-not-runs split comes first, then the POC step map, then args, then returns. It is dense and information-rich rather than padded, though the POC step enumeration and repeated 'same default as log10x_poc_from_siem_submit' refrains run longer than strictly necessary.

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

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

An output schema exists, so return values are covered structurally, and the description still tells the agent what comes back (script text, read-only API operations/credential variables, review checklist, exact next `log10x_poc_from_local` arguments). For a 7-param tool embedded in a multi-step workflow, nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters in detail, and the description's inline arg list largely restates defaults. It does add cross-tool meaning the schema lacks, notably that `window`/`target_event_count` defaults deliberately match `log10x_poc_from_siem_submit` so both POC paths sample the same size, and the ./poc/logs mount rationale. That is real added value, but it is incremental over an already-excellent 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?

Opens with a specific verb+resource ('Render a read-only shell script that exports a log sample') and immediately delimits scope: it renders, it does not run, and it contacts nothing. It separates itself from the credentialed path (`log10x_poc_from_siem_submit`) and names the follow-on tool (`log10x_poc_from_local`), so an agent can place it among 50+ 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?

Explicit when-to-use: 'step 2 of the fenced POC' with steps 1/3/4 enumerated, plus a second trigger condition ('whenever the credentials live somewhere this process does not: a jump host, a locked-down laptop, another team'). The alternative path and the condition that selects it are both stated.

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

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

Annotations already cover safety (readOnly, idempotent, not open-world), but the description adds real behavioral context: the resolver precedence rule (on-prem store wins over env vars), the silent-override failure mode, and the edge case where a pure on-prem config returns ok:true with an empty diff. This is well beyond what annotations convey.

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

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

Front-loaded with purpose then an explicit when-to-call clause, followed by args, return shape, and the empty-diff edge case. Slightly dense, but each sentence (precedence rule, remediation routing, edge case) carries distinct 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?

For a single-parameter read tool with an output schema, the description is complete: it explains the comparison, the precedence semantics, the trigger scenario, the return field shape, and the no-ambiguity edge case. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100% for the single env_id parameter, and the description only restates that it is required and accepts a UUID or nickname — the same information the schema already provides. Baseline 3 applies since 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 precise verb+resource: compare the stored env-config document against the LOG10X_* env vars the env-var bridge would have produced, and report per-field disagreements. This is clearly distinguishable from sibling tools like log10x_env_validate or the setters it references.

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 trigger: 'Call this when the user says "but I set the env var" or downstream tools report a value the user thinks they overrode.' It also names the alternative remediation paths (unset the env var, or use log10x_dest_set / log10x_set_gitops_repo to update the stored doc).

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/idempotent/openWorld=false, and the description adds substantial context beyond them: the exact validation categories checked (region requirements, URL shape, cluster-to-destination alignment, region egress), that findings carry severity, and critically that errors block downstream actions while warnings surface to the user. No contradiction with 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?

Dense but front-loaded: the action and the file path come first, then call triggers, then a structured list of findings. The findings enumeration is long but each item earns its place by telling the agent what will be reported; a slight trim of the parenthetical examples 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?

With an output schema present, return format need not be explained, yet the description still characterizes the result shape (parse result plus severity-tagged findings with remediation). For a read-only validation tool with annotations covering safety, nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and the single parameter is fully documented there, so the baseline is 3. The description restates 'env_id (required, env_id UUID or nickname)', adding no semantics beyond what the schema already says about resolution order and accepted 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 (validate) and resource (stored env-config document at a concrete path), plus the exact scope: zod schema parse plus cross-field sanity checks. An agent can distinguish it from siblings like log10x_doctor or log10x_env_diff_vs_envvars 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 says when to call it ('after any edit to the env doc' via named tools, or 'pre-flight before downstream tools') and names the downstream consumers that need a coherent config. Provides both trigger conditions and the consequence of ignoring results.

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

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

Annotations only cover the safety profile (read-only, idempotent, closed-world); the description goes well beyond them, disclosing that dollar fields are emitted as null rather than fabricated, that the envelope carries rate_source (list_price | customer_supplied | unset), and that siem_lens stamps siem_actual vs siem_lens. These are behavioral traits an agent cannot 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?

The routing note is front-loaded and the two modes are laid out in sequence, so the reader gets orientation first. It is dense and long, with several clauses packing multiple facts per sentence, but nearly every sentence carries distinct information rather than restating the schema.

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

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

For a 32-parameter, two-mode estimator, the description covers the mode split, the rate/overlay semantics, the siem_lens provenance, and the tier prerequisite. With an output schema present it need not explain return values, and it keeps envelope-field context to the pieces (rate_source, volume stamps) that affect correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all 32 parameters in depth. The description adds framing (percent-first reporting, the null-rate rule, the siem_lens provenance behavior) but no per-parameter syntax or format detail beyond what the schema supplies; the baseline 3 is correct when the schema does the heavy lifting.

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

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

States a specific verb+resource (estimate savings) and then precisely delineates the two modes: forecast projects bytes_in -> bytes_out reduction, verify counts realized savings from the routeState label. It differentiates itself from the deployment/POC siblings by scoping its own boundary ('before anything is deployed, use ... instead'), so an agent can place 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?

Gives an explicit precondition (Reporter-tier cost attribution required) and an explicit alternative for the deployment case (log10x_poc_from_local / log10x_poc_from_siem_submit), plus a fresh-session routing rule to log10x_start. It does not, however, distinguish itself from the similarly named log10x_savings sibling, leaving one obvious selection ambiguity unaddressed.

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

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

Annotations cover readOnly/idempotent/openWorld, yet the description adds substantial non-obvious behavior: hashes are stable per engine/symbol library/config, the lookup is structural rather than byte-exact, offload disposition comes from the Reporter routeState label, AI category is gated on LOG10X_AI_SUMMARY=true, cost overlay only appears when $/GB is set, and it advises saying so when no match 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?

Front-loaded with the core resolve-and-return purpose before the routing directive and the anti-pattern exclusion, so the critical part is read first. The opening sentence is a long, dense run-on enumerating many return fields, which slightly hurts scannability but earns its space.

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

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

With an output schema present and rich annotations plus 100% schema coverage, the description need not explain return values, yet it still frames them usefully. For a 9-parameter, 0-required tool with multiple aliases and conditional behavior, nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the schema itself thoroughly documents every parameter (including aliases and the siemScope cross-pillar case), so the baseline of 3 applies. The description reinforces the meaning of pattern_hash/tenxHash stability and the $/GB cost overlay but largely restates what the schema already carries.

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

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

States a specific verb+resource pair: resolve a raw log line or pattern name to its pattern hash, then return byte volume, share per service, delta, first-seen timestamp, and offload disposition. It explicitly distinguishes itself from the sibling log10x_resolve_batch by input cardinality, so an agent can route 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?

Gives a bolded 'Call this first' trigger naming the exact user intents ('what is this', 'is this new', 'is this safe to drop') and the input shape (a SINGLE log line). It also names the alternative sibling log10x_resolve_batch and the condition (MULTIPLE events / SIEM dump / batch triage) that selects it.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, but the description adds real behavioral context: must_render_verbatim (plain text, no markdown), must_ask_user, and forbidden_next_actions that lock apply tools and log10x_preview_filter until the user picks. This is unusually rich disclosure, though much of it describes return fields that the output schema may already carry.

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

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

Front-loaded with the ordering precondition and information-dense throughout. However, the extended enumeration of return fields (must_render_verbatim, must_ask_user, forbidden_next_actions, routes_to.*) partially duplicates what the output schema should convey, adding some bulk.

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

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

With annotations, a full output schema, and 100% param coverage already present, the description supplies exactly the missing orchestration layer: when to call it, what it returns semantically, and where it routes. Nothing needed to invoke it correctly appears to be missing.

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

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

Schema description coverage is 100% and the mode enum documents each lever in depth, so the schema does the heavy lifting. The description restates the mode list but adds no syntax or format meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource (explain a chosen enforcement mode) and enumerates the exact modes covered. It clearly differentiates itself from siblings by naming log10x_cost_options as its predecessor and log10x_configure_engine / log10x_preview_filter as downstream routes.

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

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

Explicit trigger ('CALL THIS AFTER log10x_cost_options when the user picks a mode'), plus routing rules that tell the agent which sibling to invoke next for each mode. The observe_only null-routes case is called out, removing the main ambiguity.

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

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

Annotations cover the safety profile (readOnly, idempotent, openWorld), and the description adds substantial context beyond them: no Kubernetes, deployed Reporter, or account required; execution is in-process via a tenx binary or docker container; and a REQUIRES-a-local-engine constraint with a warning that log10x_doctor does not preflight it. That missing-preflight disclosure is genuinely non-obvious and actionable.

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?

Long but front-loaded and dense with zero filler: core action first, then companion relationship, then environment requirements, then use cases, then validation mode and the engine constraint. Every sentence carries distinct, decision-relevant 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?

With an output schema present and 100% param coverage, the description supplies what structured fields cannot: the local-engine requirement, the no-preflight caveat, validation semantics, and the sibling relationship. Nothing needed to invoke 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%, so the baseline is 3; the description still adds value by explaining the expected.min_templates / required_patterns / forbidden_merges block as an assertion mechanism whose results surface as PASS/FAIL in output, and by clarifying that each view yields a typed envelope. It stops short of explaining every parameter, but covers the semantically tricky one.

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

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

Specific verb+resource: 'Extract the structural template library from a set of log lines', plus the mechanism (local Log10x pipeline) and the exact return shape (per-template records with templateHash + body, event count). It explicitly names its sibling log10x_resolve_batch and the shared question both answer, so an agent can distinguish it without opening schemas.

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

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

Enumerates three concrete use cases: (a) bootstrapping a pattern catalog, (b) offline auditing of stored logs, (c) validating config changes. It also states the precondition that turns extraction into validation (pass expected.*) and names log10x_resolve_batch as the companion. When-to-use and how-to-select are both 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 readOnly/idempotent, and the description adds substantial extra behavior: sampling is lossy (9 of 10 dominant events discarded), default thresholds are tagged unvalidated_default, and the output envelope surfaces observed_dominant_pct_distribution so the agent can judge calibration. This is exactly the kind of beyond-annotation disclosure that earns top marks.

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

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

Front-loads the purpose, then layers differentiation, the Stage 1 input contract, and calibration caveats. It is dense and somewhat long, with a quoted example that is illustrative but adds bulk; still, nearly every sentence carries information, so only minor trimming is warranted.

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

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

With an output schema present, the description need not restate returns, yet it still explains the key envelope field (observed_dominant_pct_distribution) and references the agent behavior contract doc. Given a 5-param tool with a required events array and calibration-heavy defaults, everything an agent needs to call it correctly 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 would be 3, but the description adds meaning: it explains the calibration caveat behind min_concentration (0.6 floor) and sample_n (1/10), and points the agent to threshold_audit for judging whether the defaults fit the dataset. That is genuine added value over the schema text.

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 behavior: identify patterns where one slot value dominates a field (>=60% by default), with a concrete example of the finding it produces. It explicitly differentiates itself from analyzer field histograms, explaining that dominance is measured within the structural pattern rather than globally, so an agent can tell it apart from siblings without opening schemas.

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

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

Gives clear usage context (surface sampling opportunities, Stage 1 accepts events as a paste array shaped like log10x_resolve_batch) and contrasts the mechanism against analyzer field histograms. It does not state an explicit when-not or name a preferred alternative for overlapping cases, so it falls 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 only cover safety (readOnly, idempotent, openWorld), and the description adds substantial behavior: dual output shapes (causal chain vs co-drifter cohort), automatic input-mode detection, acute-vs-drift trajectory detection, confidence decomposition into named sub-scores, and offload_status semantics tied to top_patterns/pattern_trend. It even instructs the agent to present the markdown report unmodified, which is real operational context beyond 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?

It is long but front-loaded: the first sentence delivers the core purpose and deliverable before expanding into triggers, mode detection, and output morphology. Most sentences earn their place, though the confidence-decomposition and report-presentation instructions are somewhat stacked and could be tightened.

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

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

Given the tool's high complexity, a rich 7-param schema, and an existing output schema (so return values need no explanation here), the description covers mode detection, output shapes, confidence mechanics, and usage triggers. An agent has everything needed to select and invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description meaningfully clarifies the required starting_point ('pass their words verbatim', auto-detected mode) and explains what the tool does with it, adding intent the schema alone does not convey. The optional params (depth, window, etc.) are already fully documented in the schema and get no extra treatment here.

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 ('Single-call root-cause investigation for any log line, pattern, service, or environment') and immediately names the deliverable ('complete causal chain ... or co-drifter cohort ... plus ready-to-run verification commands'). It also carves out a distinct role as a single-call orchestrator that internally runs the appropriate flow, setting it apart from narrower siblings like log10x_pattern_trend or log10x_top_patterns.

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 trigger phrases ('what is going on with X', 'why is X spiking', 'investigate X', pasting a log line/alert) which tells the agent precisely when to reach for it. However, it offers no when-not-to-use guidance and never names an alternative sibling for cases the agent might prefer (e.g., a single-trend 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 declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: demo-mode fallback returns a step-by-step config guide versus signed-in mode returning identity, per-env permissions, default env, and last-used env. Some of this return detail overlaps the output schema, keeping it from a 5.

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

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

Purpose and the primary routing rule are front-loaded, and every sentence carries actionable routing or mode information. The dense list of synonym phrasings and the parenthetical detail on the Auth0 device flow are slightly verbose, but nothing is wasted given 57 sibling tools.

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

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

With annotations carrying safety and an output schema carrying return shape, the description only needs to cover purpose, routing, and mode behavior — all of which it does. An agent has everything required to select and call it correctly.

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

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

Zero parameters, so the baseline is 4. The description explicitly confirms 'takes no args,' which is consistent with the empty schema and removes any doubt about argument shape.

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

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

States a specific verb+resource ('List the user's Log10x ACCOUNT environments') plus secondary purpose ('report credential / login state'), and explicitly excludes the look-alike sibling log10x_discover_env. An agent can distinguish it from signin/signout/discover tools without opening any schema.

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

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

Gives explicit trigger phrasings ('which environments do I have', 'am I logged in'), names the correct alternatives for adjacent intents (log10x_signin_start / log10x_signin_complete for login/signup), and states an explicit when-NOT rule for log10x_discover_env. Routing is fully specified.

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

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

Annotations already declare readOnlyHint/idempotentHint, but the description adds substantial context beyond them: the result is a sample-derived ratio, not a SIEM meter reading; it requires a local tenx binary with the LOG10X_TENX_PATH/PATH resolution order; and it discloses confidence tiers keyed to event counts. These are real behavioral traits an agent cannot learn 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?

Dense and front-loaded, leading with the measurement semantics before prerequisites. It repeats the local-engine requirement twice (the 'tenx CLI installed locally OR SIEM credentials' list and the trailing 'REQUIRES a local engine' sentence), which is the main waste, and the final sentence is redundant emphasis.

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

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

An output schema exists, so return values need not be re-explained, yet the description still names `compaction_ratio_x` and its numerator/denominator for clarity. For a tool with credential, local-engine and sampling caveats, it covers everything an agent needs to call it correctly or route elsewhere.

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 baseline is 3, but the description adds interpretive meaning: `sample_size` events are pulled over `timeRange`, and larger samples map to the stated confidence tiers. It also clarifies that each measured capture corresponds to one destination named in `compact_ratio_basis`, which is useful framing 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 ('Measure per-pattern compact ratios (bytes before and after encoding)') and scopes it precisely to a sample pulled from the customer's SIEM. It explicitly distinguishes itself from the default-ratio path by naming `log10x_estimate_savings` as the downstream consumer, so an agent can separate it from siblings like `log10x_savings` 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-to-use ('Use this to replace the destination's default compact ratio in log10x_estimate_savings') plus hard prerequisites: tenx CLI locally or Docker, and SIEM credentials matching `log10x_poc_from_siem_submit`. It also states the outcome ('Results flow into log10x_estimate_savings to improve savings projections'), leaving nothing to inference.

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

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

Annotations already cover read-only/idempotent/open-world safety, and the description adds meaningful behavior: it deliberately computes no Pearson and no tier ('pure raw data'), auto-selects bucket size from window length, and right-aligns both series to a shared trailing bucket grid. That is real disclosure beyond the structured fields, though cost/rate behavior and error handling are left 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?

Three dense sentences, front-loaded with the pipeline position and the return shape before the usage and alignment notes. Every sentence carries information, though the alignment clause is tightly packed and takes a second 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 an output schema present, the description needn't spell out return values, and it appropriately names only the salient facts. It gives enough workflow context (single-candidate by design, step position) for an agent to invoke it correctly, despite 12 parameters.

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 83%, so the schema already documents most parameters, including aliases like `window`/`timeRange` and `candidate`/`candidates[0]`. The description adds only the bucket auto-selection and alignment semantics, which is marginal over 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 precise verb+resource: return aligned anchor + candidate timeseries with named deterministic facts (`peak_at`, `peak_offset_seconds`, `n_buckets_aligned`). It also positions itself explicitly as the third step in a pipeline, distinguishing it from `log10x_rank_by_shape_similarity`, which ranks rather than overlays.

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

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

Explicit when-to-use: 'Use this once `log10x_rank_by_shape_similarity` has narrowed to a single suspect, or to manually verify any anchor/candidate pair side-by-side.' This names both the alternative tool and the condition that selects this one, leaving nothing to inference.

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

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

Annotations only cover read-only/idempotent/open-world, so the description carries the algorithmic burden and does: it discloses the median-rate phase partitioning, the ≥15% mean-difference rule, the three return buckets (`moved[]`, `not_moved[]`, `evaluation_failed[]`), and critically that the default threshold is uncalibrated and outputs are tagged `unvalidated_default`. That last point is a behavioral caveat an agent cannot get from the schema and would otherwise misread as a validated 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?

Purpose and scope are front-loaded and the composition guidance closes it out, so ordering is good. It is a single dense block with several layered parentheticals, which slightly taxes readability, but 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?

An output schema exists so return-value explanation isn't owed, yet the description still enumerates the result partitions. Combined with the anchor semantics, candidate-set guidance, calibration caveat, and sibling hand-off, this is complete for an 11-parameter analytical primitive.

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 64%, and the description reinforces the two tricky parameters (anchor identity semantics, and the phase_gap_floor threshold with its calibration caveat) plus the rationale for the 100-candidate cap. It does not cover `step`, `environment`, or the three `customer_metrics_*` override parameters, which fall back to the schema alone.

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 ('deterministic filter on which customer metrics moved while an anchor was active') and immediately scopes it to the cross-pillar investigation flow. It names the sibling tools it composes with (`log10x_rank_by_shape_similarity`, `log10x_metric_overlay`), so an agent can tell it apart from the shape-similarity pass without opening either schema.

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

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

Explicit positioning: 'First step of cross-pillar investigation' and 'the cheap deterministic cut that pares the candidate set before the more expensive shape-similarity pass', with a direct compose-with instruction. The agent knows both when to use it and what to call next, and the phrase 'no Pearson, no tier, no causal framing' rules out the things this tool is not for.

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, idempotent, and openWorld behavior. The description adds valuable provenance: it is a customer-owned S3 bucket, the data is filtered by a cap-CSV the MCP wrote, and only action=offload patterns appear here. It does not discuss auth or rate limits, but it meaningfully extends what the annotations provide.

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

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

The description is three tightly written sentences with no filler. It moves from return contents to filtering/routing, then to the maintenance-loop usage pattern and the downstream retriever_query alternative.

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

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

With an output schema present and rich annotations, the description does not need to explain return values. It completely covers what the tool shows, when to call it, what it excludes, and where to go for raw events, leaving no material gap for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters, including the view const, limit behavior, service filter, timeRange enum, and environment. The description does not add syntax or format details beyond the schema, so the baseline of 3 is appropriate.

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

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

The description names a specific resource (customer-owned offload S3 bucket contents view) and enumerates exactly what it returns: per-pattern bytes, event count, first/last seen, and growth rate. It also distinguishes the tool from sibling data paths by noting that drop, compact, and tier_down patterns are not in this S3 overflow view.

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 frames the tool as the maintenance-loop review for 'what's accumulating in my overflow queue?' and routes the agent to log10x_retriever_query when offloaded events are needed for an incident or audit. It also states what is excluded and where those excluded actions route, giving clear when-to-use and when-not-to-use 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 cover the safety profile (readOnly, idempotent, openWorld), and the description layers on behavior they cannot express: the stack round-trip that include_samples controls, the fact that output is deliberately truncated (12 rows, 72 chars, top 8 services, 5 samples at 120 chars), and the projection semantics of monthly_volume_gb including the volume_actual_gb vs volume_projected_gb envelope stamp. This is real disclosure beyond 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?

Front-loaded with the call trigger and purpose, then the payload, then the required input and routing. Most sentences earn their place, but the chart-dimension minutiae ('72 chars wide', '120 chars each') is cosmetic detail that competes with the routing information an agent actually 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?

An output schema exists, so explaining return contents was optional, yet the workflow routing and the must_ask_user/actions contract are exactly what an agent needs and are present. The one gap is that it asserts 'Requires pattern_hash' while the schema marks zero required parameters and offers pattern as an equivalent alias — a minor inconsistency that could mislead an agent about hard requirements.

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 is already documented, including the pattern/pattern_hash precedence and the projection caveat. The description restates the pattern_hash sourcing (tenx_hash from preview_filter.data.patterns[]) and little else about the remaining params (timeRange, environment, include_samples), so it sits at the baseline for a fully-covered schema.

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

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

States a specific verb and resource ('Returns a full single-pattern view') and enumerates the concrete payload: 24h line chart, cross-service bar chart, severity breakdown, sample events. It also names its position in the workflow relative to log10x_preview_filter, so an agent can distinguish it from pattern_trend, pattern_examples, and pattern_diff 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?

Explicit trigger ('CALL THIS AFTER log10x_preview_filter when the user drills into a specific pattern by number') plus named alternatives for both directions: log10x_preview_filter (back) and log10x_configure_engine (apply). It even specifies the must_ask_user prompt, so the agent knows the required interaction loop, not just when to call.

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