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

Goes well beyond the annotations (readOnlyHint/idempotentHint/openWorldHint) by disclosing cross-turn session state ('merges new args into the session and ... remembering each answer across turns'), the plan-only contract ('emits helm commands + values.yaml; the user runs them'), license acquisition paths, the demo+airgapped downgrade warning, and 'Tier prerequisites: none.' These are behavioral facts the annotations cannot convey.

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

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

Front-loaded: purpose and the routing rule occupy the first two sentences. However it is a dense, long block with heavy parenthetical asides, and several schema-level details are restated, so it is efficient rather than tight.

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

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

For an 11-param, nested-object, stateful wizard with an output schema, the description covers the full decision flow, session semantics, prerequisites, and license paths. Since an output schema exists, no return-value explanation is needed, and nothing an agent needs to call 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 coverage is 100%, so the baseline is 3, but the description adds flow-level meaning the schema does not: the five-decision ordering, which decisions are auto-answered vs asked, the multi-destination example for backends, and the airgapped/log10x mutual exclusion. Useful added context without contradicting the schema.

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

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

States a specific verb+resource up front ('Progressive install wizard for the Log10x Reporter / Receiver on Kubernetes') and explicitly positions itself against siblings: 'This is the SINGLE entry point for installs — call it first,' and names the tools it is not (log10x_doctor, log10x_login_status). An agent can discriminate this from the other ~50 log10x siblings without opening the schema.

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

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

Gives explicit when-to-use ('call it first'), explicit when-NOT-to-use ('Do NOT call log10x_doctor or log10x_login_status as a pre-flight'), and names the alternative flow when sign-in is needed (chain through log10x_signin_start then re-invoke). It even explains why the exclusion exists (doctor warnings confuse users). Nothing is left to inference.

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

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

Annotations cover the safety profile (readOnly, idempotent, closed-world), yet the description adds substantial behavioral disclosure: the standalone workload set, S3/SQS dependency, fail-closed preflight when AWS infra is absent, the specific verify probes, and the fact that teardown leaves Terraform-managed infra untouched.

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, leading with the action and contrast to siblings before detailing behavior. The single-paragraph block is long, though nearly every sentence carries distinct information (preflight, verify, teardown semantics).

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 15-parameter tool with an output schema, the description supplies the behavioral context an agent needs — preflight conditions, verify probes, and teardown scope — without redundantly explaining return values. Nothing critical 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 parameters are already richly documented in the schema (infra_mode auto-detection, license_source modes, SQS queue outputs). The description adds only the general 'accepts explicit overrides' notion, 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 ('produce an install/verify/teardown plan') and resource ('Log10x Retriever'), and explicitly contrasts itself with the Reporter + Receiver topological option. An agent can distinguish this from log10x_advise_install and the retriever query/probe siblings 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?

Clearly establishes the input context ('Given a DiscoverySnapshot from log10x_discover_env') and the override path, and notes preflight fails closed. However, it does not explicitly route between this tool and the sibling log10x_advise_install, leaving that alternative 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 readOnlyHint/idempotent/openWorld, so the bar is lower, yet the description adds real behavior: default 7d Reporter window, coverage-stability and anomaly gates, and the failure contract (structured `not_ready` listing which gates failed). It doesn't specify latency or gate-combination logic, keeping it at a strong 4.

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 front-loaded sentences: role first, then what it verifies, then the return contract. No redundant restatement of the name or title, and every sentence earns its place.

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

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

With an output schema present, the description needn't explain return values, and it nonetheless names the key `not_ready` outcome. Combined with the rich param schema, an agent has enough to invoke it correctly; only minor gate-interaction detail is absent.

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

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

Schema description coverage is 100%, so the schema already documents every parameter richly (horizon calibration, coverage gate threshold, projection semantics). The description body adds no parameter-level detail beyond 'default 7d,' so the baseline 3 applies.

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

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

States a specific verb and resource set ('Verifies Reporter age, pattern-coverage stability, absence of acute anomalies') and frames its role precisely as a 'pre-flight readiness gate.' It distinguishes itself from siblings by naming the downstream tools it gates (configure_engine / estimate_savings).

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

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

Clear context: run this before configure_engine / estimate_savings. However, it stops short of explicit when-not conditions (e.g., what to do if already run, or how it relates to sibling readiness tools like dependency_check or env_validate).

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

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

Annotations already declare readOnlyHint/idempotentHint/openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: a Bayesian Beta(2,2) prior is applied to savings estimates, output is a markdown summary meant for sharing, and it fails without a prior commitment record.

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

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

Three sentences, zero padding, with the tool's identity and the critical precondition front-loaded ahead of the methodology note.

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

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

A read-only aggregate with 100% schema coverage and an output schema does not need return-value explanation, and the description supplies the key dependency and rendering method. Only the absence of alternative routing when no commitment exists keeps it from being fully complete.

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

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

Schema description coverage is 100%, so the enum semantics for format and period plus the service/commitment_id precedence are already documented in the schema. The description only alludes to markdown/weekly rendering and adds no syntax or default details beyond what the schema provides.

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

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

States a specific verb+resource (weekly aggregate report against a commitment record), plus audience and cadence, so an agent can distinguish it from savings/estimate_savings siblings 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 ('REQUIRES a commitment record opened by a prior configure_engine apply') and the consequence when it is absent. It never names an alternative tool (e.g. log10x_savings, log10x_estimate_savings) to route to when no commitment exists, so it stops short of full when/when-not guidance.

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

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

