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

With no annotations, the description carries the full burden and excels. It discloses the intentional U9 fix (mean subtraction/window) and why it exists ('DC leakage used to bury the low-frequency FTF zone'), states invalid bands raise ValueError and are 'NEVER silently clamped', notes the band is echoed in the result, and explains the deterministic default (leading 1.0-s segment) and random_seed behavior. Also clarifies no reference frequencies are assumed, preventing false expectations.

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 long but every sentence earns its place: algorithm, rationale, requirements, constraints, defaults, and comparison guidance. It uses a clear structure (intro, behavior, Args, Returns, Raises) and front-loads the purpose. No fluff or repetition; the 'THE unified envelope tool' line, while emphatic, reinforces its role among siblings.

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

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

The tool is complex (6 parameters, prerequisites, error conditions, segment selection) and the description covers all aspects: preconditions (signal must be loaded), constraints (band vs Nyquist), deterministic vs random behavior, no assumed bearing frequencies, and error types. The output schema exists, so it appropriately keeps return details brief ('EnvelopeResult with the band actually used, top peaks, and comparison guidance').

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 0%, so the description must fully compensate. It explains every parameter: signal_id (ID from load_signal), filter_low/filter_high (edges in Hz with defaults, Nyquist constraint), num_peaks (count of top peaks), segment_duration (duration, default leading 1.0s, None for full signal), random_seed (seed for random position, None = deterministic). It also adds error semantics for invalid values, going far beyond the bare schema.

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

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

The description states a specific verb+resource: 'Envelope-spectrum analysis of a stored signal (bearing fault screening)' and details the algorithm ('bandpass filter -> Hilbert envelope -> mean subtraction + Hann window -> FFT -> top peaks'). It clearly distinguishes itself from siblings like analyze_fft and check_bearing_faults by positioning itself as 'THE unified envelope tool' and referencing the comparison tools for subsequent analysis.

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 usage context: 'Requires the signal loaded via load_signal() first', explains when to use the tool (bearing fault screening), and gives alternative/next-step guidance: 'compare the returned peaks against frequencies computed for the actual bearing and shaft speed (check_bearing_faults or calculate_bearing_characteristic_frequencies)'. It also clarifies segment selection options and when to pass None or random_seed.

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 is rich with behavioral detail: deterministic leading-segment default, segment_duration=None for full signal, random_seed for sampling, error conditions if signal not loaded or lacks sampling rate. It also notes ctx is unused, providing logging context. This compensates for the lack of annotations.

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

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

The description is well-structured with narrative and explicit args/returns/raises sections. It is slightly redundant (e.g., default segment duration appears twice) but every section adds needed clarity.

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

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

The description covers prerequisites, parameter semantics, return value, and exceptions. Given the output schema exists and the tool has 4 params, this description is adequately complete.

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

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

The schema has no parameter descriptions (0% coverage), but the description explains every parameter's purpose, default, and special values (e.g., segment_duration=None for full signal, random_seed determinism). This fully compensates for the schema gap.

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

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

The description opens with a clear verb-resource statement: 'Perform FFT analysis on a stored signal.' It elaborates on the purpose (time to frequency domain, harmonic detection) but doesn't explicitly differentiate among sibling analysis tools like compute_spectrogram_stft.

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

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

The description states when to use it: for identifying harmonic components and faults manifesting at specific frequencies. It also specifies the prerequisite that the signal must be loaded via load_signal() first. However, it doesn't discuss alternatives or exclusion criteria, so it falls short of a 5.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does so thoroughly: it explains the statistical test (slope p < 0.05), the onset detection logic (segment after baseline, baseline mean plus threshold standard deviations), the limitation that onset inside the baseline cannot be detected, and the prerequisite of a loaded signal with sampling rate. It also discloses that ctx is unused and the error conditions that raise ValueError. This is exemplary transparency.

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 structured with a summary, methodology explanation, usage caveats, and Args/Returns/Raises sections. It is front-loaded with the core purpose. However, there is minor redundancy between the first sentence and the second ('Within-recording screening...' and 'THE unified screening tool: feature trend AND degradation onset in one call.'). Overall, it is appropriately sized for the tool's complexity, but slightly verbose.

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

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

Given the tool's complexity, the absence of annotations, and the bare schema, the description is exceptionally complete. It covers the algorithm, statistical methods, input requirements, output structure, error conditions, and usage caveats. It even explains why this is a screening tool and how to use it for RUL, leaving no significant gaps.

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

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

The schema has 0% description coverage, so the description must compensate. The Args section provides clear semantic meaning for each parameter: signal_id is the ID from load_signal, feature_name is a time-domain feature with default 'rms', segment_duration is in seconds, overlap_ratio is a 0-1 ratio, and onset_threshold_sigma is the number of standard deviations above the baseline mean. This fully compensates for the bare schema.

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

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

The description opens with a specific and informative summary: 'Within-recording screening: feature trend + degradation onset.' It clearly states the tool's function: segmenting a recording, extracting features, testing for statistical trends, and detecting onset. It also distinguishes itself from sibling tools by positioning itself as 'THE unified screening tool' and explicitly contrasting with estimate_rul for prognosis, making its unique purpose clear.

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

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

Usage guidance is explicit: it states the tool is for screening within a single recording, not for prognosis, and directs users to estimate_rul for Remaining Useful Life. It also notes the prerequisite of calling load_signal() first and explains how to use the per-segment series for RUL analysis. This clearly tells the agent when to use this tool versus 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?

With no annotations, the description carries the full burden and excels. It discloses that the signal must be loaded first, that units are only reported when declared (and never guessed), that severity tools need unit declaration, and that a ValueError is raised for unloaded signal IDs. It also explains the diagnostic meaning of each output parameter, going far beyond a basic 'calculate' operation.

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

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

The description is well-structured with a clear opening line, a helpful bullet list of statistical parameters, and concise Args/Returns/Raises sections. Every sentence adds value: the parameter explanations inform interpretation, and the unit caveat prevents misuse. It is appropriately sized for a diagnostics 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?

Given the single parameter, the presence of an output schema (StatisticalResult), and no annotations, the description is remarkably complete. It covers prerequisites, limitations, unit handling, error cases, and the nature of the results. No critical contextual gaps remain.

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

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

The schema only provides type/title for signal_id, but the description adds essential semantics: 'ID of the stored signal (from load_signal)' and explicitly ties it to the load_signal prerequisite. It also states the ValueError condition, clarifying that the parameter must reference a previously loaded signal. This fully compensates for the 0% schema description 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 clearly states the tool's function: 'Calculate statistical parameters of a stored signal for diagnostics.' It uses a specific verb (calculate), identifies the resource (statistical parameters of a stored signal), and distinguishes itself from siblings like analyze_fft (frequency-domain) and check_bearing_faults (fault-specific) by focusing on statistical indicators.

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

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

The description provides explicit usage context: 'Requires the signal loaded via load_signal() first' and 'Statistical parameters are screening indicators, not definitive diagnostics — combine with frequency-domain evidence.' This states when to use the tool, a prerequisite, and a clear recommendation to pair with alternative frequency-domain analysis, fulfilling the when/when-not/alternatives 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?

With no annotations, the description carries the full burden and does so well: it details the reference selection logic, classification criteria, severity aggregation, comparability handling, and the exact reprocess behavior (idempotent, bounded to 10, hash-verified, next-call guidance). It also mentions return statuses and exceptions. The only minor gap is not stating whether the tool mutates state—reprocess=True does modify snapshots, but that is implied.

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

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

