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

The description states 'PERSIST' and 'Writes a local owner-only advisory JSON file,' which directly contradicts the readOnlyHint=true annotation. This is a critical inconsistency that misleads the agent about whether the tool modifies state.

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 (Args, Returns, Example) and every sentence provides essential information. It is dense but not verbose, and the example aids 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?

Despite no output schema, the description explains the return dict, overwrite behavior, ownership, and safety profile, plus gives an example. This makes the tool's behavior and usage fully understandable.

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

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

With 0% schema description coverage, the description fully compensates: it defines the feeds argument's shape, the site argument's format and default, and provides a concrete example. 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 specific verb and resource: 'Adopt + persist the canonical alias map for a site.' It clearly distinguishes this from siblings like diff_alias_map by focusing on adoption and persistence, and it explains the map's structure and 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 when to use the tool (to adopt and persist a canonical alias map) and provides context about it being advisory and non-OT-device-write. However, it does not explicitly mention when not to use it or name a direct alternative.

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

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

Annotations already indicate read-only, non-destructive behavior, and the description adds meaningful context: it explains that window_minutes is inferred if omitted, defines chatter_window_s and standing_s, and details the return structure. This goes beyond simply echoing 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 a terse purpose line, labeled Args and Returns sections, and a concrete example. Every sentence adds value without redundancy, and the front-loaded purpose makes it immediately scannable.

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

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