Annotations establish the mutation/idempotency profile, and the description adds substantial context beyond them: the pinned output folder enabling cheap re-runs, the daemonless podman pull with automatic --cap-add SYS_ADMIN, the mandatory GitHub token even for public repos, the not_configured failure mode, and the flavor gating that refuses runtime builds. This is 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 text is long but dense and front-loaded with the inline-wait behavior before drilling into sources and prerequisites; almost every clause carries distinct information. It is slightly repetitive in restating the re-run/pinned-output behavior across the description and the max_wait_ms schema entry, which keeps it from a 5.

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

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

For a 23-parameter tool with an output schema, the description covers the operation model, source combinations, credential requirements, execution backends, flavor constraints, and failure modes (not_configured, refused runtime). Nothing an agent needs to invoke it correctly is missing, and return values are appropriately 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 description coverage is 100%, so the baseline is 3, and every parameter is already well documented in the schema. The description still adds cross-parameter semantics the schema does not: how sources combine freely, that github_token doubles as the source-repo credential for docker_images, and that max_wait_ms:0 means fire-and-forget.

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 ('Compile a symbol library from any mix of sources') and enumerates the source types it accepts. It is clearly distinguishable from siblings log10x_compile_status (polling) and log10x_compile_link (linking), and the output artifacts are named.

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 describes the inline-vs-async decision: small compiles and every re-run finish within max_wait_ms and return in one call, while a long first compile returns a job_id to poll with log10x_compile_status or by re-calling this tool. It also states prerequisites and exclusions (GitHub token required, runtime flavors refused, .jar not scanned directly).

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

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

Goes well beyond the annotations (readOnlyHint=false, idempotentHint=true) by disclosing that no source is mounted, 0 new files are scanned, the .10x.tar is written into the same units folder, the inline wait default and fallback job_id behavior, and that the native runtime build is refused. These are real operational traits an agent needs.

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

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

Front-loaded with the core action and the key differentiator (no source scan) in the first sentence, then usage, then preconditions. It is long and the flavor-rename parenthetical is dense, but every block carries load-bearing 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 hybrid-timing tool that may return a library directly or a job_id, the description supplies the exact wait semantics, the poll destination, and execution-flavor constraints. An output schema exists, and the description still adds the return-mode distinction without redundant return-shape detail.

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 value beyond the schema: recursive traversal of units_path, the same-folder write location of the library, the 45s inline wait that 'normally returns the linked library in ONE call', and sanitization of library_name. Some params (timeout_ms, mode flavors) are only lightly touched in prose.

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 ('Link an existing folder of .10x.json symbol units ... into a single .10x.tar library') and immediately scopes it against the sibling compile: 'with NO source scan'. An agent can distinguish this from log10x_compile 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?