The description is dense and front-loads the core logic, but it is quite long with multiple embedded clauses and parenthetical details. The structure is logical yet verbose, and some sentences could be streamlined. It earns its place but is not tightly concise.

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

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

Given the tool's complexity (7 parameters, 0% schema coverage, output schema present, no annotations), the description is remarkably complete. It covers reference logic, classification, comparability, reprocessing, return statuses, and exceptions. An agent has enough context to invoke it correctly without external documentation.

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 0%, so the description must compensate. It explains asset_id, measurement_point_id, acquired_since/until (as ISO 8601 bounds), last_k (1 to 50), reference_measurements (3 to 100), and reprocess. It adds meaning beyond the schema, such as the reference window size when no baseline is declared and the role of last_k in bearing evidence. The //ctx parameter is noted as unused but not fully described.

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: 'Assess the change of one measurement point against its reference.' It distinguishes itself from siblings like declare_healthy_baseline and analyze_signal_trend by focusing on a single measurement point and a declared or automatic reference. An agent can immediately tell it evaluates change status for an asset point.

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

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

The description explains the core use case and mentions reprocess=True when processing lineage is not homogeneous, which implies when to use that flag. However, it does not explicitly compare against alternatives like assess_severity or analyze_signal_trend, nor does it state when-not to use this tool. Usage guidance is implied but lacks explicit routing.

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

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

With no annotations, the description carries full transparency burden and excels: it covers unit handling (never guessed), standard provenance, mutual exclusivity, custom threshold behavior, rpm band selection, refusal conditions, and detailed ValueError cases. It even notes that ctx is unused and references logging. This is exemplary 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 description is well-structured with clear sections (purpose, input routes, args, returns, raises) and front-loaded. It is long but justified given complexity. Minor redundancy exists: signal_id and rms_velocity_mm_s are described both in 'Input routes' and 'Args,' but this aids readability rather than wasting space.

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

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

Given 7 parameters, two usage routes, custom thresholds, and many error conditions, the description covers everything needed: prerequisites, metadata requirements, return structure (VibrationSeverityResult fields), and error cases. The presence of an output schema further reduces the need to explain return values, and the description still lists key output fields. Complete for a complex 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 0%, so the description must explain all 7 parameters. It does so thoroughly: mutual exclusion, defaults, units, custom threshold structure, power refusal, and conditional behavior (e.g., 'Ignored when custom thresholds are given'). Every parameter's meaning is expanded well beyond the bare schema.

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

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

The description states a specific verb+resource: 'Assess vibration severity (ISO 20816-3 zones A-D) and alert level.' It clearly defines the tool's purpose and standard, and positions itself as 'THE unified severity tool,' distinguishing it from other analysis and reporting tools in the sibling list.

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

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

The description provides clear usage context: it explains the two mutually exclusive input routes (signal_id vs. rms_velocity_mm_s), requires 'exactly ONE,' and notes prerequisites like 'load_signal first.' It also defines scope with the >15 kW refusal. However, it does not explicitly name alternative tools to avoid using, so it misses the 'versus alternatives' clause.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently specifies the exactness requirement ('never guessed'), identifies the formula source, states that ctx is unused, and lists the return dictionary. This is solid but not exhaustive; it omits error conditions or edge cases.

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

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

The description is well-structured and front-loaded with the purpose. Each section—usage note, args, returns, example—earns its place. The example is relevant and compact, showing a typical call and output. No redundancy; length is appropriate for the tool's complexity.

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

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

Given the presence of an output schema, the description need not elaborate on return values, but it still notes they are in Hz. It covers input sourcing, formula reference, defaults, and includes a worked example. Missing are the physical meanings of each characteristic frequency and any valid range or error handling, but for a calculation tool this is adequate.

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 0%, so the description fully compensates by providing symbols, meanings, and units for every parameter (e.g., 'num_balls: Number of rolling elements (Z)'). It also clarifies the default for contact_angle_deg and notes ctx is unused. This is exemplary parameter documentation.

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

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

The description opens with a specific verb and resource: 'Calculate bearing characteristic frequencies from geometry.' It names the exact outputs (BPFO, BPFI, BSF, FTF) and cites a standard reference, making its purpose unmistakable and distinct from sibling analysis tools.

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

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

The description clearly states when it should be used: when exact geometry is available from the manual, catalog, or user, and cautions against guessing. It also notes the deep-groove ball bearing contact angle default. However, it does not explicitly mention when not to use it or propose alternatives, so it stops short of a 5.

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

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

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses route exclusivity, verified catalog entries, canonical fault vocabulary mapping, provenance echoing, return summary contents, and a comprehensive Raises section listing all error conditions. The only minor gap is not explicitly stating whether the envelope spectrum must be pre-computed or is computed internally, but this is not a significant omission.

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 long but well-structured with headers, bullet lists, and an Args section, front-loading the purpose in the first line. It is appropriately sized for a tool with 9 parameters and three routes. Minor redundancy exists (e.g., route descriptions partly restated in Args), and the internal note about ctx being unused is extra detail that an agent doesn't need for selection/invocation.

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

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

Given the complexity, missing annotations, and empty schema descriptions, the description covers all essential aspects: what the tool does, prerequisites, route selection rules, parameter meanings, return type (BearingFaultsSummary with provenance), and error behavior. The output schema exists and is well-summarized, so no further return-value detail is necessary.

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

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

The schema provides no parameter descriptions (0% coverage), but the description's Args section thoroughly compensates. It provides units (RPM, mm, Hz, percent), defaults (contact_angle_deg=0, tolerance_pct=5), constraints (frequencies all > 0), and explains the role of each parameter within the three routes, including an example dictionary. This is far beyond what the bare schema offers.

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

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

The first sentence clearly states the verb and resource: 'Check expected fault frequencies in a stored signal's envelope spectrum.' It also brands itself as 'THE unified bearing-check tool' and enumerates three distinct routes, which distinguishes it from siblings like calculate_bearing_characteristic_frequencies and analyze_envelope.

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

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

The description explicitly states the prerequisite (signal loaded via load_signal()) and that exactly one expected-frequency route must be provided. It explains when to use each route: catalog lookup for verified bearings, explicit frequencies for non-catalog or non-bearing checks like gearbox GMF, and explicit geometry for out-of-catalog cases. However, it does not explicitly contrast with sibling tools such as calculate_bearing_characteristic_frequencies, so it lacks a direct when-not-to-use statement.

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

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

With no annotations, the description carries the full burden and largely meets it: it discloses the memory-vs-disk boundary, that a load-time measurement persists in asset history, and the return shape (cleared_count, signal_id, status). It does not state whether the in-memory removal is irreversible for the session or note any confirmation/authorization requirements, leaving a gap for a mutating tool.

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

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

The core behavior is well front-loaded in the first two paragraphs, but the Args/Returns docstring boilerplate is wasteful: the ctx entry references an external module docstring that an agent cannot see, and the Returns block duplicates the output schema that already exists. Roughly a third of the text does not earn 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?

Given a single-parameter tool with an output schema present, the description is nearly complete on behavior, side effects, and persistence semantics. The redundant Returns section and the phantom ctx parameter are the only meaningful blemishes, and neither blocks correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: signal_id is explained as the ID to remove with None (default) clearing the whole cache, which fully resolves the anyOf string/null ambiguity. It is docked slightly for documenting a 'ctx' argument that does not exist in the input schema, which adds confusion rather than clarity.

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

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