With no output schema, the description takes on the burden of explaining the return dict in detail, listing all keys and example values. For a tool with 5 parameters and a complex result set, this is remarkably complete, even including a usage example.

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's Args section fully explains each parameter's meaning and default behavior (e.g., 'chatter_window_s: A source with >=3 transitions inside this window chatters'). It completely 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 'ISA-18.2 alarm-flood analysis over a list of alarm events' and elaborates with specific outputs like 'top offenders', 'chattering', and 'standing'. This distinguishes it from siblings such as alarm_flood_analysis or alarm_cascade by focusing on 'bad actors' (source-level 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?

The description provides clear context on what the tool does and its inputs, making its intended use apparent. However, it does not explicitly mention when not to use it or reference alternative sibling tools, so it lacks explicit 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds valuable behavioral context beyond that: it reveals the first-out heuristic is 'transparent' and 'cited by timestamp — NOT causal,' notes the tool is 'bounded,' and explains it collects live via the 'OPC-UA active-condition scan.' This enriches the agent's understanding beyond the structured 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 sections for Args, Returns, and Example, and the opening line is an immediate purpose statement. It is longer than some descriptions, but every sentence adds necessary detail for correct usage. Slightly verbose but not wasteful, earning a 4.

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 (5 parameters, no schema descriptions, no output schema), the description is comprehensively complete. It covers the return dict structure with all nested fields, explains the cascade logic, clarifies the heuristic nature, and provides a concrete example. This gives the agent everything needed to invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description carries full responsibility for parameter meanings. It does this excellently by explaining each parameter: 'endpoint', 'duration_s' (with range 1..300), 'window_s' (quiet gap), 'min_cascade', and 'events' (with format {source, timestamp, state?}). It also provides an example call, making usage 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 clearly states the tool's function: 'Collapse an alarm flood into cascades + each cascade's first-out root.' This uses a specific verb ('collapse') and resource ('alarm flood'), and it precisely answers the question 'which alarm to look at first.' It also distinguishes itself from sibling tools like 'downtime_root_cause' by explicitly stating it is a heuristic, not causal.

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 explicit usage context: 'when 100+ alarms hit in minutes' and explains the tool answers 'which alarm to look at first.' It clearly differentiates from alternatives by stating 'NOT causal (use downtime_root_cause for causality)' and clarifies when to use live collection vs. pure analysis with 'Pass 'events' for pure analysis, or an endpoint to collect live.'

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

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

Annotations already mark the operation read-only and non-destructive, but the description adds substantial behavioral detail: exact equality after normalization of case, punctuation, and embedded numbers; events without message text are excluded from shares; and each cluster retains distinct wordings and sources. It also explicitly states what the tool does NOT claim, preventing over-interpretation of cluster meanings.

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 opens with a one-line summary and risk marker, explains motivation and algorithm, details all three parameters, and lists the return structure. The contrast with alarm_bad_actors is front-loaded, and the example grounds the explanation without bloat.

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 there is no output schema, the description compensates by fully specifying the return dict fields, including clusters, signatures, counts, shares, distinct wordings, and sources. It also addresses edge cases like events without text and one-off clusters. Combined with the sibling context and annotations, an agent has everything needed to select and invoke this 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 fully carries the burden. It explains the events parameter with accepted message field aliases, top_n with default and cap, and min_count with default and behavior. It even provides a concrete example call showing expected parameter shapes.

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 line states a specific action and resource: 'Collapse ten phrasings of one fault into one row.' The description then explicitly contrasts this with alarm_bad_actors, clarifying that this tool answers 'which fault is noisiest' rather than 'which instrument is noisiest.' This clearly differentiates it from the closest sibling.

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 concrete when-to-use context: when multiple wordings of the same underlying fault inflate a bad-actor list. It names the alternative alarm_bad_actors and explains the distinction in terms of SOURCE versus message content. It also cautions that clustering is exact-equality based, not semantic similarity, so a human must decide whether different wordings mean the same thing.

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?

Even with annotations indicating readOnly/openWorld/non-destructive, the description adds substantial behavioral depth: it never applies suppression/shelving/deadband/delay changes, output is bounded with truncation flags, and live collection is limited to the OPC-UA active-condition scan. This goes far beyond the annotations and explains non-obvious side effects and limitations.

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?

Though long, the description is efficiently structured: a one-line summary, a detailed paragraph, then Args/Returns/Example sections. Every sentence adds information; there is no filler or tautology. The density is warranted for a tool with 9 parameters and a rich output shape.

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

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

There is no output schema, so the description's detailed 'Returns dict' fills the gap with field names and nested structures. It also covers collection methods, advisory semantics, truncation behavior, and supplies a concrete example. For a complex analytical tool, this is a complete and self-sufficient specification.

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 all 9 parameters with meanings, defaults, and relationships (e.g., 'endpoint used only when events is omitted', 'events skips live collection entirely', 'stale_after_s: Continuously-active age that marks a standing alarm'). This adds critical semantics the schema lacks.

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

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

The description opens with a specific verb and resource ('ISA-18.2 deep alarm-flood analysis') and lists concrete outputs (episodes, chattering, stale, advice). It explicitly differentiates from the sibling tool alarm_bad_actors by stating 'Deepens alarm_bad_actors', making the tool's unique scope unmistakable.

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

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

Provides clear situational guidance: 'Pass events for pure analysis, or an endpoint to collect live' and warns that 'other protocols contribute no alarms' (an explicit exclusion). The advisory-only caveat tells the agent this tool is not for applying changes, effectively distinguishing it from mutation-oriented siblings.

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

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

The description opens with [READ][risk=low] and adds rich behavioral context beyond the readOnly/destructive annotations: it discloses live OPC-UA collection, CSV file writing when out_path is set, bounded inline rows with truncation noted, and that endpoint is used only when events are omitted. This exceeds what annotations alone convey and does not contradict them.

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

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

The description is well-structured with a summary, Args, Returns, and Example, and it front-loads safety tags. It is somewhat lengthy but necessary given the lack of schema descriptions; there is minimal 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 6-parameter tool with no output schema, the description is complete: it explains input modes, output dict shape, CSV side-effect, truncation behavior, defaults, and provides an example. An agent has everything needed to invoke the tool correctly.

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

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

The input schema has 0% property description coverage, so the description must carry the burden, and it does thoroughly. The Args section explains all six parameters with purpose, defaults, constraints (e.g., duration_s 1..300, default 60; window_s default 600; threshold default 10), and the expected structure of events. This is exemplary compensation for schema gaps.

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 produces an ISA-18.2 alarm-rationalization worksheet (CSV or inline rows), with specific columns and count-descending ordering. It distinguishes itself from sibling alarm tools by framing itself as the starting document for rationalization review and explaining both event-based and live-endpoint modes.

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

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

It gives clear context: pass 'events' for pure analysis or provide an endpoint to collect live via the OPC-UA scan, and use 'out_path' to write CSV versus inline rows. However, it does not explicitly name sibling alternatives or state when not to use this tool, 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?

Beyond the readOnlyHint and destructiveHint annotations, the description discloses that it samples over a bounded window, computes mean/stddev/min/max, flags outliers using sigma, and does not persist models. It also notes server-side capping of samples, adding meaningful behavioral context.

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 compact and well-structured: a deprecation notice, a clear one-line summary, a brief algorithm explanation, and a concise args list. Every sentence adds value without unnecessary verbosity.

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 the tool's purpose, algorithm, limitations, and all parameters. Although there is no output schema and the return format isn't explicitly described, the tool's behavior is sufficiently clear for a read-only statistical scan. The deprecation notice makes completeness slightly less critical.

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 descriptions for its 5 parameters, but the description compensates fully with an Args section explaining each parameter's purpose (node_id, endpoint, samples, interval_ms, sigma). This provides complete semantic 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 explicitly states it performs a statistical outlier scan on an OPC-UA node, with a specific verb and resource. It also clearly marks itself as deprecated in favor of opcua_anomaly_scan, distinguishing it from that alternative.

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 deprecation notice explicitly directs users to opcua_anomaly_scan instead of this tool, providing a clear alternative. It also clarifies the tool's scope ('Simple statistics only — no ML, no persisted model'), implying when it is appropriate.

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

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

Annotations already mark readOnlyHint=true and destructiveHint=false, but the description adds meaningful context: the tool connects to endpoints via its own protocol client and reads identity calls. It also warns about reachability constraints and labels risk as low, going beyond the structured 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?

Information is front-loaded with [READ][risk=low], followed by a concise explanation, an honest scope note, parameter guidance, return structure, and example. Every sentence adds value and the format is easily scannable.

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

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

With no output schema, the description fully specifies the return dict including all fields such as asset_count, reachable_count, method, and asset details. It covers scope, parameters, example, and edge cases (unreachable endpoints), making it complete 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?

Although schema description coverage is 0%, the text fully explains the only parameter: 'endpoints: Endpoint names to fingerprint; omit to fingerprint ALL configured endpoints.' The example further clarifies 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?

Description opens with a specific verb+resource: 'Actively fingerprint endpoints into an asset register.' It then lists concrete protocol identity calls and explicitly distinguishes active fingerprinting from passive SPAN/tap discovery, clearly separating it from sibling 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?

Provides explicit scope boundaries: 'ACTIVE fingerprinting (we connect to each device), NOT passive SPAN/tap discovery' and 'Only finds devices we are configured to reach.' It also explains the optional endpoints parameter, giving the agent clear guidance on when to omit it.

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

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

Beyond the annotations (readOnlyHint true, destructiveHint false), the description discloses critical behavior: it reads from a local database with no device I/O, reports violations only under specific conservative conditions (3×MAD and sustained for 3+ samples), handles missing baselines with an explicit 'no_baseline' response, and bounds output size. 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 well-structured and front-loaded with the core purpose, followed by behavioral details, parameter definitions, return format, and an example. Every sentence adds value, and the 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?

Despite no output schema, the description explicitly lists the return dict structure and fields. It covers parameters, behavior, edge cases, and output bounds, making it fully self-contained for an AI 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?

With 0% schema description coverage, the description fully compensates by explaining each parameter: tag (with example), endpoint (label filter), and window_s (range and default). It also provides a concrete usage example, making the parameters unambiguous.

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: 'Check recent local samples against the learned baseline.' It uses a specific verb ('check') and resource ('samples against baseline'), and differentiates itself from sibling tools like baseline_learn and baseline_status by focusing on anomaly detection against a stored baseline.

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 on when to use the tool (checking recent samples for baseline violations) and explains its conservative detection policy. It does not explicitly name alternative tools or exclusions, but the context strongly implies this is the go-to for anomaly checking, especially with siblings like baseline_status for status inquiries.

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

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

Annotations already flag read-only, but the description adds the crucial unknown_context refusal, the no-borrowing rule, margin_mad × MAD and sustain_n requirements, and the fact that flags cite their baseline. It also explains why the response lists known_contexts, making the tool's behavior genuinely predictable.

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 section earns its place: purpose, critical refusal behavior, rule thresholds, Args, return shapes, and an example. The risk tag and core action are front-loaded, and the structure is easy to scan.

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 no output schema, the description fully specifies both known-context and unknown_context return shapes, plus example usage. An agent has enough to decide whether and how to invoke the tool correctly, including what happens for unlearned contexts.

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

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

With 0% schema coverage, the description carries full responsibility and does so thoroughly: every parameter is explained, including the relationship between contextual and baseline_learn_contextual, the shape of samples, and the meaning/defaults of margin_mad and sustain_n. This far exceeds the bare schema titles.

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

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

Opens with a specific verb/resource and scope: 'Check readings against the band for ONE declared context.' It also draws an explicit contrast with uncontextual or nearest-band behavior, so an agent can distinguish it from baseline_check and other 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 makes clear this tool is for checking samples against one declared contextual band and expects a baseline_learn_contextual result, but it never names an alternative tool to use for global or non-contextual checks. That gives clear context without explicit 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?

Despite readOnlyHint=true, the description honestly discloses that successful calls persist the band to ~/.iaiops/baselines.json, adding important context about a local write side effect. It also details algorithm behavior (percentiles, no ML), refusal conditions, and the guarantee that it 'never invents a band from thin data', going well beyond the annotations.

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

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

The description is well-structured with clear sections: intro, source, algorithm, refusal, persistence, args, returns, and example. Every sentence adds value, and the length is justified by the tool's complexity. The upfront '[READ][risk=low]' provides an immediate safety signal.

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

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

With no output schema, the description fully specifies the return dict fields, including status, band components, n_samples, window, segment, and optional missing list. It covers all necessary invocation context (source, algorithm, refusal, side effects, parameters, example), making it complete for an AI agent to select and call 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 schema has zero descriptions, so the Args section compensates by explaining each parameter: tag with example, endpoint as a label filter, and since as an ISO-8601 time filter. The example call further disambiguates usage, though the descriptions are brief and do not specify all edge-case behaviors (e.g., null for endpoint).

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

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

The opening sentence 'Learn a conservative per-tag normal band from local history' uses a specific verb and resource, precisely stating what the tool does. It further distinguishes itself from live device reads and references related tools like baseline_record_change and historian_push, setting it apart from siblings.

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

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

The description explicitly states the data source is '~/.iaiops/data.db' written by historian_push and stresses 'NOT a live device read', clearly indicating when not to use it. It also gives concrete refusal thresholds (100 samples or 24h span), telling the agent exactly when the tool will reject insufficient data, and mentions the dependency on baseline_record_change for segmentation.

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

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

Goes well beyond the readOnly/destructive annotations by explaining refusal behavior for thin contexts, counting rather than pooling uncontexted samples, and deliberately avoiding a default fallback bucket. It even discloses why there is no `--context` CLI wiring due to the local store 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 longer than typical but every paragraph carries meaningful design rationale or invocation detail, and it is well structured with Args, Returns, and an Example. The dryer example earns its place by clarifying the failure mode the tool avoids.

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

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

For a read-only learning tool with no output schema, the description provides the full return dict shape, parameter semantics, example call, and behavioral edge cases such as refused and uncontexted contexts. Nothing important 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?

With 0% schema description coverage, the description fully compensates by documenting the sample row shape, `tag`, `context_key` as the declared-context field, `min_samples` as a per-context minimum, and `min_span_s` as a per-context history span with defaults. This gives the agent everything it needs beyond the raw JSON schema.

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

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

States a precise verb and resource: 'Learn one conservative band per declared context, not one per tag.' The dryer example and contrast with per-tag learning make it clearly distinguishable from siblings like `baseline_learn`.

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

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

Clearly describes when contextual baselines are needed: when a tag has multiple normal regimes due to shift, product/recipe, or start-up vs steady state. It also explains that contexts must be declared, not inferred, and shows how to pass samples, but it does not explicitly name the sibling alternative to use instead or provide an explicit 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?

Annotation Contradiction: the description explicitly says 'Writes ONLY local metadata' and 'Record an operator change-log entry', which is a side-effecting write, while annotations set readOnlyHint=true. Although the description is otherwise transparent about file path, owner-only access, and no OT device write, the contradiction requires a score of 1.

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 purpose line, safety note, behavioral explanation, args, return, and example. It is relatively long, but each section provides necessary domain context and the [READ][risk=low] prefix front-loads key information.

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

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

The description is highly complete: it names the local metadata file, explains why no OT device write occurs, describes the return dict, gives an example, and explains the impact on baseline_learn. Since there is no output schema, explicitly documenting the return format is especially valuable.

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 carries the burden. The Args section clarifies 'tag' as the process tag and 'note' as what changed, with concrete examples ('line1.temp', 'setpoint 60→70C'), adding meaningful semantics beyond the bare schema 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 clearly states 'Record an operator change-log entry for a tag (local only)' — a specific verb and resource. It distinguishes itself from siblings like baseline_learn by explaining that a recorded change marks a regime boundary and that baseline_learn uses only samples after the latest change.

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

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

The description explains when to use the tool (after an operator change such as a setpoint move or valve replacement) and explicitly contrasts it with baseline_learn. It lacks an explicit 'do not use when...' list, but the intended context is clear enough.

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 goes well beyond the annotations by explaining the exact status values ('no_baseline', 'learning', 'ok', 'violation'), that it never guesses, reads only from local store, and lists are bounded to 100 entries. It also describes the return shapes for both one-tag and all-tag cases. No contradiction with readOnlyHint=true.

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 header, a concise explanation of behavior, an Args section, a Returns section, and an example. Every sentence contributes useful information without redundancy or fluff.

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 optional parameter and no output schema, the description is fully complete. It covers input, output shape, status meanings, listing behavior, bounded entries, and provides an example invocation. No important information is missing for an agent to use 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 input schema provides only the parameter name 'tag' with a default of null, but no description. The description explains that the tag is optional and omitting it lists all tracked tags. It also clarifies how the parameter affects the return value, adding meaning beyond the schema.

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

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

The description clearly states that this tool returns baseline status for one tag or a bounded listing of all tags. It uses a specific verb ('status') and resource ('baseline'), and distinguishes itself from sibling tools by emphasizing read-only local store access and no device I/O.

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 that this is a read-only status query operating only on the local store with no history scan or device I/O. It does not explicitly mention alternatives or when-not-to-use, but the context is sufficient to know when it is appropriate.

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

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

Annotations already mark it as readOnlyHint=true, and the description reinforces that it is 'read-only, advisory' and 'Pure analysis.' It explains the data requirement (good parts stream) and output structure. No contradictions.

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?

While well-structured with summary, args, returns, and example, the description is verbose. It includes repetitive phrases ('worst-first, each duration cited by its two bounding timestamps') that could be tightened. A 3 reflects adequate but not optimal conciseness.

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

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

With one required parameter and no output schema, the description covers all necessary context: input format, output dict structure with example, and clarifying notes. It is fully sufficient for an agent to use 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 coverage is 0%, but the description provides a detailed parameter description: 'good_parts: [{timestamp (ISO-8601), product}]' with ordering notes and an example. This fully compensates, making the parameter's semantics crystal 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 clearly states it analyzes changeover/SMED durations between products. It explains what it measures (gap between last good part and first good part of next product) and how it relates to OEE. This distinct purpose makes it clear among sibling tools like oee_compute and downtime_events.

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 specifies it works on a 'good-part completion stream' and labels it 'read-only, advisory.' It contrasts with OEE availability aggregations. However, it does not explicitly state when not to use it or list alternatives, 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?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral context by stating it offers an 'honest iaiops posture' with per-control status/gap, and emphasizes it is not a certification. This goes beyond the annotations and provides insight into the tool's output reliability and scope.

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 well-structured, starting with a clear summary line before diving into details. The Args and Returns sections are clearly labeled and the example is useful. Every sentence adds value, though a bit of density could be trimmed without loss.

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

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

There is no output schema, so the description carries the full burden of explaining returns. It does so by explicitly listing the keys of the returned dict (framework, levels, selected_level, pillar_count, deltas, note) and describing the delta structure. Coupled with parameter details and an example, the tool is fully specified for an agent.

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 defines 'level' as a string/null with no values, giving 0% coverage. The description fully compensates by listing accepted values ('l2'/'l3', '二级'/'三级', or '2'/'3') and explaining the default behavior when omitted (both levels). The example further clarifies 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's function: comparing 等保 2.0 二级 vs 三级 per-pillar deltas and iaiops posture. It explicitly says it is an onboarding/self-assessment aid, not a certification, which distinguishes it from sibling compliance tools like compliance_mapping or compliance_report. The verb and resource are specific.

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

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

The description gives clear context for when to use the tool: as an onboarding/self-assessment aid, and clarifies what it is not for (certification). It also explains how to pass the level argument with accepted values. However, it does not explicitly name alternative tools or provide when-not-to-use guidance beyond the certification disclaimer.

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

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

Beyond the readOnlyHint=true annotation, the description discloses deterministic packaging, upstream secret redaction, path traversal validation with '..' rejection, parent directory creation with 0700 permissions, and a complete return dictionary. These are nontrivial behavioral traits that meaningfully inform an agent about side effects and safety.

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 line, file list, argument definitions, return value, and example. Every sentence contributes functional knowledge without fluff, and the front-loaded [READ][risk=low] tag aids quick classification.

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 lacking an output schema, the description defines the exact return dict structure, all parameters, validation behavior, and a usage example. It is sufficiently complete for an agent to invoke the tool correctly and interpret its result.

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

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

The schema provides no descriptions and has 0% coverage, so the description carries the full burden. It explains out_path must end in .zip, defines since/until as ISO-8601 inclusive bounds, and provides a concrete usage example. This fully compensates for the empty 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 specific verb-resource pair ('Export the audit-evidence bundle (zip) for an auditor') and details the deterministic zip contents, clearly differentiating it from generic export or compliance reporting tools. It names the exact output artifact and its 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 phrase 'for an auditor' gives clear context on when to use the tool, and the detailed contents imply it is for governance/audit evidence packaging rather than general data export. It does not explicitly name alternatives or exclusions, but the context is strong enough to guide selection.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds a redundant '[READ][risk=low]' tag without new safety info. However, it does add context about the output containing 'current iaiops status' and positions the tool as a companion to compliance_mapping with a different perspective, which is useful behavioral context beyond the annotations.

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

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

The description is well-structured: a concise summary, detailed mapping explanation, return schema, and example. Every sentence contributes meaning without fluff, and the length is appropriate for the complexity of the tool.

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

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

For a read-only, zero-parameter tool, the description is complete. It explains the purpose, return format, example invocation, and relationship to the sibling compliance_mapping. The lack of an output schema is compensated by the detailed dict structure provided in the 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?

With zero parameters and an empty schema, the description adds value by showing an example call `compliance_frameworks()` and detailing the return dict structure. This clarifies that no arguments are needed and what the response will contain, fully compensating for the lack of schema detail.

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

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

The description clearly states the tool's function: cross-framework mapping between 防护指南, 等保 2.0, and IEC 62443. It explicitly distinguishes itself from compliance_mapping by noting it provides a high-level crosswalk for answering which clause satisfies what, making it a distinct sibling 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 provides explicit usage guidance: 'use this to answer which 等保 / 62443 clause does this satisfy'. It also names compliance_mapping as the alternative for per-control gaps, offering clear when-to-use versus when-not-to-use direction.

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

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

Annotations already declare readOnlyHint=true and low risk, and the description echoes '[READ][risk=low]' consistent with annotations. It adds behavioral context by detailing the return dict structure and honest status values, which helps the agent understand the output shape. It does not disclose any side effects or prerequisites, but with annotations covering safety, this is acceptable.

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 well-structured: it opens with the mapping scope, lists pillars, describes the return format, and closes with an example. Each sentence contributes useful information, though a slightly terser phrasing could improve conciseness without losing substance.

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

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

With no parameters and no output schema, the description compensates by fully spelling out the return dict structure and providing an example. It also cross-references compliance_frameworks for further context. The main gap is a lack of explicit error handling or when-to-use guidance, but given the tool's simplicity, this is largely 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 input schema has zero parameters, so the baseline is 4 per the rubric. The description adds meaning by showing the exact invocation example `compliance_mapping()` and clarifying that the tool takes no arguments, which is helpful for correct 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 maps a specific standard (《工控系统网络安全防护指南》) to iaiops governance, with specific pillars and status taxonomy. It distinguishes itself from the sibling compliance_frameworks by focusing on this one framework, 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 description provides an explicit alternative reference: 'See compliance_frameworks for the full cross-framework 对照,' which guides users needing broader coverage. However, it does not explicitly state when to prefer this tool over other compliance siblings, so the guidance is clear but not exhaustive.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, destructiveHint), the description adds substantial behavioral details: the '[READ][risk=low]' prefix, the full report contents, truncation behavior with a hint to pass `out_path`, and the exact return dict structure. It also clarifies the tool is not a certification, enriching the agent's understanding of side effects and limitations.

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 (summary, Args, Returns, Example). Every sentence adds value—no fluff or tautology. The length is justified by the tool's complexity and the need to convey truncation behavior, return format, and parameter semantics.

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

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

Given the tool has 3 parameters, no output schema, and no enum constraints, the description covers all essential context: what the report contains, return dict fields, truncation behavior, and a concrete example. The agent can confidently select and invoke this tool without additional documentation.

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

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

With 0% schema description coverage, the description fully compensates by explaining each parameter: `level` with accepted values ('l2'/'l3', '二级'/'三级', '2'/'3', omit for both), `site` as the name stamped on the title page, and `out_path` as a required file path when the report exceeds the inline bound. It even provides an example call, making parameter usage unmistakable.

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: 'Render the 等保 2.0 / IEC 62443 compliance report (Markdown)'—clearly stating the tool's purpose. It distinguishes itself from sibling compliance tools by emphasizing it produces a deliverable document for a CISO and explicitly notes it is 'NOT a certification', setting it apart from raw mapping or evidence 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 clear usage context: it is an 'onboarding/self-assessment aid' and includes an explicit exclusion ('NOT a certification'). It also gives actionable guidance on when `out_path` is required (when report exceeds ~400 lines). However, it does not explicitly name alternative tools from the sibling list, so it stops short of full 5-level guidance on when to use alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral depth: the 'OT-dangerous' warning that aliases are never server-side renames, the re-classification using the same semantic classifier as OPC-UA, and the grouping behavior across protocols. The explicit 'Advisory only' caveat is exactly the kind of contextual disclosure beyond annotations that helps an agent trust the tool's 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 long but effectively structured with a bolded purpose statement, safety advisory, then structured Args/Returns/Example sections. Every sentence contributes either operational semantics, parameter details, or output format. The front-loaded '[READ][risk=low]' tag and clear examples make it easy to scan. No filler or repetition.

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

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

Given the tool's complexity and lack of an output schema, the description is remarkably complete. It specifies the return dictionary's structure including all keys and nested fields, provides an example call, and mentions the two upstream tools that produce valid 'feeds'. The advisory nature and site prefix behavior are also covered, leaving little ambiguity for an agent deciding whether and how to call it.

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

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

With 0% schema_description_coverage, the description fully compensates. It explains the 'feeds' parameter in detail: each element has {protocol, source, asset?, tags:[...]}, clarifies the possible tag sources (OPC-UA descriptors, Modbus template tags, or normalized tags), and describes how a feed-level 'asset' applies to tags. It also documents the 'site' parameter with a default value. This goes far beyond the minimal schema and enables 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 starts with a clear verb phrase 'Fuse per-protocol tag feeds into ONE unified asset model.' This specifies exactly what the tool does (fusion/unification) and the resource (per-protocol tag feeds). It also distinguishes itself from per-protocol tools by name (OPC-UA, Modbus) and mentions upstream tools like opcua_discover_tags and modbus_apply_template, establishing a unique role among 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 clearly frames when to use this tool: when unifying per-protocol tag feeds into a cross-protocol model. It also gives essential context by stating 'Advisory only' and that aliases are suggestions, not server-side renames, which informs appropriate use. However, it does not explicitly list alternative tools or say 'use X instead when...', so it stops short of full exclusion guidance.

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

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

Despite annotations already declaring readOnlyHint=true and destructiveHint=false, the description adds substantial behavioral context: it states 'Pure analysis,' details the exact return dict structure, explains deterministic 'now' for reproducibility, and clarifies that staleness budgets are per-tag/per-feed. This goes well beyond the annotations and provides valuable operational detail.

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: a one-paragraph summary of the tool's purpose and behavior, followed by a structured Args list, Returns dict, and a concrete example. Every sentence adds value, and the length is appropriate for the tool's complexity. It is front-loaded with the core 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?

Given the tool's complexity and lack of output schema, the description is remarkably complete: it covers input structure, return fields, examples, and configuration nuances (slow vs. fast feeds). It also mentions deterministic 'now' for reproducibility, which is helpful for testing. No significant 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?

With 0% schema description coverage, the description fully compensates by providing an in-depth Args section that explains each parameter, including nested structure for 'feeds' with optional fields, the fallback behavior of 'default_staleness_s', the purpose of 'now', and the default for 'top_n'. An example usage further clarifies 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 the tool's function: 'Cross-endpoint fleet rollup of data-TRUST: worst tags + bad quality.' It specifies a concrete verb ('rollup') and resource ('data-TRUST'), distinguishes itself from siblings like data_quality_scorecard by emphasizing a fleet-wide view, and lists distinct outputs (endpoint ranking, bad-quality rollup, liveness rollup).

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 contextual guidance: 'Builds on data_quality_scorecard to give a fleet-wide view' and explains that staleness/gap budgets are configurable per tag to handle different feed types. However, it does not explicitly state when NOT to use this tool or name alternative tools for single-endpoint analysis, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral detail: scoring criteria (staleness, dead heartbeat, quality, flatline, gaps, anomaly), deterministic 'now' handling, and the explicit limitation that it does not evaluate whether values are alarming. These details go well beyond what annotations convey.

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

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

The description is long enough to cover a complex tool but every sentence serves a purpose: summary, exclusion, parameter details, return structure, and example. It is well-structured with labels and a clear example, keeping all information directly usable.

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 sparse input schema, absence of output schema, and presence of closely related sibling tools, the description is remarkably complete. It documents the expected feeds structure, parameter defaults, return dict contents, and a usage example, leaving no significant gaps 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%, so the description carries the full burden, and it succeeds by fully specifying the structure of 'feeds', explaining defaults for 'default_staleness_s' and 'now', and providing a concrete example call. The parameter semantics are thoroughly compensated.

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 a specific verb ('Scores') and resource ('data-TRUST scorecard across endpoints' tag feeds'), and explicitly distinguishes itself from process health by noting it assesses trustworthiness, not alarming values. This effectively differentiates it from sibling tools like health_summary and anomaly_scan.

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 when-not-to-use exclusion ('NOT process health') and states it is 'Pure analysis over provided feeds.' However, it does not explicitly name alternative tools or state 'use this when X' beyond the inherent purpose, 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?

Annotations already declare readOnlyHint and openWorldHint, and the description aligns with them without contradicting them. It adds substantial behavior beyond annotations: four verdicts, the 'absent means nothing known' semantics, the strict library-file validation ('one bad entry refuses the whole file'), and the explicit refusal to infer vulnerability or severity.

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 and includes a somewhat discursive OT-site anecdote, but the extra length is all relevant: it prevents misuse by over-eager agents. The structure is front-loaded with purpose, then warnings, verdicts, parameters, returns, and example, so an agent can stop after the first section if needed.

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 no output schema and 0% schema coverage, the description is unusually complete. It documents the exact return dict fields, the verdict semantics, the advisory library format, the absent-device behavior, the read-only safety profile, and usage prerequisites. No critical call-time information is missing.

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

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

Schema coverage is 0%, so the description carries the full burden, and it delivers. It explains the shapes of `devices` and `library_path`, lists the advisory entry fields, enumerates the affected-range field options, and includes a concrete example call. Without this, the schema's minimal types would leave agents guessing.

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

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

The opening line names a specific verb and resource: 'Which scanned devices fall inside a mounted advisory's stated range.' It also distinguishes itself from a vulnerability scanner by insisting it reports range membership only, not 'vulnerable' or 'exploitable'. This is clear and unique among the 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?

It gives clear usage context: it closes the loop after `iaiops scan` has read vendor/model/firmware/serial, and it deliberately stops short of vulnerability scanning. It does not name an explicit alternative sibling tool, but it provides enough context to know when this tool is appropriate and what it will not do.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and the description reinforces with '[READ][risk=low]'. It goes far beyond annotations by detailing the probe sequence (connect → read(ref) → freshness → variance) and disclosing that it returns per-hop detail and a recommended action. This gives the agent a clear mental model of what happens during invocation.

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

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

Although the description is longer than typical, it is tightly structured with a clear READ/risk header, a concise behavioral summary, a bulleted Args list, a Returns dict format, and an example. Every sentence adds information—there is no filler or redundancy. The front-loading of the core purpose and verdict taxonomy makes it scannable.

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 has no output schema, so the description must explain the return contract—and it does, listing the exact verdict strings and the structure of hops. It also covers edge cases (omitting ref, injecting series for flatline analysis) and provides a concrete example. For a moderately complex diagnostic tool, this is fully self-contained.

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 carries the parameter documentation load. Each of the five parameters is explained with type, purpose, and default behavior (e.g., 'ref: Tag/node/address/device to read... Omit to test connectivity only', 'freshness_threshold_s: Max value-age (seconds) before stale'). This is exemplary compensation for the empty 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 specific verb and resource: 'Localize a 'no data' break across an endpoint's reachable hops.' It clearly distinguishes this tool from siblings by naming it the '#1 OT triage' and enumerating distinct failure-mode verdicts (cannot_connect, comms_ok_value_stale, comms_ok_flatline), which differentiates it from generic health or anomaly 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 gives clear context: use when there is a 'no data' break, and explains that it distinguishes network/PLC down, stale values, and flatline. It also provides an actionable usage hint ('Omit ref to test connectivity only'). It does not explicitly name alternative tools or state when not to use it, 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.