Explicitly names three when-to-use scenarios (re-link after pruning units, assemble a piecemeal units tree, rebuild from a prior compile's output folder) and routes polling to log10x_compile_status. The compiler-flavor requirement is stated as a hard precondition with the accepted spellings.

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 the read-only/idempotent/non-destructive profile, and the description adds substantial lifecycle detail beyond that: the first terminal poll captures the exit code and frees the container, later polls stay readable, the compiled library is never removed, and behavior degrades to unit counts + log tail on an older engine image. This is exactly the extra context 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?

Dense but front-loaded: the polling action and job_id keying come first, then the returned fields, then the degradation caveat. Every sentence carries substance, though the diagnostics/return-value enumeration is heavier than strictly needed given an output schema exists.

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 async status poller with an output schema, full schema coverage, and rich annotations, the description fills the remaining gaps (lifecycle, degradation, diagnostics promotion) so an agent can call and interpret 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 schema already documents job_id, view, and log_lines (including the 'raise it when diagnosing a failed run' hint). The description restates the job_id origin but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (poll), resource (asynchronous compile), and names the two siblings that produce the job (log10x_compile and log10x_compile_link). An agent can distinguish this status poller from the retriever_query_status sibling and from the compile launchers without opening any schema.

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

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

Clearly establishes the usage context: call it to poll a job started by log10x_compile or log10x_compile_link, keyed by job_id. It does not explicitly name a competing status tool or say when-not to use it, but the precondition 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 cover read-only/idempotent/open-world, but the description adds substantive behavior beyond them: tier-dependent menu collapse (6 vs 2 entries), capability gating by receiver tier/SIEM/offload bucket, and envelope semantics (must_render_verbatim, must_ask_user, forbidden_next_actions). These are non-obvious operational traits an agent needs.

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

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

Front-loaded with the trigger condition and packed with routing rules; every sentence conveys operational detail. It is dense rather than bloated, though some clauses overlap with the schema descriptions, preventing a 5.

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

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

For a menu-generating routing tool with an output schema present, the description supplies everything needed: entry conditions, tier-dependent output, envelope fields, and downstream routing. 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%, so the schema carries the parameter burden, and the description largely restates it (e.g., siem_lens provenance stamping and destination forwarding are already in the schema). It adds narrative value by explaining how parameters survive the hop into routes_to.args, but this is marginal over the schema text, so baseline 3 applies.

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

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

The description names a specific action (return the cost-reduction option menu) and clearly distinguishes it from siblings by stating it produces a mode menu that routes to log10x_explain_mode rather than performing the estimation itself. It also specifies tier-dependent output shape (6-mode vs 2-entry), making the tool's identity unmistakable.

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

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

Explicitly states the trigger condition ('CALL THIS after the user picks ... from log10x_start') and the downstream routing ('All non-observe modes route to log10x_explain_mode'). It also names forbidden next actions (do not call estimate_savings, configure_engine, or pattern_mitigate until the user picks), which is unusually precise guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds real context beyond that: it discloses the return shape (raw Prometheus response plus backend metadata) and the env-var-configured backend target. It stops short of noting auth requirements or rate limits.

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

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

Front-loaded with the core purpose, then usage framing, then the alternative. Every sentence carries information, though the piece is on the longer side for a passthrough tool.

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

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

For a five-parameter passthrough tool with an output schema, the description covers purpose, backend resolution, return shape, correct usage cases and the alternative workflow. Nothing an agent needs in order to choose or call it is missing.

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

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

Schema description coverage is 100% and the schema already documents mode, start, end, step and promql with examples. The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource: a low-level PromQL passthrough to the customer metric backend. It explicitly positions itself against siblings by calling itself 'the escape hatch' and naming the deterministic primitive chain it is not.

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 an explicit alternative path (`log10x_metrics_that_moved` → `log10x_rank_by_shape_similarity` → `log10x_metric_overlay`) 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=true, openWorldHint=false, idempotentHint=true, so the description doesn't need to re-litigate safety. It adds non-obvious behavior: the blast-radius semantics, that deleting a log line can silently break an alert, and (in schema) ambiguous-vendor errors and in-process vs bash-command fallback. The ambiguous-error and fallback behavior is documented in the schema rather than the description, so not a full 5.

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

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

Front-loads the core action, then the mandatory pre-condition, then example developer questions and the framing payoff. Every sentence earns its place. Slightly dense but not 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?

An output schema exists, so return values needn't be explained. The description covers purpose, trigger conditions, and consequence, and the schema covers vendor resolution behavior. Complete enough for an agent to select and invoke correctly; minor gap is that the ambiguous-error case lives only in the schema.

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

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

Schema coverage is 100% and the vendor parameter carries a rich description (auto-detection rules, ambiguity error, in-process vs command fallback). The description itself contributes pattern-identity scoping but no per-parameter detail. 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 (scan/generate commands) and resource (SIEM/observability stack for dependencies on a pattern), and enumerates the target surfaces (Datadog monitors, Splunk saved searches, Grafana dashboards, Prometheus alert rules). This clearly distinguishes it from siblings like log10x_pattern_mitigate or log10x_pattern_detail.

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

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

Explicitly gates usage: 'Call this before any mute, drop, or source-code deletion' and gives developer-phrased triggers ('am I allowed to delete this log.info() call'). Names the consequence of skipping it, which is exactly the when-to-use/when-not guidance an agent needs.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses what is probed (kubectl workloads, IRSA annotations, AWS EKS/S3/SQS/CloudWatch), that shell calls are logged in probeLog for audit, that only get/describe/list verbs are used, a 30-min cache producing snapshot_id, and that no tier prerequisites apply. This is substantial context the annotations alone do not 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?

Long but front-loaded and information-dense: the core purpose leads, followed by when-to-use, when-not-to-use, then capabilities. The bolding aids scanning, though some routing detail is repeated across the middle section, keeping it just short of maximally tight.

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

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

An output schema exists, so return values need no exposition. For a zero-required-param discovery tool the description covers purpose, routing, safety profile, caching, and audit behavior — everything an agent needs to invoke it correctly.

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

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

Schema description coverage is 100%, so all eight parameters are already documented with defaults and semantics. The description adds no per-parameter syntax or override guidance beyond what the schema provides. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (read-only discovery/probe) and resource (caller's Kubernetes cluster + AWS account infrastructure), and explicitly disambiguates from the similarly-named Log10x ACCOUNT environment concept. An agent can tell it apart 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 routing: call FIRST when the user wants to install Log10x, then log10x_advise_install, and explicitly names tools NOT to call beforehand (log10x_doctor, log10x_login_status, log10x_savings). Also names the alternative for account-env questions. Nothing is left to inference.

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

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

Beyond the readOnly/openWorld/idempotent annotations, it discloses the session caching keyed by (environment, endpoint), reuse semantics across primitives, threshold behavior (0.7 primary / 0.5 runner-ups), and the exact fallback shape (`no_join_available` with probed-label matrix). This is rich context the annotations cannot convey.

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

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

Front-loads what the tool does, then the caching model, then the routing guidance, then the no-join fallback. Every sentence carries information, though the description is on the longer side for a tool that agents are told not to call directly.

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

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

Given an output schema exists, return values need not be explained, yet the description still characterizes the no-join fallback. Together with the caching and routing guidance, an agent has everything needed to decide whether and how to invoke it.

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

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

With 100% schema coverage the parameter documentation is already thorough, so the baseline is 3; the description adds value by naming the caching key (environment, customer-backend-endpoint) and restating the threshold semantics that tie parameters to behavior. It does not add much syntactic detail beyond the schema, keeping it from 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?

States a specific verb+resource ('auto-discover the structural join label') and explains the mechanism (Jaccard similarity on label value sets). It is clearly distinguishable from the sibling log10x_discover_labels, which handles label discovery rather than cross-pillar join resolution.

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

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

Explicitly tells the agent 'normally NOT need to call this tool directly' because the primitives (metrics_that_moved, rank_by_shape_similarity, metric_overlay) call it internally, and reserves direct use for power users wanting to inspect the join universe or force re-discovery. This is clear when-to-use, when-not-to-use, and who-else-uses-it guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so safety and idempotence are covered. The description adds the dual-mode behavior (list vs. distinct values) and the session-startup role, but says nothing about value cardinality beyond the schema's limit cap or pagination behavior; with an output schema present, that omission is minor.

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; the resource definition is front-loaded, the usage trigger follows, and the motivating example closes. No filler or repetition.

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

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

Zero required parameters, a full output schema, and complete annotations mean the agent needs nothing else. The description covers purpose, timing, and both invocation modes, which is everything a discovery tool of this shape requires.

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

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

Schema description coverage is 100%, so all three parameters are already documented in detail. The description's 'pass a label name to get its distinct values' largely restates the label property's own schema text, so it adds framing rather than new semantics. 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 ('List') and resource ('labels Log10x metrics can be filtered or grouped by'), plus the second operating mode ('pass a label name to get its distinct values'). An agent immediately understands the resource is label metadata, distinguishing it from sibling tools like log10x_discover_env or log10x_services.

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 prescribes when to call it: 'at the start of a session, or before calling any tool that takes a label/filter argument.' It also gives the concrete failure mode it prevents (guessing 'namespace' when the real name is 'k8s_namespace'), which is the strongest possible justification for the timing guidance.

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

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

Annotations already declare readOnly/idempotent/openWorld, so the safety profile is covered; the description adds the return shape (markdown report with pass/warn/fail and remediation hints) and conditional behavior (cross-pillar enrichment floor only when LOG10X_CUSTOMER_METRICS_URL is set). It stops short of describing what happens for informational vs failing probes or any partial-failure behavior.

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

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

The purpose is front-loaded in the first sentence and each clause earns its place via concrete probe names. The probe enumeration is dense and slightly list-heavy, but no sentence is redundant.

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

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

For a diagnostic tool with an output schema and full annotation coverage, the description supplies everything an agent needs: what it probes, when to call it, the result format, and conditional behavior tied to an env var. Nothing required 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 single `environment` parameter (omit for all environments, pass a nickname for one) is already fully documented in the schema. The description adds nothing about the parameter, so the baseline of 3 is correct.

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

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

The description gives a specific verb+resource ("Run a startup health check on the Log10x MCP installation") and enumerates the exact probes it performs, so the scope is unambiguous. It does not explicitly name or differentiate itself from overlapping siblings like log10x_env_validate or log10x_dependency_check, which is the only gap keeping it below 5.

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

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

It states clear when-to-use conditions: "once at the start of a session" and after any unexpected tool error to isolate configuration problems. It does not name when NOT to use it or point at specific alternative diagnostic tools, so it falls short of the 5 criteria.

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

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

Goes well beyond the annotations: discloses that the server runs under `--network none`, never executes the emitted script, refuses to return a script containing a log10x hostname, writes export-sample.sh at mode 0755, and touches nothing. It also frames the readOnlyHint=true annotation explicitly ('it renders text and writes one script file; it contacts nothing'), so no hidden side effects 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?

Front-loads the core purpose and the network split before the procedural detail, and the POC step enumeration earns its length by telling the agent where this fits. It is somewhat verbose and repeats the 'same default as log10x_poc_from_siem' rationale across two params, which is minor redundancy rather than waste.

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 7-param tool with an output schema, it covers everything an agent needs: prerequisites, what it returns (script text, touched API operations/credential vars, checklist, next-call args), follow-up steps, and the unsupported analyzers with a manual workaround. Nothing required 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 already 100%, so the schema does the heavy lifting; the description adds cross-tool meaning by explaining why defaults match log10x_poc_from_siem (so both paths sample the same size) and when to lower target_event_count. That rationale is genuinely beyond the schema, though much of the per-arg text restates enum/default facts already documented.

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: 'Render a read-only shell script that exports a log sample.' It immediately names its scope (user's own analyzer, own credentials, chosen machine) and explicitly distinguishes itself from siblings log10x_poc_from_local and log10x_poc_from_siem, so an agent can route correctly 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: step 2 of the fenced POC (with steps 1, 3, 4 enumerated) and whenever credentials live somewhere the process cannot reach. It also states what it does NOT do (does not run the script, contacts nothing) and points at the alternative path for credentialed sampling, 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 the safety profile (readOnly, idempotent), yet the description adds substantial behavior: resolver precedence, the silent-override failure mode, the per-field return shape, and the pure-on-prem edge case returning ok:true with an empty diff. That is well beyond what structured fields 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 the purpose, then the trigger condition, then args and return shape. It is dense but nearly every sentence carries distinct information; the field-list enumeration of disagreeing fields is the only mildly padded part.

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

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

With an output schema present, the description need not explain return values, yet it still enumerates the diff fields and remediation guidance. Combined with the precedence rule and edge case, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100% and there is a single parameter, so the schema already documents env_id as a UUID or nickname resolved through the store chain. The description merely restates that env_id is required and accepts a UUID or nickname, adding no new syntax or edge-case detail.

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 both operands: it compares the stored env-config document against the LOG10X_* environment variables the env-var bridge would produce, and reports per-field disagreements. This is clearly distinguishable from nearby siblings like log10x_env_validate or log10x_discover_env.

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 triggering condition: '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 explains the underlying rule (on-prem store wins per resolver precedence) that makes this tool the right one in that situation.

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

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

Annotations already establish readOnlyHint/idempotent, but the description adds what the annotations cannot: each finding carries severity (error/warning/info) with a remediation, and errors block downstream actions while warnings/info only surface. It also describes the specific cross-field rules checked, which is meaningful behavioral context beyond the schema.

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

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

Front-loads the action and the call-timing guidance, then the return shape and the enumerated checks. Dense but each clause carries information; the long findings enumeration is justified by the breadth of checks, though a bulleted form would scan faster.

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

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

Covers purpose, trigger conditions, parameter requirement, and the full breadth of validation findings with severity semantics. Return values are additionally backed by an output schema, so nothing an agent needs to invoke and interpret this tool is missing.

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

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

Schema description coverage is 100% for the single env_id parameter, including the UUID-or-nickname resolution chain. The description restates 'env_id (required — env_id UUID or nickname)' without adding syntax or format beyond what the schema already 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 (validate) and resource (stored env-config document at a concrete path), and enumerates the exact checks performed (schema parse plus cross-field sanity). An agent can distinguish it from siblings such as log10x_doctor or log10x_env_diff_vs_envvars without reading either schema.

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

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

Explicitly states when to call it: 'after any edit to the env doc (via log10x_dest_set / hand-edit / restore) or pre-flight before downstream tools that need a coherent config', naming concrete downstream consumers (commitment_report, configure_engine, offload-recipe emitters).

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

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

Annotations only declare readOnly/idempotent/openWorld=false; the description adds substantial behavior beyond them: null dollar fields rather than fabricated rates, the rate_source enum (list_price | customer_supplied | unset), siem_actual vs siem_lens provenance stamping, volume_actual_gb vs volume_projected_gb scale-factor stamping, and the tier prerequisite. This is exactly the extra context an agent needs for correct invocation.

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

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

Front-loads the session-routing caveat, then purpose, then mode details and prerequisites — a sound order. It is dense for a 30-parameter tool but some phrasing repeats (the dollar-overlay/null-rate point is made multiple times), so it is not maximally tight.

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

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

With an output schema present, return values need not be described, and the description instead covers what the schema cannot: mode semantics, the routing prerequisite, the tier requirement, unsafe-default behavior (allow_lossy opt-in, no fabricated dollar numbers), and envelope provenance fields. Complete for a tool of this complexity.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema on the two modes, the effective_ingest_per_gb rate-override contract, siem_lens provenance, and the Reporter-tier prerequisite that gates the tool. It does not attempt to re-explain all 30 params, which is appropriate given the schema already does that.

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

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

States a specific verb+resource ('Two-mode savings estimator with percent-first reporting and a dollar overlay') and then decomposes both modes precisely: forecast projects bytes_in -> bytes_out and percent reduction; verify counts realized savings over a window. It explicitly distinguishes itself from siblings by naming log10x_poc_from_local, log10x_poc_from_siem_submit, and log10x_start as the correct tools in other situations.

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/when-not routing: 'if this is the user first cost question of the session, call log10x_start first' and 'Before anything is deployed, use log10x_poc_from_local or log10x_poc_from_siem_submit instead.' It also states the precondition (REQUIRES Reporter-tier cost attribution) and the mode-selection rule (forecast for proposed policy, verify for deployed policy).

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 (readOnly/openWorld/idempotent), so the description carries the rest and does: it discloses the matching is structural rather than byte-exact (timestamps/IDs collapse to one identity), the offload disposition comes from the Reporter `routeState` label, cost fields only populate when $/GB is set, and that a no-match should be reported honestly.

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 identity-resolution purpose before the return payload and the call-first guidance, and every clause maps to a real behavior. The long enumeration of returned fields is dense but it is the part that differentiates this tool, so it 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?

For a 9-parameter, zero-required tool with full schema coverage, an output schema, and annotations, the description supplies the remaining decision-relevant context: when to call it, when not to, the structural-match caveat, and the honesty requirement on no-match.

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

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

Schema coverage is 100% and the schema itself already documents aliasing (tenxHash/pattern_hash), the cost-rate source semantics, and the siemScope default, so the description adds little beyond repeating 'cost overlay when $/GB is set'. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource (resolve a raw log line or pattern name to a stable pattern identity) and enumerates the returned payload, so the agent knows exactly what comes back. It also names the sibling it is not (log10x_resolve_batch), making the split unambiguous.

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

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

Explicit trigger conditions: 'Call this first' when a user pastes a SINGLE log line and asks 'what is this', 'is this new', 'is this safe to drop', or 'is this being dropped'. It then names the exclusion case (MULTIPLE events, SIEM dump, batch triage) and routes to log10x_resolve_batch.

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

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

Goes well beyond the readOnly/idempotent annotations by disclosing runtime contract details: must_render_verbatim (plain-text card, no markdown), must_ask_user (Apply/Preview), and forbidden_next_actions that lock apply tools and log10x_preview_filter until the user chooses. This tells the agent exactly how to render and gate the response, which the annotations cannot convey.

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

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

Front-loaded with the trigger condition and core purpose, and every sentence carries routing or rendering information. It is very dense in a single long second sentence, which slightly taxes readability but wastes no words.

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

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

For a coordination tool in a multi-step flow, the description covers preconditions, expected output shape, user-gating, and post-call routing to both apply and preview paths. Despite an output schema existing, the extra contract detail makes the tool fully actionable.

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

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

Schema coverage is 100% and the schema already richly documents every parameter, including the full mode enum definitions. The description adds only the routing-shaped { service, mode } usage for preview, so with structured data doing the heavy lifting this sits at the baseline.

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

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

States a specific verb+resource ('Explains the chosen enforcement mode') and enumerates the exact modes it covers. It also names the sibling it must follow (log10x_cost_options) and the siblings it routes to (log10x_configure_engine, log10x_preview_filter), so an agent can distinguish it from those 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?

Explicit sequencing: 'CALL THIS AFTER log10x_cost_options when the user picks a mode.' It also specifies downstream routing per mode (apply for non-observe, null for observe_only, preview always), giving clear when-to-use and what-follows 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 safety (readOnlyHint, idempotentHint), and the description adds substantial operational context: it runs in-process on the host, requires the tenx binary on PATH or Docker via LOG10X_TENX_MODE=docker, and warns that log10x_doctor does not preflight the engine. It stops short of describing failure modes or rate/scale limits, so it lands just below the top mark.

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 mechanism, then use cases, then validation mode, then prerequisites. Dense and well-organized, though the baroque bolding and backtick-heavy formatting make it longer than strictly necessary for an agent to parse the core contract.

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 little prose, yet the description still names the returned fields and covers the prerequisite engine setup, the sibling relationship, and the validation variant. For a 7-parameter tool with a nested expected object, 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% so the baseline is 3, but the description adds real meaning: it explains the validation assertion trio (expected.min_templates, required_patterns, forbidden_merges) and their PASS/FAIL output, plus the view=summary envelope contents. That is genuine value beyond 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 — 'Extract the structural template library from a log corpus' — and immediately narrows the mechanism ('RUNNING A LOCAL LOG10X PIPELINE'). It explicitly differentiates from the sibling log10x_resolve_batch, so an agent can route between them 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 (bootstrapping a catalog, offline auditing, validating config changes) plus a named companion/alternative tool. It also states what is NOT required (Kubernetes, Reporter, account), which removes a false blocker an agent might otherwise assume.

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, closed-world), yet the description adds real behavioral context: thresholds are hand-picked and tagged `unvalidated_default`, and the envelope surfaces `observed_dominant_pct_distribution` so the agent can calibrate. It also references a docs contract for agent behavior. It does not describe output shape in detail, but the output schema exists to carry that.

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 definition and the example before the differentiation and calibration caveats. Dense but each sentence carries substantive information; the embedded quote and markdown formatting add mild length without much waste.

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

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

Covers the technique, its scope relative to alternatives, the Stage 1 input constraint, and the calibration caveat, while an output schema already documents return values. An agent has enough to select and invoke it correctly without opening sibling tools.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by framing min_concentration (0.6) and sample_n (1/10) as unvalidated calibration defaults and telling the agent to compare 0.6 against the observed distribution before trusting it. That interpretive guidance is not present in the schema.

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

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

States a specific verb and resource ('identify patterns where one slot value dominates the field') and immediately grounds it with a concrete example threshold (>= 60%). It explicitly distinguishes itself from analyzer field histograms by explaining that dominance is measured within per-pattern field-sets, which an agent cannot infer from the name alone.

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

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

Gives a clear use context (surfacing sampling opportunities to save volume) and differentiates against the closest conceptual alternative (analyzer field histograms). It also flags the Stage 1 constraint of accepting a paste array. It stops short of stating when NOT to use it versus siblings like log10x_top_patterns or log10x_estimate_savings, so it is not a full 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 cover only safety/idempotency, but the description goes well beyond them: it discloses the dual report shapes (acute chain vs. drift cohort), the mechanical confidence decomposition sub-scores, per-pattern offload_status states, and mode auto-detection from input. This is rich behavioral context an agent could not infer from structured fields.

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

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

Purpose is front-loaded in the first sentence, and most sentences carry distinct information (report shapes, confidence math, trigger phrases). It runs long and includes agent-facing render instructions ('show the entire markdown report...') that could arguably live outside a tool description.

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

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

With an output schema present, the description needn't enumerate return fields, and it still conveys the two report shapes, confidence decomposition, and offload_status semantics. For a 7-parameter, mode-switching tool, an agent has everything needed to call and interpret it.

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 already 100%, so the baseline is 3, but the description adds real semantic value: starting_point should be the user's words verbatim and the tool auto-detects whether it is a log line, pattern ID, service, or 'environment'. The other parameters (depth, window, baseline_offset) are left to the schema.

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

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

States a specific verb and resource ('root-cause investigation') with explicit scope ('any log line, pattern, service, or environment') and a named output ('causal chain' or 'co-drifter cohort'). This lets an agent distinguish it from siblings like log10x_pattern_trend or log10x_top_patterns 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?

Provides concrete trigger phrases ('what is going on with X', 'why is X spiking', pasted log lines) that map directly to invocation contexts. However, it never names an alternative tool or states when NOT to use it (e.g., versus top_patterns or pattern_trend), so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false, so the safety profile is covered. The description adds information the annotations cannot: mode-dependent behavior (demo mode with no key or failed validation returns a step-by-step config guide; signed-in mode returns identity, reachable envs with OWNER/WRITE/READ permissions, default env, and session-most-recent env). That is genuine behavioral 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 core purpose in the first sentence, then routes. The bolded phrasing lists are long but each entry is a real disambiguation trigger rather than filler, so the length is largely earned; a slight deduction for the density of emphasis and repeated tool names.

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

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

An output schema exists, so return shape need not be restated, and annotations cover the safety profile. What remains — the two operating modes and which sibling tools handle the authentication path — is fully covered, leaving nothing an agent needs missing.

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

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

Zero parameters, so the baseline is 4. The description confirms 'takes no args', which is consistent with the empty schema and useful confirmation for an agent deciding whether it needs to gather inputs first, though it adds little beyond what the empty schema already implies.

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 user's Log10x ACCOUNT environments and report credential / login state') and immediately scopes it against siblings by naming log10x_signin_start, log10x_signin_complete, and log10x_discover_env with the reason discover_env is unrelated. An agent can identify this tool and its boundary 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?

Provides explicit routing: an enumerated list of user phrasings that must map to this tool ('which environments do I have', 'am I logged in', 'switch envs') and a separate enumerated list for when to use log10x_signin_start / log10x_signin_complete instead, plus an explicit 'Do NOT call log10x_discover_env' exclusion with rationale. This is about as complete as when/when-not guidance gets.

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 readOnlyHint/idempotentHint annotations, it discloses hard prerequisites (tenx CLI on PATH or LOG10X_TENX_PATH, Docker mode, SIEM credentials), the data-provenance chain, and confidence tiers keyed to event counts (high >=50, medium 10-49, low <10). This is exactly the behavioral context annotations cannot convey.

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

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

Front-loaded with the core action and value, and most sentences earn their place. There is some redundancy, however, as the local-engine requirement is effectively stated twice ('Requires: tenx CLI installed locally...' and 'REQUIRES a local engine: the tenx binary on PATH, or Docker...').

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?

Because an output schema exists, return values needn't be explained, and the description still covers the full operational picture: prerequisites, environment scoping, confidence behavior, and integration with downstream savings tools. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning: it ties sample_size to confidence quality ('high confidence requires >=50 events per pattern') and explains the cost tradeoff of larger samples. It also frames timeRange as the measurement window, going beyond the schema's format description.

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 ('Measure real per-pattern compaction ratios from a SIEM sample') and explains the mechanism (pulls events, runs through local tenx engine, returns compaction_ratio_x). It explicitly differentiates from siblings by naming log10x_estimate_savings and log10x_pattern_detail as the tools whose generic estimates it replaces.

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

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

It gives explicit routing: 'Use this to replace generic 5-10x estimates in log10x_estimate_savings and log10x_pattern_detail with measured values for this customer environment.' Prerequisites and the downstream flow into log10x_estimate_savings are stated, leaving little to inference.

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

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

Annotations already declare readOnlyHint/openWorldHint/idempotentHint, so the safety profile is covered. The description adds real behavioral context beyond that: bucket size is auto-selected from window length and both series are right-aligned to the same trailing grid so a sparse anchor and dense candidate compare on the same chaos window. It doesn't discuss truncation/cost limits explicitly, but that is covered by max_buckets in the schema.

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

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

Front-loaded with the step's role in the investigation flow, then output facts, then the exclusion ('No Pearson, no tier'), then usage. Every sentence carries signal. Slightly dense, but no filler sentences.

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 12-parameter, multi-backend tool the description conveys the return shape, alignment mechanics, and single-suspect usage pattern; an output schema exists so return values need not be fully re-explained. It is complete enough for correct invocation, though auth/backend override parameters are left to schema.

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

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

Schema description coverage is 83%, so most parameters are already documented. The description nonetheless adds cross-parameter meaning the schema lacks: bucket size auto-selection from window length and the shared right-alignment grid. It also reinforces the single-candidate design, which the schema hints at only via 'candidates[0]'.

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 ('return aligned anchor + candidate timeseries plus deterministic facts'), names the concrete outputs and explicitly what it is not ('No Pearson, no tier — pure raw data'). This cleanly distinguishes it from the sibling log10x_rank_by_shape_similarity without needing to open 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: '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.' The alternative and the sequencing condition are both named, 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?

The description adds substantial behavioral detail beyond the annotations: it explains the median-rate phase partitioning, the ≥15% gap rule, the returned arrays (`moved[]`, `not_moved[]`, `evaluation_failed[]`), and explicitly states what it does not do ('no Pearson, no tier, no causal framing'). The annotations already cover read-only/idempotent safety, and the description does not contradict them.

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

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

The description is front-loaded with the purpose and workflow role, then adds algorithm and return details. It is dense but largely earns its space; the only minor redundancy is the repeated emphasis on 'deterministic' and 'cheap' across two sentences.

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 complex 11-parameter tool with an output schema and rich annotations, the description supplies the investigation context, algorithm, outputs, and composition guidance an agent needs. It does not need to re-explain return values because an output schema exists, but it still orients the caller 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?

With 64% schema coverage, the schema carries much of the parameter detail, but the description adds conceptual meaning: it defines the anchor/candidate pillar relationship ('candidates are all sibling series from the OTHER pillar') and clarifies the anchor_type branches. It also implies the phase-gap-floor behavior. It does not document every parameter, but it adds value beyond the schema for the core semantics.

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

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

The description states a specific verb and resource — a deterministic filter on which customer metrics moved while an anchor was active — and distinguishes the tool from siblings by naming the expensive shape-similarity pass it precedes. An agent can identify the tool's role in cross-pillar investigation without opening the schema.

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

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

It explicitly frames the tool as the 'first step' and 'cheap deterministic cut' to use before 'the more expensive shape-similarity pass', and it names the two composition tools (`log10x_rank_by_shape_similarity`, `log10x_metric_overlay`). This gives clear when-to-use and sequencing guidance with named alternatives.

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

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

Annotations already declare readOnly, idempotent, and openWorld, so the safety profile is covered. The description adds genuine non-obvious behavior: only action=offload data is present (drop patterns are NOT in S3; compact and tier_down route elsewhere) and it is sourced from a cap-CSV the MCP wrote. It stops short of disclosing any latency or pagination caveats, but the substantive scoping insight is a real value-add.

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 resource definition before the routing guidance, with each sentence carrying distinct information (fields, filtering scope, usage framing, alternative). Slightly dense with parenthetical asides, but nothing is redundant.

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

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

An output schema exists, so return values need no explanation. Combined with annotations covering the safety profile and a description that covers scope, filtering, and routing, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the schema already documents every parameter, including the limit truncation note and timeRange equivalences. The description reinforces the offload filter but adds no syntax or semantics 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?

States a specific resource (offload S3 bucket contents) and enumerates the returned fields (per-pattern bytes, event count, time-first-seen, time-last-seen, growth rate). It also distinguishes itself from related siblings by naming log10x_retriever_query for rehydration, so an agent can route correctly 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?

Explicitly frames the when: 'Call this as the maintenance-loop review: what's accumulating in my overflow queue?' and names the alternative (log10x_retriever_query) with the condition that selects it (incident or audit needs data back in the SIEM). Nothing is left to inference.

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

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

Annotations 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.

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, openWorldHint), so the bar is lower, and the description still adds real behavioral context: how re_emerged is derived (checking first_seen against the before-window boundary), how co-emergence clusters fingerprint a deploy with default 60s window, and that an incidents block is emitted when clusters are found. It stops short of noting limits, auth, or large-window cost behavior.

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

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