The description opens with a specific verb and resource ('Remove one signal — or all signals — from the in-memory repository') and pins the scope to the in-memory cache, which cleanly separates it from disk-oriented siblings like load_signal and the list_* tools. An agent can identify the operation without opening the schema.

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

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

It gives clear context for when this applies ('Memory only; the asset ledger on disk is untouched') and explains the reload-recognition behavior, which helps an agent decide whether clearing is safe. It stops short of explicitly naming alternatives or when-not-to-use conditions, so it lands below the top tier.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It mentions the Welch method and the load_signal prerequisite, but does not describe potential errors, side effects (likely none), or output specifics. Given that an output schema exists, this is adequate but not rich.

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

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

The description is concise and well-structured: a one-line summary, a prerequisite, and a clearly formatted Args list. Every sentence contributes useful information with no redundancy.

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

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

Given the tool has an output schema, return values are covered. The description includes the essential prerequisite and parameter semantics, enough for a moderate-complexity tool with 4 parameters. However, it omits edge-case behavior (e.g., invalid signal_id, constraints on nperseg Vs noverlap), so a 4 is appropriate.

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

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

The input schema has 0% description coverage, but the description's Args section fully compensates by explaining each parameter's meaning (samples per FFT segment, overlap, window function) and listing defaults. This adds significant value beyond the raw schema.

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

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

The description clearly states 'Compute Power Spectral Density (Welch method) for a stored signal' with a specific verb, resource, and method. It distinguishes this from sibling tools like compute_spectrogram_stft and analyze_fft, making the tool's purpose unambiguous.

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

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

The description provides a clear prerequisite ('Requires signal loaded via load_signal() first'), establishing context for when the tool should be used. However, it does not explicitly contrast with alternatives or state when not to use it, so it falls short of a 5.

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

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

With no annotations, the description carries the transparency burden. It discloses a key behavioral trait: the return is a time-frequency summary, not a full 2D array. However, it does not mention side effects, prerequisites (e.g., signal must exist), or potential errors, which are relevant for an unannotated tool.

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

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

The description is appropriately concise: a short purpose statement, a usage note, and a bulleted parameter list. No redundant sentences; every element contributes to understanding.

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

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

Given the output schema exists, return values do not need explanation. The description covers purpose, usage, and parameters adequately. It could add constraints or error conditions, but for a compute tool with this schema richness, it is fairly 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 0%, so the description must compensate. It explains all four parameters: signal_id, nperseg, noverlap, and window, including defaults. It does not cover constraints like nperseg > noverlap or valid window types, but it provides enough meaning for basic usage.

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

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

The description clearly states the tool computes an STFT spectrogram for a stored signal, using a specific verb and resource. It also distinguishes itself from siblings by emphasizing time-frequency analysis and noting the output is a summary, not a full 2D array.

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 guidance on when to use it: 'Use for detecting time-varying frequency content (transient faults, speed changes).' Does not explicitly mention alternatives or exclusions, but the context and sibling names make alternatives clear.

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

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

With no annotations the description carries the full burden and does so: eligibility rules (members must be recorded measurements of THIS point, comparable or qualified against the current declaration, no two sharing an acquisition slot, 3-100 members), versioning semantics after re-declaration, withdrawal behavior, and a Raises section enumerating every rejection reason. This is far beyond what structured fields provide.

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

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

Front-loads the core purpose and is organized into Args/Returns/Raises, but some material is redundant with structured fields (the Returns block restates the output schema, and the Raises list is long). The length is justified by tool complexity, though it could be trimmed slightly.

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

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

For a mutation tool with five parameters, no annotations, and a complex validation model, the description covers invocation, constraints, side effects on assess_asset_change, withdrawal semantics, and error conditions. An output schema exists, so the extra return detail is a bonus rather than a necessity.

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 0%, and the description fully compensates: it names each argument, gives the source of measurement_ids, the 3-100 bounds, the free-text limits (200 chars, one line) for declared_by and note, and the withdrawal-only requirement for note. Nothing is left for the agent to infer.

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: 'Declare which recorded measurements are the healthy reference of a point.' It also positions the tool against its main sibling by explaining that assess_asset_change uses this baseline, so an agent can tell the two apart without opening either schema.

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

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

Explicitly describes the condition under which the tool matters (until declared, assess_asset_change falls back to first comparable acquisitions), where the ids come from (load_signal, get_asset_history), and the alternative behavior of passing an empty list to withdraw, including the requirement of a note and the resulting fallback to the automatic window.

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

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

