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 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 provided, the description carries full responsibility for disclosing behavior. It clearly states the destructive nature ('Remove', 'clears the whole cache') and clarifies that operations affect only the in-memory repository. It also explains the return dict (cleared_count, signal_id, status), which is valuable behavioral context beyond what the schema provides. Minor gap: it doesn't explicitly state whether removed signals are recoverable, but the in-memory qualifier helps.

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 concise. It starts with a clear one-sentence purpose, then follows with an Args section and Returns section. Every sentence adds useful information — even the note about `ctx` being unused is relevant for understanding behavior. 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?

Given the tool's simplicity (one optional parameter, output schema present), the description is complete. It covers purpose, parameter semantics, return values, and the in-memory scope. The output schema fills in the exact return structure, so the description doesn't need to repeat it. For a destructive tool with no annotations, it sufficiently informs the agent about behavior.

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 for signal_id is bare (no description, 0% coverage), but the description adds crucial meaning: 'ID to remove; None (default) clears the whole cache.' This explains the parameter's semantics, default behavior, and the distinction between removing a specific signal versus all signals. Without this, the schema alone would be ambiguous.

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.' It clearly states the action (removing signals) and the scope (in-memory repository), distinguishing it from sibling tools like get_signal_info, list_signals, and generate_test_signal which are non-destructive.

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

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

The description implies usage: use this tool when you need to delete signals or clear the cache. It provides context about the default behavior (None clears the whole cache) but does not explicitly mention alternatives or when not to use it. Given that no other removal tool exists among siblings, the guidance is implicit rather than explicit.

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

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

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 full behavioral burden. It thoroughly discloses the graceful degradation behavior, structured refusal for ISO severity (status='refused' with reason and remedy), the rule of never guessing units, and the ValueError condition. This gives the agent critical runtime 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 structured with a summary line, detailed behavior explanation, and an Args block. It is lengthy but every sentence provides necessary information. The only minor loss is slight redundancy in the ISO severity explanation, but it remains readable and efficient.

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

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

Given the tool's complexity and that an output schema exists, the description covers purpose, parameters, behavioral edge cases, error conditions, and output semantics (e.g., the iso_severity block). It leaves no critical ambiguity for an agent deciding to use or 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?

Schema description coverage is 0%, so the description must compensate. It explains every parameter: signal_id, rpm, bearing_id, machine_group, support_type, including enum meanings, defaults, and how to properly declare units via load_signal. This is essential context the schema alone 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?

The description opens with 'Full integrated diagnosis' and lists specific analyses (FFT, PSD, STFT, bearing faults, ISO severity), clearly stating the tool's role as a comprehensive pipeline. This distinguishes it from sibling tools like analyze_fft or compute_power_spectral_density, which are single-purpose.

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

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

The description implies use for complete vibration diagnosis, mentioning loading signals from the repository and synthesizing results into an actionable report. It does not explicitly name alternatives or state when not to use this tool, but the 'full integrated' framing provides clear context for its primary use case.

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 provided, the description carries the full transparency burden and does well: it discloses file writing (data/signals/ with timestamp), companion metadata, auto-registration, and the return value. It does not mention potential overwrite behavior or access requirements, but the timestamped naming implies no overwrites, and these are acceptable gaps for a generation 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 efficiently structured: a one-sentence overview, a paragraph on side effects, a bullet-like list of signal content, and a clear Args/Returns breakdown. Every sentence serves a purpose, no filler, and key information is front-loaded.

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

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

Despite having no annotations, the description provides a complete picture: outputs, files written, auto-registration, signal patterns, parameter details, and return type. It fully covers the complexity of a 5-parameter tool with no schema descriptions, making it self-sufficient.

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

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

Schema description coverage is 0%, so the description must compensate entirely, and it does. Every parameter is explained: signal_type gives all enum values with their waveform patterns, duration notes the resolution trade-off, sampling_rate, noise_level, and random_seed with reproducibility. This adds substantial 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 clearly states the tool's purpose with a specific verb ('Generate'), a resource ('synthetic test signal'), and the full workflow (save, load, auto-register). It distinguishes itself from the many analysis/loading sibling tools by being the only signal-generation 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?

The description clearly implies when to use this tool (to create synthetic test signals for downstream analysis tools), noted by 'immediately usable by every analysis, diagnosis, and ISO severity tool with no manual steps.' It does not explicitly name alternatives or exclusions, but given the sibling set, the usage context is clear.

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

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

With no annotations provided, the description must carry the full burden of behavioral disclosure. It does well by detailing what is returned (StoredSignalInfo with source_metadata populated), the source of that metadata (_metadata.json), the empty-dict fallback, and the ValueError condition. It also notes that ctx is unused. This is transparent and useful, though it does not explicitly state the operation is read-only (which is obvious from 'get').

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 concise summary followed by Args, Returns, and Raises sections. Every sentence earns its place, providing key details without fluff. The main purpose is front-loaded, making it easy for an agent to quickly assess relevance.

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

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

For a simple tool with one parameter and an output schema, this description is complete. It explains the purpose, parameter semantics, return value, and error behavior. The output schema already covers the return structure, so the description does not need to over-explain. No gaps are evident.

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 description for signal_id (0% coverage), so the description compensates by explaining it as 'ID of a signal previously loaded via load_signal.' This adds critical context beyond the raw schema. The mention of ctx is confusing because it does not appear in the schema, but it is clearly marked as unused, so it does not harm overall 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 clear verb and resource: 'Get metadata for a stored signal without loading the full array.' This distinguishes it from load_signal (which loads the full array) and list_signals (which lists signals), making the purpose unambiguous.

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

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

The phrase 'without loading the full array' clearly signals when to use this tool instead of loading the entire signal. It also states a prerequisite: signal_id must be from a signal 'previously loaded via load_signal.' However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a perfect score.

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 fully discloses behavioral traits: atomic batch fail-fast behavior, automatic signal_id derivation, overwrite semantics, raw decode contracts, unit declaration requirements, channel suffix behavior, and explicit refusal of raw params for self-describing formats. It also lists all exception conditions and return formats, providing complete 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 lengthy but appropriately so for a tool with 11 parameters, batch behavior, raw decoding, and complex edge cases. It is well-structured with clear paragraphs, an Args list, Returns, and Raises sections. The core purpose is front-loaded, and each sentence contributes meaningful information 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?

Given the tool's complexity and the lack of annotations or schema descriptions, the description is remarkably complete. It covers parameter semantics, return values, error scenarios, and the broader load->analyze->diagnose->report flow. The output schema exists but the description still explains StoredSignalInfo for single and batch loads, making it self-sufficient for correct invocation.

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

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

Despite 0% schema description coverage, the description extensively documents every parameter: filepath for single or batch, signal_id custom vs derived, sampling_rate and signal_unit overrides, raw file parameters with defaults, and overwrite behavior. It explains relationships between parameters (e.g., raw parameters broadcast in batch) and provides context for each one, fully compensating for the missing 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 explicitly states the tool's function: 'Load one signal — or a batch — into the in-memory repository.' It clearly distinguishes this from sibling tools like list_signals or get_signal_info by focusing on the loading operation and the subsequent flow of using signal_id. The verb 'load' and resource 'signal' are specific and unambiguous.

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

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

The description provides strong usage context: it explains that once loaded, the signal is referenced by signal_id in every analysis, diagnosis, report, and prognostics tool, positioning this tool as the entry point for data ingestion. It details batch usage, raw file handling, and metadata merging, making the when-to-use clear. However, it does not explicitly name sibling tools as alternatives or state when not to use this tool, which prevents a perfect score.

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.