The core definition and the labeled sets are front-loaded and the Scoping/Returns structure helps. But roughly a third of the text is competitive marketing ('coherent ONLY because log10x pattern_hash is stable... competitors that re-cluster per query') that does not help an agent select or invoke the tool, so several sentences do not earn their place.

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

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

For a 9-parameter tool with an output schema and read-only annotations, the description is complete: it explains usage triggers, scoping, defaults, the semantics of each returned set, and the conditions under which an incidents block appears. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters, and the description largely restates them (timeRange window pairing, limit rows-per-category, service/severity scoping). The re_emerged boundary semantics and cluster-fingerprint framing add a little meaning beyond the schema, but not enough to rise above the baseline for full coverage.

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

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

The description states a specific verb+resource+scope ('Set diff of patterns across a time boundary') and enumerates exactly what is computed: the new/retired/persistent/re_emerged sets plus co_emergence_clusters. This is unambiguous and clearly distinguishable from look-alike siblings such as log10x_pattern_trend or log10x_whats_changing, which do not produce a set diff.

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?

Concrete trigger phrases are given ('what changed since last deploy', 'which patterns disappeared this week', 'did the rollback bring back the old errors') and it names a specific companion call (log10x_pattern_examples on a flagged hash). However it never explicitly distinguishes itself from the similarly-purposed siblings log10x_whats_changing and log10x_pattern_trend, leaving that disambiguation 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 the safety profile (readOnlyHint, openWorldHint, idempotentHint), and the description goes well beyond them: SIEM phrase-search probe, local templater pass, Jaccard ≥0.85 discrimination, top-buckets-by-count ordering, explicit parseFailed markers, and head-line-only warnings for multi-line templates.

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 core action and 24h constraint come first, with alternatives and orchestration role after. Some clauses (templater-path recap, similarity threshold mechanics) are verbose, but every sentence carries operational information.

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

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

An output schema exists, so return-value detail is not required, and the description still covers partial-extraction semantics, retention limits, and the orchestration contract. For a 12-param open-world tool, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already explains view, bucket_id, timeRange, slot_filter, etc. The description restates the pattern/pattern_hash duality and the 24h cap but adds no syntax or format detail beyond what the schema provides, matching the baseline 3.

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

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

States a specific verb (pull recent live events) and resource (for a pattern), names the supported log analyzers, and explicitly distinguishes itself from log10x_retriever_query, log10x_event_lookup, and log10x_pattern_trend. An agent can identify the tool's role 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 ('orchestration primitive called by log10x_investigate when the chain needs concrete event evidence'), when-not (bounded to 24h; use log10x_retriever_query for older history), and preferred alternatives for single-line inspection.

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