With no annotations, the description carries the full burden and delivers: versioning semantics (a no-op re-declaration appends nothing and returns the current version; a change appends and reports changed keys), precedence rules (a measurement's rpm wins over nominal_rpm), contradiction handling (contradicting measurements are excluded, omitting ones qualified), the 'no silent default' ISO behavior, and the stale-snapshot count plus the exact reprocess remedy call.

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

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

Args/Returns/Raises headers give good structure and the purpose is front-loaded, so the length is defensible for a 13-parameter, versioned tool. It loses a point for dense, parenthesis-heavy prose and for a Returns section that duplicates the existing output schema.

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

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

For a high-complexity versioned mutation with 0% schema coverage and no annotations, the description covers all parameters, the versioning/staleness model, the remedy call, and the ValueError conditions in one place. An agent has everything needed to invoke it correctly, even though the output schema already exists.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: it documents id grammar (letters/digits/underscore/dash/dot, leading alnum, case-sensitive), fault_orders labels and shaft-multiple convention, machine_group 1/2, support_type values, positive-number constraints on nominal_rpm and machine_power_kw, and the 200-char one-line limits on free text. This meaning is not recoverable from the schema alone.

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

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

The description names a specific verb (declare) and resource (the context of a measurement point in the local asset ledger), then enumerates exactly what that context comprises. It also positions the tool relative to consumers like health snapshots and diagnose_vibration, so an agent can tell what it does without opening the schema.

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

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

It explains what the declaration feeds (snapshots and diagnose_vibration defaults) and when stale context arises, which implies usage. However it never states when to prefer this over the sibling declare_healthy_baseline, nor gives an explicit when-to-use / when-not-to-use rule, leaving routing to inference.

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

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

With no annotations, the description carries the full behavioral burden and does so richly: it discloses graceful degradation (refusal block instead of failure), the never-guess-units policy, the exact precedence chain for rpm/bearing_id/machine_group/support_type, which blocks get skipped, and the ValueError conditions. This is far beyond anything the schema or annotations convey.

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

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

Front-loaded with the one-line summary, then behavior, then Args/Raises, so a reader can stop early. It is long and somewhat repetitive (the degradation/refusal theme is restated across two paragraphs with heavy capitalization), but for a multi-mode diagnostic pipeline most of it earns its place.

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

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

An output schema exists, so return values need not be described; the description instead covers the things structured data cannot — degradation semantics, unit requirements, parameter resolution, and error conditions. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 0% and the schema only gives bare types/enums/defaults, so the description must compensate — and it does: each of the five parameters gets a purpose plus its full resolution fallback chain (e.g. rpm → declared measurement rpm → point nominal_rpm → refuse). This adds substantial meaning the schema lacks.

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

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

Opens with a specific verb+resource and enumerates the composed analyses (FFT + PSD + STFT + bearing faults + ISO severity), which instantly distinguishes it from siblings like analyze_fft, compute_power_spectral_density, check_bearing_faults and assess_severity that each do one slice. An agent can tell this is the umbrella pipeline 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?

Framing it as the 'comprehensive' pipeline that 'runs all analyses' clearly signals when to reach for it over the single-analysis siblings, and it names check_bearing_faults(frequencies=...) as the alternative when a point has fault_orders but no bearing_id. It does not explicitly state when NOT to use it (e.g. when you only need one analysis), 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?

With no annotations provided, the description carries the full burden of behavioral disclosure and does so thoroughly. It discloses that the tool refuses single-point input, requires a statistically significant increasing trend (p<0.05), and returns status 'no_degradation_trend' otherwise. It also explains the assumption that the indicator rises toward the failure threshold, defines fit_r_squared as not a confidence measure, and references ISO 10816-3 boundaries externally, leaving no hidden behavior.

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

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

The description is long but well-structured, with clear sections for purpose, usage restrictions, input routes, behavioral assumptions, parameter details, and return values. Each sentence contributes necessary information given the complexity of the tool (7 parameters, nuanced degradation logic). It could be slightly tightened, but the length is justified and the front-loaded purpose statement ensures immediate clarity.

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

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

Given the high complexity of the tool, an output schema presence, and no annotations, the description is exceptionally complete. It covers prerequisites (multiple measurements), input alternatives, statistical requirements, parameter semantics, and return behavior (status, rul conditional, observation_horizon). The only missing detail is the exact shape of the output object, but that is covered by the output schema, so the description meets the completeness bar.

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

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

The schema provides zero parameter descriptions, so the description must compensate fully—and it does. Each parameter is explained with its role, units, defaults, and constraints: failure_threshold in same units as feature values, timestamps strictly increasing, feature_values and signal_ids mutually exclusive, feature_name default 'rms' and ignored for feature_values, method enum with linear default and kalman spacing requirement, time_unit as the label for RUL expression. This adds substantial meaning beyond the raw schema.

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

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

The description opens with a clear verb+resource statement: 'Estimate Remaining Useful Life from repeated measurements over time.' It explicitly distinguishes itself from the sibling tool analyze_signal_trend by stating it refuses single-point data, while also specifying that it operates on multi-session degradation trends. This gives the agent a precise understanding of the tool's scope and differentiates it from related tools.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: it refuses a single recording or point and directs the agent to 'analyze_signal_trend instead' for within-recording screening. It also details two mutually exclusive input routes (feature_values vs signal_ids) and notes the condition that kalman needs approximately uniform measurement spacing, giving clear criteria for selecting this tool over 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?

With no annotations, the description carries full burden. It discloses the requirement of a loaded signal and sampling rate from metadata, the return type (FeatureExtractionResult), potential ValueError conditions, and the side-effect of not writing CSV files. This gives a clear behavioral profile without contradiction.

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

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

The description is well-structured with sections for Args, Returns, Raises, and an Example. The opening sentence is concise, and each additional sentence provides necessary information about behavior, prerequisites, or errors—no filler.

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

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

The description is complete enough for an agent to invoke the tool correctly. It covers prerequisites, parameter semantics, return type, error conditions, and includes an example. It does not need to explain the output schema in detail because an output schema is provided.

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 0%, but the description compensates with an Args section explaining each parameter: signal_id is 'ID of the stored signal (from load_signal)', segment_duration is 'duration in seconds' with default 0.1, and overlap_ratio is 'overlap between segments, 0-1' with default 0.5. It also includes units and defaults beyond the schema.

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

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

The description begins with a specific verb and resource: 'Extract time-domain features from a stored signal using sliding windows.' It clearly distinguishes this from sibling tools like analyze_fft or compute_power_spectral_density by focusing on time-domain features and sliding-window segmentation.

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 a clear prerequisite: 'Requires the signal loaded via load_signal() first.' It also notes that the tool returns an in-memory summary and explicitly says 'no CSV is written to data/signals/', signaling when not to use it if a file output is expected. However, it does not name alternative tools, so it falls short of explicit 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?

With no annotations, the description carries the behavioral transparency burden. It discloses caching, the 'never invent' constraint, and potential `FileNotFoundError`. It also clarifies that `ctx` is unused, which prevents confusion. It does not mention permissions or rate limits, but these are less critical for a PDF extraction tool. Overall, it provides solid behavioral context beyond what schema offers.

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 moderately sized but well-organized into description, Args, Returns, and Raises sections. Each section adds value. The mention of `ctx` may be unnecessary since it's not in the schema, and the Returns section partly repeats the opening sentence. Still, the structure aids readability and nothing is extraneous.

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, the description doesn't need to detail return values, but it does summarize them. It covers error handling with `FileNotFoundError` and mentions that the error message lists available manuals. It could have mentioned `list_machine_manuals` as a prerequisite, but the error handling covers discovery. Overall, it is sufficiently complete for a 2-parameter tool with an 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?

The input schema has 0% description coverage, so the description must explain parameters. It does: `file_name` specifies the location under `resources/machine_manuals/`, and `use_cache` explains caching behavior with its default. This adds meaningful semantics beyond the bare schema, which only shows types and defaults.

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

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

The description clearly states the tool's function with a specific verb ('Extract') and resource ('machine specifications from an equipment manual (PDF)'), and enumerates example outputs (bearing designations, speeds, power ratings, text excerpt). It distinguishes itself from siblings like `search_bearing_catalog` by focusing on extraction from manuals, and from `read_manual_excerpt` by covering specifications rather than arbitrary excerpts.

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

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

The description provides explicit follow-up guidance: if a bearing's geometry is not in the manual, use `search_bearing_catalog(bearing_id=...)`, and if not there either, ask the user—never invent. It also explains caching behavior and that `use_cache` controls it, which tells the agent when to disable caching. This makes usage context and alternatives clear.

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

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

With no annotations present, the description carries the full burden. It discloses the authorship contract, the absence of confidence figures, the requirement to preserve the standards caveat, and that the server alone writes evaluative sentences. It also documents exceptions and the pdf dependency, going well 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?

The description is structured into clear sections (summary, authorship contract, args, returns, raises) and, while long, every part serves a purpose for such a complex tool. The front-loaded summary gives immediate orientation without wasted 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?

Given the tool's complexity and the presence of an output schema, the description is complete: it covers return semantics, exceptions, dependencies, and behavior for omitted parameters. It is fully self-sufficient and leaves no critical gap.

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

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

Schema description coverage is 0%, so the description fully compensates with a detailed Args block explaining each parameter, including defaults, enum choices, and behavior for omitted bearing_id. This adds meaning far beyond the raw schema types.

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

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

The description clearly states the tool's purpose: 'Generate the integrated diagnostic report — one document, whole case.' It enumerates the sections rendered and explicitly distinguishes itself from generate_diagnostic_report_docx by noting it takes no caller content sections.

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

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

The description explicitly contrasts this tool with generate_diagnostic_report_docx, and explains when to supply baseline_signal_id for delta readings. The 'AUTHORSHIP CONTRACT' provides clear instructions on how to handle output, making the usage context thorough.

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

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

With no annotations provided, the description carries full burden and meets it: it discloses prerequisites (pip install), error conditions (ValueError for missing signal or python-docx), the return type (dictionary with file_path, file_name, summary), and notes that ctx is unused. This exceeds typical transparency.

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

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

The description is well-structured with a clear opening summary, a detailed but organized sections breakdown, and concise Args/Returns/Raises. Every sentence adds value, and the structure is front-loaded with the main purpose.

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

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

For a tool with nested objects, 3 parameters, and no annotations, the description is comprehensive: it covers prerequisites, errors, return format, and parameter details. The presence of an output schema does not reduce the need for this clarity, and the description fully delivers.

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

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

The schema provides only types and a generic sections object, while the description supplies rich semantics: it enumerates the allowed section keys (statistics, fft_peaks, etc.), expected types and shapes, and explains how signal_id and title are used (report title/filename). This fully compensates for the 0% schema 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 opens with a specific verb+resource: 'Generate a structured Word (.docx) diagnostic report for a stored signal.' The .docx format and diagnostic report scope clearly distinguish it from sibling tools like generate_diagnostic_report or generate_fft_report, even without naming them.

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

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

The description clearly states the prerequisite that the signal must be stored (from load_signal) and requires an install. It also clarifies that 'sections' is optional, implying usage context. However, it does not explicitly mention alternatives or when not to use, so it stops short of a 5.

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

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

Without annotations, the description carries the full burden and does so thoroughly. It discloses that the tool writes a file to reports/, depends on prior load_signal(), uses metadata for sampling rate, reads optional bearing_freqs from _metadata.json, rejects rather than clamps filter_high above Nyquist, and returns a dictionary without HTML content. It also lists exceptions and notes ctx is unused.

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 long but every sentence earns its place. It front-loads the core purpose in the first line, then progressively provides necessary detail on prerequisites, parameters, returns, and exceptions. The example is compact and illustrative. There is no redundant filler.

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

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

The description covers prerequisites, side effects, return value format, error conditions, parameter defaults, and edge cases. Even though an output schema exists, it goes beyond that by explaining the dictionary structure. Given the tool's complexity (6 params, file output, dependencies), this is a complete and self-contained description.

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

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

Schema description coverage is 0%, but the Args section explains all six parameters with meanings, defaults, and constraints. For example, filter_high: 'Default (None) adapts to the signal: min(5000, Nyquist-1). An explicit value above Nyquist is rejected, never clamped.' The example also demonstrates bearing_freqs structure, fully compensating for the lack of schema descriptions.

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

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

The description opens with a clear, specific statement: 'Generate professional envelope analysis report (HTML) for a stored signal.' It identifies the resource (envelope analysis report), format (HTML), and context (stored signal). This distinguishes it from sibling tools like generate_fft_report or generate_iso_report, and the phrase 'instead of inline content' further differentiates it from analyze_envelope.

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

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

The description provides clear usage context: it requires the signal to be loaded via load_signal() first, states that it saves to a reports/ directory, and explains how bearing frequencies are handled. It does not explicitly name alternatives or exclusion scenarios, but the prerequisites and output format give a solid sense of when to use this tool.

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

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

With no annotations provided, the description carries the burden of disclosing behavior. It states the tool creates an interactive HTML report, depends on signals' stored sampling-rate metadata, raises ValueError for unloaded signals, and returns a dictionary with file path, metadata, and summary. This provides meaningful context beyond the schema, though it does not detail filesystem side effects like overwrite behavior.

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

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

The description is well-structured with clear sections: intro, strategy, args, returns, raises, and example. Every sentence provides value, the main purpose is front-loaded, and the example is compact yet illustrative. There is no redundant filler.

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

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

For a tool with 4 parameters, no annotations, and an output schema, the description covers prerequisites, dependencies on load_signal, return shape, error conditions, and a usage example. It also integrates with the sibling tool family by noting the shared HTML report approach. This is effectively complete for an agent to invoke and understand the tool.

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

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

The input schema provides 0% description coverage, but the description's Args section thoroughly explains all four parameters, including defaults, types, and the signal_groups structure with a concrete example. It also clarifies the semantics of features_to_plot (null means all 17 features). This fully compensates for the schema gap.

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

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

The description opens with a specific verb and resource: 'generate feature comparison report with violin plots comparing time-domain features.' It clearly scopes the tool to comparing features across signal groups and differentiates it from sibling report generators like generate_fft_report or generate_envelope_report.

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

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

The description states the tool requires signals loaded via load_signal() first and notes the shared 'same HTML report approach as other reports.' It implies usage is for feature discrimination analysis, but it does not explicitly state when NOT to use this tool versus alternatives, so it misses the 5-level criterion.

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?

No annotations are provided, so the description carries the full burden. It discloses that the tool saves a self-contained Plotly HTML report to reports/ with timestamped filenames, consecutive runs produce distinct files, and the return value contains no HTML content (just path, metadata, summary). It also documents error conditions (ValueError for unloaded signal or missing sampling rate). This is extensive behavioral disclosure beyond what the schema provides.

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

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

The description is well-structured with a one-sentence summary, a prerequisite note, then Args/Returns/Raises sections. Every sentence adds useful information: file naming behavior, sampling rate source, parameter meanings, return structure, and error conditions. No fluff or redundancy.

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

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

Given the tool's complexity (4 parameters, no annotations), the description fully covers the prerequisite (loaded signal), the output behavior (file path, metadata, summary), error conditions, and parameter semantics. It is complete enough for an agent to invoke the tool correctly and interpret the result without additional context.

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

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

The schema has 0% description coverage, but the description compensates fully with an Args section explaining each parameter: signal_id, max_freq (with default), num_peaks (with default), rpm (with harmonic labeling semantics), and ctx (unused). It adds meaning beyond the schema by explaining the harmonic labeling behavior (rpm/60 Hz multiples as 1x/2x/...) and the default values for max_freq and num_peaks.

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 begins with a specific verb and resource: 'Generate an interactive FFT spectrum report (HTML) for a stored signal.' This clearly distinguishes it from sibling report generators (envelope, ISO, PCA, etc.) by naming the FFT spectrum focus. The phrase 'FFT spectrum report' is unambiguous and aligns with the tool name.

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

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

The description states a clear prerequisite: 'Requires the signal loaded via load_signal() first; the sampling rate comes from the stored signal metadata.' This gives the agent context on when the tool can be invoked. However, it doesn't explicitly contrast with alternatives like generate_envelope_report or analyze_fft, so it lacks explicit exclusions/alternative guidance. The context is strong enough to warrant a 4 rather than 3.

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

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

With no annotations provided, the description carries full burden and delivers: it discloses the file side-effect (saves to reports/ with timestamped filename), chart contents, delegation to assess_severity, the 'units are never guessed' rule, return shape (dictionary with NO HTML content), and ValueError conditions for unloaded signals or missing sampling rate/unit.

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 line, followed by a clear Args/Returns/Raises structure that is scannable. The description is longer than average, but every sentence earns its place given zero schema descriptions — including the transparent note that ctx is unused.

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

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

For a tool with an output schema, no annotations, and 0% schema description coverage, this description is complete: it covers prerequisites, side-effects, error conditions, parameter meanings, delegation, and return shape. Nothing critical is missing for an agent 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 0%, and the description compensates well: machine_group gets kW ranges (large >300 kW / medium 15-300 kW), rpm gets behavioral semantics (selects ISO band's lower edge below 600 RPM), and signal_id gets source context (from load_signal). support_type is merely repeated from the enum without explaining rigid vs flexible, leaving a minor gap.

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

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

The description opens with a specific verb+resource: 'Generate an ISO 20816-3 evaluation report (HTML) for a stored signal.' It further details the output (color-coded A-D zone chart with RMS marker, boundaries, severity text), which clearly distinguishes it from sibling report generators like generate_fft_report or generate_diagnostic_report.

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 is provided: the signal must be loaded via load_signal() first with sampling rate and a declared unit. It also notes the evaluation is delegated to assess_severity, implying that tool handles evaluation-only use cases. However, it does not explicitly name alternatives or state when not to use this tool.

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

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

Since no annotations are provided, the description fully carries the behavioral transparency burden. It discloses the confidence value behavior (echoed without evidential basis), the error handling (ValueError with allowed values, never silent), and the fact that ctx is unused. This goes beyond basic operation and explains underlying logic.

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 moderately long but every element serves a purpose: purpose statement, behavioral caveat, structured Args/Returns/Raises. The front-loaded summary gives immediate understanding, and the structured format makes scanning easy without redundancy.

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

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

For a tool with two parameters and important constraints, the description covers all necessary context: inputs, output format, error behavior, and usage nuances. Output schema exists, so return details are handled there. The description is fully adequate for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate entirely. It does so thoroughly: severity_zone is explained as ISO zone letters, and fault_types is described with the canonical vocabulary, the explicit exclusion of BPFO/BPFI/BSF/FTF acronyms, and the meaning of None. This adds meaning well beyond the schema's enum lists.

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

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

The description clearly states the tool's function: 'Generate maintenance recommendations based on severity and detected faults.' It further specifies the uniqueness by combining ISO zone-based urgency with fault-specific actions, distinguishing it from sibling tools like assess_severity or diagnostic report generators.

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 guidance on inputs: allowed fault types, the warning against using BPFO acronyms, and the 'None' option for zone-only advice. It also explicitly states the tool does NOT accept a confidence value, which is a clear exclusion. However, it does not compare to alternative sibling tools, leaving some ambiguity about when to choose this over other diagnostic tools.

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

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

With no annotations provided, the description carries the full burden of disclosure. It honestly warns that labels are model predictions, not ground truth, and explains the need for `true_labels`. It also lists error conditions (FileNotFoundError, ValueError) and prerequisites. It only omits explicit details about where the HTML file is saved, but this is a minor gap given the return value mentions a file path.

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

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

The description is well-structured with clear sections (overview, important note, args, returns, raises, example) and is front-loaded with the core purpose. Every sentence provides necessary information, though it is slightly longer than strictly needed. The example is valuable but adds length.

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

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

The description covers all essential aspects for using this tool correctly: purpose, prerequisites, parameter meanings, return value, error cases, and a concrete example. Since an output schema is available (per context), the return description is a bonus. The only minor omission is the exact file output location, which is not critical for invocation.

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

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

The input schema has 0% description coverage, but the description's Args section provides thorough semantics for every parameter: model_name includes an example, test_signal_ids explains optionality, true_labels includes format and example mapping, segment_duration gives unit and default, overlap_ratio gives range and default. This fully compensates for the schema's lack of descriptions.

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

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

The description clearly states the specific action ('Generate PCA visualization HTML report') and resource ('test data in 2D PCA space'), distinguishing it from sibling report tools like FFT/envelope/ISO reports. The mention of 'interactive scatter plot' and prediction labels makes its unique purpose explicit.

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

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

The description gives clear context for when to use the tool, including the prerequisite that test signals must be loaded via load_signal() first. It also explains when to use the `true_labels` parameter for validation. However, it does not explicitly contrast this tool with alternative report tools or state when not to use it, so it misses exclusions.

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

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

With no annotations, the description carries the full burden and does well: it discloses the write path (data/signals/ with timestamped filename), a companion _metadata.json declaring sampling_rate and unit 'g', auto-registration in the repository, and the exact signal content per fault type. It omits permissions, overwrite behavior, and error handling, but overall transparency is strong.

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

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

Front-loaded with the core purpose and side effects, followed by signal content and a conventional Args/Returns block; every section earns its place. There is minor redundancy between 'no manual steps' and 'auto-loaded... immediately usable,' but the structure is clean.

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 5-parameter mutation tool with no annotations, the description covers purpose, persistence side effects, fault-type content, and all parameters. An output schema exists, so the brief Returns section is sufficient; only permission and failure-mode details are absent.

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

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

Schema description coverage is 0%, and 5 params are undocumented in the schema, so the description must compensate — and it does, documenting all of them via an Args block: signal_type purpose, duration with a resolution hint (10 s = 0.1 Hz), sampling_rate, noise_level, and random_seed (None = non-deterministic).

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 ('Generate a synthetic test signal') plus its full lifecycle ('save it, and load it into the repository'). This clearly distinguishes it from siblings like load_signal or list_signals, which operate on existing data.

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

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

The description establishes clear context: this produces synthetic fault patterns and the returned signal_id is 'immediately usable by every analysis, diagnosis, and ISO severity tool.' However, it never explicitly states when to prefer this over load_signal (e.g., when no real measurement data exists), so there are no named alternatives or exclusions.

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

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

With no annotations, the description carries the full load and does much of it: it describes truncation at 50 assets, the integrity block, typed not_found behavior instead of exceptions, and ValueError conditions. It stops short of stating auth/permission requirements or read-only enforcement, but the error and truncation behavior are valuable and non-obvious.

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 two-mode structure is front-loaded and the Args/Returns/Raises sections are easy to scan. The prose is dense and some sentences pack multiple clauses, which slightly hurts readability but nothing is wasted.

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

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

Given a 3-parameter tool with no annotations, an output schema that only declares status values, and a 0% schema description coverage, the description supplies the missing parameter semantics, mode selection, and error behavior. It is complete enough to invoke correctly, though it could note prerequisites such as whether the ledger must already exist.

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 0%, so the description must compensate, and it does: asset_id is described as the ledger id or None for index, max_measurements is bounded 1–200 newest first, and measurement_point_id is a point restriction requiring asset_id. Defaults (e.g., max_measurements default 20) are not repeated, but the operational meaning of each parameter is conveyed.

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

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

The description names a specific verb (Read) and resource (the asset ledger) and then bifurcates into the two distinct modes: index (all assets) and per-asset history. The reader knows exactly what the tool returns in either mode without opening the schema.

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

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

It clearly states the condition for each mode (without asset_id = index; with asset_id = history) and the constraint that measurement_point_id needs asset_id. It does not explicitly name alternative tools like get_signal_info, but for this tool the mode selection is the dominant decision and that is well documented.

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

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

With no annotations, the description carries the burden and mostly succeeds: it discloses that the full array is NOT loaded, that source_metadata comes from the companion _metadata.json (empty dict when absent), and that ValueError is raised for an unknown signal_id. It omits nothing critical for a local read-only repository call, though it never explicitly says the operation is read-only/non-mutating.

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 two lead paragraphs are front-loaded and earn their place, but the docstring-style Args/Returns/Raises block partially duplicates what the schema and output schema already provide, and the ctx note ('Unused — see this module's docstring on logging') is noise for an agent.

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 precondition, the return payload, and the error case, which is enough for an agent to call it correctly. Because an output schema exists, the Returns paragraph is partly redundant, and there is no mention of behavior when the companion metadata file is malformed.

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 0% (the single signal_id property is a bare string), so the description must compensate, and it does by defining signal_id as an ID of a signal previously loaded via load_signal. That added constraint is meaningful, though no format or error-adjacent detail beyond existence is given.

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

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

States a specific verb (Get), resource (metadata for a stored signal), and scope qualifier (without loading the full array), which implicitly contrasts with the sibling load_signal that retrieves the array itself. An agent can tell what this returns 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 a clear precondition: the signal_id must be 'a signal previously loaded via load_signal', and the opening line frames the use case (metadata only, not the full array). It stops short of naming load_signal or list_signals as explicit alternatives or stating when not to use it.

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

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

With no annotations provided, the description carries the full burden, and it delivers: it details what is returned (list vs dict), what is not returned (HTML content), the token-saving behavior, and specific error conditions (ValueError for path escape, missing file, or missing metadata). This is thorough and goes beyond the bare minimum.

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

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

The description is well-structured with a summary sentence, then explanatory paragraphs for modes, arguments, returns, and raises. Every sentence adds meaningful information, and the docstring-like format makes it easy to parse. No filler or redundancy.

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

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

Despite having only one optional parameter, the description covers all aspects: purpose, modes, parameter validation, return types, and error handling. The output schema may provide additional structural detail, but the description alone is sufficient for an agent to select and invoke the tool correctly.

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

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

The only parameter, file_name, has 0% schema description coverage, so the description must compensate. It does: 'Optional report filename inside reports/ — returns its metadata instead of the listing' explains both the path constraint and the behavioral switch. The Raises section adds validation semantics, making the parameter's role fully clear.

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

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

The description opens with a clear verb+resource statement: 'List HTML reports, or get one report's embedded metadata.' It distinguishes two modes (with and without file_name) and explicitly states it never returns HTML content, setting it apart from sibling tools that probably handle report generation or content.

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

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

The description explicitly explains when to use each mode: without file_name for a listing of all reports, with file_name for a single report's metadata. It also says 'Never returns HTML content — metadata only, to avoid token consumption,' giving a clear when-not and rationale. The mention of 'absorbed get_report_info' signals that this tool replaces that function, providing alternative context.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently states the operation is a list, the location, the file types, and the exact return fields. It doesn't mention sorting or pagination, but for a read-only listing tool this is adequate; no side effects or permissions are implied.

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 only two sentences, with the main purpose first and usage guidance second. Every clause adds value: location, file types, usage context, and return format.

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

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

The tool is simple with no parameters, and an output schema exists. The description covers the tool's purpose, location, and return format, and includes a crucial usage instruction about passing filenames exactly as-is. It is fully adequate for an agent to select and invoke 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?

The tool has no parameters, and the schema is empty, so the baseline is 4. The description adds no parameter-specific information because there are none to explain, and the return-value note helps clarify output but that's not parameter 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 clearly states 'List all machine manuals in resources/machine_manuals/ (PDF/TXT)', providing a specific verb, resource, and scope. It distinguishes itself from sibling tools by focusing on listing rather than reading or extracting, and explicitly names usage with siblings.

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

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

The description explicitly says 'Use before read_manual_excerpt / extract_manual_specs', providing clear context for when to invoke this tool. It also instructs to 'pass the returned filenames exactly as-is', which guides the agent on how to use the output. No alternative for 'when not to use' is given, but the guidance is sufficient for this simple listing operation.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It explains the default scope, the return structure (Dict with scope, count, and files/signals), and notes that ctx is unused. It implies a read-only listing operation, though it never explicitly states there are no side effects.

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

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

The description is well-structured with a clear first-line summary, followed by Args and Returns sections. Each part contributes value, but the 'ctx: MCP context. Unused...' note is a minor tangential detail that prevents a perfect score.

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

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

For a single-parameter list tool with an output schema, the description covers the default behavior, valid parameter values, return format, and usage intent. There are no significant gaps in context for an agent to invoke and interpret results 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 0%, but the description fully explains the only parameter, scope, by defining each enum value ('disk' vs 'memory') and its behavioral consequences. This adds significant semantic meaning beyond the raw schema enum.

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

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

The description opens with a specific verb and resource: 'List signal files on disk or signals loaded in the repository.' It explicitly distinguishes the disk and memory scopes, making it clear what this tool does and differentiating it from related tools like load_signal and clear_signals.

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

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

The description provides clear usage context: disk scope is for 'use before loading' and memory scope is for 'seeing which signal_ids are available for analysis.' It does not explicitly name alternative tools or when not to use this tool, so it falls just short of a 5.

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

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

With no annotations, the description carries the full burden and does so richly: batch is fail-fast and atomic with one combined error, id collision is an explicit error unless overwrite, unit declaration discipline for ISO verdicts, raw decode contract requirements, and that ledger problems never fail the load (reported as ledger_status 'not_recorded', safe retry). These are exactly the behavioral 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?

Long but organized into clearly labeled blocks (batch, id default, unit discipline, raw files, asset ledger) and front-loaded with the core purpose. It is dense and nearly every sentence adds operative detail, though the sheer volume slightly exceeds what a minimal call needs.

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

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

For a complex 11-parameter ingest tool with no annotations and a documented return (StoredSignalInfo) plus Raises, the description covers inputs, defaults, error conditions, and side effects (ledger/snapshot). 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 0%, so the description must compensate, and the Args section documents every one of the 11 parameters with defaults, allowed values (e.g. 'g'/'m/s2'/'mm/s'/'m/s', endianness, sample formats) and interaction rules (parameter overrides metadata, raw params broadcast in batch). This fully compensates for the empty 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 ('Load one signal — or a batch — into the in-memory repository') and explicitly frames its role as the entry point of the load -> analyze -> diagnose -> report flow, distinguishing it from sibling analysis/report tools. An agent immediately knows this is the ingest step.

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

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

Clear context for single vs batch use (batch for training sets) and how downstream tools consume signal_id. It explains the signal_id handle and when overwrite is needed, but does not name alternative ingestion paths (e.g. generate_test_signal) or state when-not-to-use, 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?

With no annotations, the description carries the transparency burden. It discloses that the tool generates an HTML file, requires a loaded signal, raises ValueError on invalid input, and returns a file path. It also notes the sampling rate comes from metadata. While it does not mention file location or overwrite behavior, the disclosed error conditions and return type provide solid transparency.

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

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

The description is well-structured with clear sections (Description, Args, Returns, Raises, Example), each earning its place. The opening one-liner states the core purpose, and the example adds practical value without redundancy. Length is appropriate for the tool's complexity.

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

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

The description covers purpose, usage, parameters, return value, error conditions, and a usage example. It includes mention that ctx is unused, which helps agent calls. Even with an output schema present, it explains the return path, making the tool fully understandable standalone.

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 0%, but the Args section fully compensates by explaining every parameter: signal_id (origin), time_range (format and units), show_statistics (what lines are shown), and title (custom). The example further clarifies usage with a concrete time_range. This goes well beyond the schema's bare property definitions.

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 begins with a specific verb+resource: 'Generate interactive time-domain plot for a stored signal.' This clearly distinguishes it from sibling analysis tools (FFT, envelope, statistics) by focusing on time-domain visualization. The subsequent sentence about inspecting signal quality, identifying anomalies, and visualizing transients reinforces its unique role.

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

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

The description explicitly states the prerequisite (signal must be loaded via load_signal()) and explains when the tool is useful (inspecting quality, anomalies, transients). However, it does not explicitly mention when not to use it or name alternative tools for other analysis types, stopping short of the fullest 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?

With no annotations provided, the description fully carries the transparency burden. It discloses that output is 'BOUNDED' and 'never per-segment arrays', describes the internal pipeline, notes that ctx is 'Unused', and details exact error conditions including that FileNotFoundError lists models on disk. This is rich behavioral context beyond a basic 'predict' statement.

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 main purpose, then systematically covers prerequisites, pipeline, output bounds, parameters, returns, and errors. Every sentence earns its place; the use of Args/Returns/Raises headers improves scannability without redundancy.

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

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

For a two-parameter tool with an output schema, the description provides a complete picture: required prerequisites, the transformation pipeline, bounded output behavior, parameter sources, and concrete failure modes. An agent can confidently select and invoke this tool correctly without needing additional context.

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 0%, so the description must compensate. The Args section adds meaning: signal_id is identified as coming from load_signal, model_name is given a default and linked to the training result, and ctx is explicitly marked unused. This exceeds the bare schema but does not provide exact format specifiers (e.g., length constraints), which keeps it at a 4.

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

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

The description opens with a specific verb and resource: 'Predict anomalies in a stored signal using a trained model.' This clearly distinguishes the tool from siblings such as train_anomaly_model, analyze_fft, and estimate_rul, while also naming both inputs (signal and model).

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

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

The description explicitly states prerequisites: 'Requires the signal loaded via load_signal() first and a model trained via train_anomaly_model', and gives the pipeline order. It also implies when not to use the tool via the ValueError for unloaded signals. However, it does not name specific alternatives or explicitly contrast with sibling tools, so it falls short of a 5.

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

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

With no annotations, the description carries full burden. It discloses that max_pages is ignored for TXT files, that pages consume tokens, that ctx is unused, and that FileNotFoundError is raised. It could mention read-only behavior explicitly, but 'Read' implies it; the disclosure of token consumption is a notable behavioral trait.

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 docstring is well-structured with Args, Returns, and Raises sections, and the guidance is front-loaded. The reference to 'this module's docstring on logging' is a minor detour, but overall every sentence serves a purpose and the text is not bloated.

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

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

For a tool with two parameters, no annotations, and an output schema (which the description doesn't need to duplicate), the description covers purpose, usage, parameters, return value, and error conditions. It is complete enough to use the tool safely and effectively.

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 0%, so the description must fully compensate. It provides clear semantics for file_name (location and accepted formats), max_pages (default, ignored for TXT), and ctx (unused). This far exceeds what the schema offers.

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: 'Read a text excerpt from a machine manual (PDF or TXT).' It clearly distinguishes from siblings by adding 'Use for consecutive-page reading; for targeted questions prefer search_documentation.' This directly differentiates it from the related search tool.

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 guidance is provided: 'Use for consecutive-page reading; for targeted questions prefer search_documentation.' Additionally, it advises to start with max_pages=10 and increase only if needed due to token consumption, which is actionable and context-specific.

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

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

With no annotations, the description carries full behavioral disclosure. It reveals the catalog is small by design, mandates source citation, clarifies that a miss is a valid result, describes the return structure (specifications or BearingCatalogMiss), and documents an exception when the catalog file cannot be read. This is comprehensive.

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

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

The description is well-organized with clear Args, Returns, and Raises sections, and it front-loads the purpose. It is slightly verbose in referencing an internal docstring for logging, but the length is justified by the useful behavioral details.

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

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

The tool is simple (one parameter) but the description covers input semantics, output behavior, error conditions, and catalog policy. Even with an output schema, the Returns section adds value by describing the miss object's fields. Complete given the tool's scope.

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

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

The schema only provides a parameter name, type, and required flag with 0% description coverage. The description compensates fully by defining 'bearing_id' as a bearing designation and providing concrete examples ('6205', 'SKF 6205-2RS'), which is essential for correct invocation.

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

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

The description clearly states the tool searches for bearing specifications in a local verified catalog, using a specific verb and resource. It also distinguishes itself from sibling tools by noting it is a fallback when the machine manual names a bearing but lacks geometry, positioning it uniquely among the listed tools.

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

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

The description explicitly names the scenario for use ('Fallback for when the machine manual names a bearing but not its geometry') and provides decision guidance for negative outcomes ('A miss is a legitimate negative outcome — ask the user for the geometry; never guess it'). This goes beyond general context to actionable instructions.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden. It exceeds basic expectations by revealing lazy index building, disk caching, automatic rebuild on source changes, backend fallback (FAISS vs TF-IDF), and the return format including relevance score and chunk index. It also notes the ctx parameter is unused. It does not mention potential performance impacts or error cases, but is notably transparent.

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

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

The description is well-structured with clear sections: purpose, backend details, indexing behavior, arguments, and return value. Every sentence adds value—backend options, caching, parameter explanations, and return fields—without fluff. The core purpose is front-loaded in the first line.

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

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

For a tool with 3 parameters, no annotations, and a provided output schema, this description is self-sufficient. It explains the search scope, retrieval algorithm, backend choices, caching behavior, parameter semantics, and return structure. It also mentions the optional dependency for the FAISS backend, making it complete for an agent to invoke correctly.

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

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

The input schema has zero description coverage, but the description fully compensates with an Args section. It explains query with natural-language examples, top_k as 'Number of passages to return' with default, force_reindex as 'Rebuild the index even if cache is fresh', and ctx as unused. This provides complete semantic meaning beyond the bare schema.

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

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

The description opens with 'Semantic search across all machine manuals and bearing catalogs', a specific verb+resource+scope statement. It further clarifies it uses vector retrieval (RAG) to find relevant passages from PDFs, text files, and JSON catalogs, distinguishing it from sibling tools like read_manual_excerpt or search_bearing_catalog.

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

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

The description provides clear context for usage: natural-language questions or keywords like 'bearing 6205 geometry', and explains the automated backend selection. However, it does not explicitly state when to use this tool over sibling tools such as search_bearing_catalog, nor does it mention exclusions or alternative contexts.

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

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

With no annotations provided, the description fully carries the behavioral disclosure burden. It reveals that the model is trained ONLY on healthy data, fault data is used only for tuning, standardization is fitted on training data only, and it saves model/scaler/PCA. It also discloses the validation strategy and possible ValueError conditions.

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 long but appropriately structured with numbered pipeline steps, bolded section headers, and labeled sections (Args, Returns, Raises). Every sentence adds value, and the key message (unsupervised training on healthy data) is front-loaded.

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

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

Despite the tool's complexity (8 params, pipeline steps, training modes, validation logic), the description covers all essentials. It explains the output (AnomalyModelResult with model paths and metrics), error conditions, and prerequisites, making it complete for an agent to use correctly.

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

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

The input schema has 0% description coverage (only titles/defaults), so the description's 'Args' section is essential. It explains each parameter in detail, including defaults and semantic roles—e.g., fault_signal_ids for hyperparameter tuning, healthy_validation_ids for explicit validation with automatic 80/20 fallback.

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

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

The description opens with a specific verb+resource: 'Train ML-based anomaly detection model on healthy data'. It clearly differentiates from siblings like predict_anomalies and check_bearing_faults by stating it trains an unsupervised/semi-supervised model, and it names the exact algorithms (OneClassSVM, LocalOutlierFactor).

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

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

The description provides a complete pipeline, explicitly states when to use unsupervised vs semi-supervised modes, explains how validation splits work, and warns 'This is NOT supervised learning'. It also instructs to load signals first with load_signal, giving a clear prerequisite and alternative.

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