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?

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?

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?

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

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

While annotations already declare readOnlyHint=true and destructiveHint=false, the description adds behavioral context by explaining that the tool 're-runs the cross-protocol asset model over feeds' and reports how the address space moved. It also discloses the return structure with counts and lists, which is valuable beyond the annotations. There is no contradiction with annotations.

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

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

The description is well-structured and front-loaded: it opens with a concise one-line summary, then explains the process, defines arguments, describes the return dict, and provides a concrete example. Every sentence adds useful information 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?

Given that there is no output schema, the description includes the full return dict structure with counts and lists, which is important for the agent. It also gives a full example invocation. The main gaps are the site default inconsistency and the fact that 'feeds' format is only described by reference to 'adopt_alias_map,' which might require the agent to look up that tool's schema. Overall, the description is robust.

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 description coverage, so the description must compensate for parameter meaning. It explains 'feeds' as fresh per-protocol tag feeds of the same shape as adopt_alias_map, and 'site' as the site label whose baseline to diff against, defaulting to 'site.' This adds meaning not present in the schema, but the description relies on referencing another tool's shape for 'feeds' and there is a minor discrepancy: the schema default for 'site' is null, while the description says default is 'site.'

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 '[READ][risk=low] Diff a fresh discovery run against the adopted baseline,' which clearly states the tool's function with a specific verb (diff) and resource (alias map). It distinguishes itself from the sibling tool 'adopt_alias_map' by explaining it diffs against an adopted baseline, 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 explicit usage context by stating 'Adopt a baseline first with adopt_alias_map,' which is a clear prerequisite. It also describes the categories of output (added, removed, renamed, reclassified) and the stable|changed verdict, implying when this tool is appropriate. It does not explicitly mention alternatives, but the prerequisite and operational detail offer solid guidance.

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

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

Annotations already mark the tool as read-only and non-destructive. The description adds that it is low risk and details the return dictionary structure, providing context beyond the annotation's safety profile.

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 front-loaded with the core action, followed by the return structure, parameters, and an example. Every sentence adds value 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?

For a simple tool with one parameter and no output schema, the description is complete: it covers the operation, parameter semantics, return format, and an example, 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 only one optional parameter with no description, but the description provides an Args section explaining 'endpoint' as the endpoint name from config and includes a usage example. 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 clearly states the tool performs a Class 0/1/2/3 integrity poll that returns all static points grouped by measurement type. It names the specific DNP3 operation and distinguishes it from siblings like dnp3_link_status or iec104_interrogate.

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 the tool should be used when a complete read of DNP3 static data is needed, but it does not explicitly contrast with alternatives or state when not to use it. This is clear context without 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, openWorldHint=true, and destructiveHint=false, so safety is covered. The description adds that the tool 'brings the DNP3 master online' and returns a dict with specific fields, which is useful. However, it does not clarify whether this action has lasting side effects or how it interacts with repeated calls, so it adds only moderate context beyond 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 purpose, args, returns, and an example. It is concise and front-loaded with the primary purpose. The [READ][risk=low] tag is somewhat redundant with annotations but does not harm overall readability.

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 one optional parameter and no output schema, the description covers the essentials: it explains the endpoint parameter, lists the return dict keys, and provides an example. The annotations cover safety. While it does not elaborate on the meaning of 'online' or the exact list of possible statuses, it is sufficiently complete for a simple status/health 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 schema has no description for the endpoint parameter (0% coverage), so the description carries the full burden. It explains that endpoint is a 'name from config (protocol dnp3)' and that omitting it uses the default. This adds meaningful semantics beyond the bare schema type, though it could specify the default value or format.

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: 'Bring the DNP3 master online and report link/outstation status.' This uses specific verbs ('bring online', 'report') and identifies the resource (DNP3 master, link/outstation). It is distinct from sibling tools like dnp3_integrity_poll, which likely focuses on polling integrity data.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives. It only explains that the endpoint parameter is optional and takes a config endpoint name, but does not mention any use cases, prerequisites, or exclusions. Given the long list of sibling tools, this lack of differentiation is a significant gap.

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, so the read-only nature is covered. The description adds substantial behavioral detail: the keyword heuristic categorization logic, the effect of min_duration_s as a filter, and the exact structure of returned events. The [READ][risk=low] tag further reinforces safety expectations. No contradiction with annotations.

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

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

The description is well-organized into Summary, Args, Returns, and Example sections. Each sentence provides essential information, and the core purpose is front-loaded. Despite being longer than typical descriptions, it justifies its length given the tool's complexity and the absence of an output schema.

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

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

For a 3-parameter tool with no output schema, the description is fully complete. It defines all inputs, the output structure (including nested by_category and events), the category mapping behavior, and gives a concrete example. An agent has all necessary information to invoke the tool correctly without additional assumptions.

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. It thoroughly explains each parameter: series format (ISO-8601 timestamps, state types including string/bool/number), category_map as an optional override with default heuristic behavior, and min_duration_s as a filter. This goes well beyond the schema's bare names and 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 opens with a specific verb+resource: 'Detect running→stopped transitions and categorize stoppages.' This clearly states the tool's function and distinguishes it from sibling tools like downtime_root_cause or oee_compute. The additional example and return structure reinforce the 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 clearly implies when to use the tool: when you need to identify and categorize downtime events from timestamped state data. However, it does not explicitly name alternatives or exclusions. The precise input/output specification gives enough context for an agent to infer appropriateness, but lacks explicit comparison to other downtime-focused 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?

Annotations already mark it read-only, but the description goes further: 'executes nothing', 'proposes a human-approved, undoable (MOC-gated) action', and 'only signals present in the input are cited'. It also discloses anti-hallucination downgrade and lead-window weighting behavior, adding meaningful context beyond 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 long but well-structured with [READ], an overview, Args, behavior notes, return dict, and a concrete example. Each section adds necessary detail for a complex 8-parameter tool with no output schema; nothing feels redundant.

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

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

With no output schema, the description fully defines the return dict, including hypotheses/evidence fields and optional graph. It also covers optional historian trend evidence and config-dependent behavior, making the tool safe to invoke in varied 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?

Schema coverage is 0%, but the description compensates with a detailed Args section. It explains window semantics including end-omission bound by state_series, per-argument shapes, cause_weights override/rejection/clamping, and include_graph's output behavior. This provides far more meaning than schema alone.

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

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

Description opens with '[READ][risk=low] AI downtime root-cause copilot' and explicitly states it 'correlates' evidence, 'ranks candidate root causes', and 'cites the REAL signals'. This clearly identifies a specific analytical read-only tool and differentiates it from live/other siblings via its advisory, evidence-cited nature.

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 says to supply evidence around a downtime/incident window (alarms, tags, dataflow, state series) and clarifies when it should be used as a read-only analysis. It also explains how insufficient evidence is handled, but does not name explicit alternatives or when-not-to-use conditions, so 4 rather than 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 readOnlyHint=true and destructiveHint=false, the description discloses live evidence gathering, sampling caps (refs capped at 20), load controls (sample_count, interval_ms), graph as 'pure re-shape', and 'no hidden inputs'. It also confirms non-destructive and nothing executed, enriching the annotation profile.

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 well-structured with distinct sections: purpose, Args, return shape, and example. Every sentence carries information, but the length is justified given the 8 parameters and behavioral nuance. Could be slightly 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?

Given the tool's complexity and absence of output schema, the description fully covers inputs, behavior, return shape (referencing downtime_root_cause plus 'collected_evidence'), and provides a concrete example. It also notes the graph block's structure. 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?

With 0% schema coverage, the description compensates fully by explaining every parameter's meaning, type, constraints, defaults, and relationships (e.g., 'first is also the diagnose_dataflow target', 'OPC-UA only'). This far exceeds the bare schema and gives precise operational guidance.

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 the tool is an 'AI downtime RCA copilot that GATHERS its own live evidence' with a specific verb (gathers) and resource (live evidence). It explicitly distinguishes from sibling downtime_root_cause: 'instead of hand-injecting evidence you give an endpoint + incident window and it pulls the evidence itself'.

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 differentiates when to use this tool vs downtime_root_cause by explaining the difference in evidence handling (auto-gathered vs hand-injected). It also notes 'Light read load; non-destructive; nothing executed', which signals safe contexts, but does not explicitly list 'when not to use' 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?

The description goes far beyond the readOnlyHint/openWorldHint/destructiveHint annotations by explicitly stating 'READ' and 'risk=low', 'proposes but executes nothing', and 'Thin evidence downgrades honestly rather than guessing'. This provides clear behavioral context about safety, advisory nature, and handling of uncertain evidence, with no 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?

Though lengthy, the description is well-structured with clear sections (summary, Args, Returns, Example) and every sentence adds substantive detail. The front-loaded summary conveys the core purpose immediately, and the parameter explanations are essential for the complex tool. No fluff 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?

With 11 parameters, no output schema, and complex composite behavior, the description is exceptionally complete. It details the expected input structures, the composition of sub-reports, the return dictionary with all fields, and includes a concrete example. It fully equips an agent 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 fully compensates by explaining every parameter in the Args section. It provides meaningful semantics for window, alarms, tags, dataflow, state_series, precursors, cascade_window_s, lead_window_s, cause_weights, imminent_within_s, and include_graph, including defaults and behavior.

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 is a 'One-call downtime triage' that composes alarm cascade, RCA, and precursor forecasts into a single tool answering three explicit questions about a stopped line. This unambiguously distinguishes it from sibling tools like alarm_cascade, downtime_root_cause, and pdm_forecast, which are listed as components.

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 specifies the primary use case ('on a stopped line') and notes the tool is read-first and advisory. However, it does not explicitly state when NOT to use it or name alternative tools for simpler cases (e.g., if only one question is needed). The composition context implies the usage but 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?

The description adds significant behavioral context beyond the annotations: it identifies the source as ~/.iaiops/data.db, warns the output preview is bounded to 200 rows to avoid flooding, and notes the parquet format requires pip install 'iaiops[export].' These details are valuable and not present in the annotations. No contradictions with the readOnlyHint or destructiveHint.

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 organized with a clear one-line summary, followed by source context, arg breakdown, return structure, and an example. Every sentence carries essential information—no filler or repetition. Despite its length, it earns its space for a 7-parameter 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?

The description is complete: it covers the source, format options, required dependency, all parameters, output schema (since no output schema is provided), and a concrete example. Given the tool's complexity (7 params, no output schema), this description covers all bases needed 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 explaining every parameter: fmt values, since/until as ISO-8601 inclusive bounds, endpoint and tag as filters, limit with range and default, and out_path with default pattern. This goes far 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+resource: 'Export collected samples from the LOCAL SQLite sink to a file.' It clearly distinguishes from siblings by noting the source is the local SQLite store, not a live device read, which differentiates it from historian_query and live-read 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 context on when to use the tool: data comes from the local SQLite sink written by historian_push(sink="sqlite"), and explicitly states 'NOT a live device read.' It also gives format selection guidance (csv, sqlite, parquet) and mentions the optional dependency for parquet. However, it never explicitly names alternative tools (e.g., historian_query) or states 'when not to use,' so it stops short of a full usage guide.

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 adds 'Read-only; no device I/O' and a [risk=low] tag, clarifying that this tool does not interact with devices. This is useful behavioral context that goes beyond the structured hints, though it omits details like rate limits or auth requirements.

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 front-loaded summary line, labeled Args/Returns sections, and an example. It is somewhat verbose, repeating the read-only nature already in annotations, but each part serves a purpose and the format 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?

The description thoroughly explains the single input parameter and the return dict structure, which is critical given there is no output schema. It also clarifies the fleet-wide aggregation scope. However, it does not cover edge cases (e.g., empty sites list, missing causes) or aggregation semantics (e.g., how top_causes are ranked), leaving a small 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?

The input schema for 'sites' is a bare array of objects with no property descriptions (0% schema description coverage). The description fully compensates by detailing the expected structure: 'Per-site reports carrying incidents: [{site, incidents:[{cause|primary_cause, confidence?}]}],' and provides an exact example. This 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's function: 'Roll up active RCA incidents across sites → fleet-wide top causes.' It specifies the verb ('roll up'), the resource ('active RCA incidents'), and the scope ('fleet-wide'), distinguishing it from site-level tools like downtime_root_cause and aligning with the sibling set's fleet-analytics theme.

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: it aggregates per-site incident reports into a fleet picture, implying use when a fleet-wide root-cause overview is needed. However, it does not explicitly name 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?

Annotations already mark it as read-only and non-destructive, and the description goes further by adding 'Read-only, pure; no device I/O,' explaining the offline logic based on stale_after_s, and clarifying that fleet_status is the worst site status present. This adds valuable behavioral context 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 clear Args, Returns, and Example sections. Every sentence adds value—no filler—and the length is justified given the need to document three parameters and return semantics in the absence of schema descriptions.

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 lists the return dict keys and explains the input behavior and output structure. It also provides an example, making the tool self-contained and fully understandable for an agent to select and 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 schema provides no parameter descriptions (0% coverage), but the description fully compensates. It details the sites argument structure including optional fields and status values, defines stale_after_s with its default, explains now as an optional ISO-8601 timestamp for deterministic staleness, and even includes a usage example.

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: 'Roll up per-site status reports into one fleet health view.' It also differentiates itself from sibling data_quality_fleet_rollup by noting it aggregates across edge SITES rather than per-endpoint within one site, making its purpose distinct.

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 positions this tool as 'the tier above data_quality_fleet_rollup' for central management across sites, giving clear context for when to use it. However, it does not explicitly state when not to use it or mention alternatives beyond that one sibling, so it stops short of full exclusionary guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: the tool is deprecated and redirected to opcua_health_summary, thresholds come from config or per-ref overrides, and the return includes ok/warn/alarm/unknown counts plus offending tags. This goes beyond annotations without contradicting 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 compact and front-loaded with the deprecation warning and READ status. The two-sentence summary plus a concise Args block provides necessary information without waste. Every sentence serves a purpose: deprecation, safety, behavior, and parameter meaning.

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 adequately explains the return value (counts and offending tags). It also covers default behavior (configured tags), override mechanism (thresholds), and deprecation. For a 3-parameter read-only tool, this is sufficient for an agent to select and invoke it correctly.

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

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

The input schema only provides types and defaults with no descriptions, so the description carries full weight. The Args section clearly explains each parameter: endpoint as a config name, node_ids as tag node IDs with an omit-to-use-configured-tags behavior, and thresholds as an optional dict of per-ref overrides. This adds essential meaning the schema lacks.

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

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

The description states a specific verb ('Classify') and resource ('OPC-UA tags') with clear scope: 'Classifies tag node-ids against warn/alarm thresholds.' It distinguishes itself from generic health tools by specifying the OPC-UA context, threshold-based classification, and return contents (counts plus offending tags).

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 how to use the tool: it explains that node_ids can be omitted to use configured tags, and that thresholds can be overridden. It does not explicitly state when to use this vs. sibling tools like tag_health or subscription_health, but the OPC-UA and threshold-specific language implies the intended scope.

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 aligns with '[READ][risk=low]' and adds significant behavioral context: the liveness logic based on changes, longest-stall detection, and the nuanced point that comms/quality can look fine while the upstream is dead. It also lists the return dict fields, adding transparency beyond 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 multi-sectional (overview, Args, Returns, Example) and front-loaded with the core purpose. Every sentence adds value, though the Args section partially repeats schema property names. It is appropriately concise given the amount of useful detail, with no 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?

For a simple 2-parameter tool with no output schema, the description is complete: it explains the concept, input formats, return values, and provides an example. It also covers edge-case behavior (max_interval_s) and the reason for flatlining. Nothing essential is missing.

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

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

Schema description coverage is 0%, so the description fully compensates. It explains 'series' as 'heartbeat samples — scalars or {value, timestamp?} (a counter/toggle)' and 'max_interval_s' as 'max allowed gap between changes; exceeding it = not alive.' The example further clarifies usage, adding 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 a specific verb+resource: 'Is a heartbeat/watchdog tag still alive? (liveness check).' It defines the tool's unique scope (heartbeat/watchdog vs. siblings like tag_health or historian_health) and the core concept of change detection. This distinguishes it from other health 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 useful context: a heartbeat must keep changing, and a flatlined one signals death even when other signals look fine. It implies when to use (for liveness of heartbeat series) but does not explicitly name alternatives or state when not to use. This is implied usage guidance rather than 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?

The description discloses key behaviors beyond annotations: 'Read-only, bounded (tag list is capped with a truncation flag); no device I/O' and 'TSDB readers need their extra: pip install iaiops[tdengine|iotdb]'. It also explains fallback behavior for the reader parameter. These details add significant context that the annotations (readOnlyHint, destructiveHint) only partially cover.

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: a lead summary, Args, Returns, and Example. It is detailed yet concise, with every sentence contributing useful information. The use of headers and inline code makes it 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?

Despite having no output schema, the description fully specifies the return structure: '{reader, source, tag_count, tags:[{tag, rows, first_ts, last_ts}], truncated}' plus the standard envelope. It also provides an example call and covers optional dependencies, making it complete for the tool's moderate complexity.

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

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

With 0% schema description coverage, the description fully compensates by explaining both parameters: reader accepts 'sqlite' | 'tdengine' | 'iotdb', with default behavior (config or local sqlite) and pip install prerequisites; limit is 'Max tags returned (1..2000; default 500)'. This is thorough and adds 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 clearly states the tool's purpose: 'Per-tag history coverage — what history do we actually have.' It specifies the exact resource (history store) and the output (rows, first_ts, last_ts per tag). This distinguishes it from sibling tools like historian_query and historian_push by focusing on coverage metadata rather than data retrieval or writing.

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 context for when to use the tool: 'Answers the question every RCA starts with' and explicitly notes it queries the same store historian_push writes. However, it does not explicitly name alternatives or describe when not to use it (e.g., 'for actual data values use historian_query'), 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 reinforces this with '[READ][risk=low]' and 'Pure analysis.' It goes beyond annotations by detailing the return dict structure and verdict values, giving the agent a more complete picture of the tool's 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 compact with labeled Args and Returns sections, front-loaded safety/risk info, and a practical example. Every sentence contributes useful 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?

There is no output schema, but the description specifies the complete return dict including all keys and the verdict string. The example further clarifies the expected input format, making the tool self-contained for an agent to call and interpret.

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

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

Schema description coverage is 0%, so the description must compensate, and it does. It defines the series format, gap_threshold_s as 'time gap ... counts as a data gap (default 60),' and flatline_eps as 'spread at/below which the series counts as flatline.' This fully documents all three parameters.

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: 'Bad-tag / flatline / gap detection over a provided series.' It clearly distinguishes itself from sibling tools like historian_query by emphasizing 'pure analysis over an injected sample series — no live historian needed.'

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 use case: analysis over an injected series, with the important caveat that no live historian is needed. It does not explicitly name alternative tools or provide when-not-to-use guidance, but the context is clear enough for an agent to select it appropriately.

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

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

Annotations only indicate readOnlyHint=false and destructiveHint=false, but the description adds meaningful safety context: 'risk=low', 'Data egress to the operator's OWN database,' and 'Non-numeric points are skipped.' It also discloses the return dict shape, going well 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 a concise header, intro, Args list, Returns line, and example. It is front-loaded with the core purpose. It is slightly verbose (repeats 'write' concept), but every section adds value; the example is helpful. A touch more brevity would make it perfect.

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

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

For a 7-parameter tool with no output schema, the description covers input format, defaults, target systems, return values, and a complete example. It also adds domain context (national TSDB, 信创) and safety disambiguation. No critical 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?

Schema coverage is 0%, so the description must compensate. It does: it explains each parameter group (points, sink, host/port/user/password, database), provides value domains for sink ('tdengine' or 'iotdb'), notes sensible defaults, and gives an example mapping for points. This fully compensates for 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 opens with a specific verb+resource: 'Push collected telemetry to a national TSDB.' It clearly distinguishes from siblings by specifying the target (TDengine/IoTDB) and explicitly saying 'instead of binding InfluxDB' and 'NOT a control-system write,' differentiating it from read/query tools and other write operations.

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: 'Writes already-collected points' and lists example input sources (output of interrogate / integrity_poll / read_points / monitor). It also gives a when-not: 'NOT a control-system write,' and an alternative: 'instead of binding InfluxDB.' This provides explicit usage context and 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 mark readOnlyHint=true and destructiveHint=false, but the description adds bounded rows ('rows are capped and a truncation flag is set when more history exists') and a crucial semantic: 'an empty samples with is_truncated=false means the history really is empty, NOT that the result was cut short.' Also discloses no device I/O.

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?

Description is structured with a summary line, context, args, return dict, and example. Each sentence adds necessary behavioral or parameter detail; no 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?

No output schema exists, so the description specifies the return dict fields and the `is_truncated` trust semantics. It also covers the reader fallback path and example invocation, making it self-contained 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?

Schema coverage is 0% and the Args section fully compensates: each parameter is explained with types, defaults, constraints (e.g., limit 1..10000 default 1000), and reader-specific behavior ('endpoint ... sqlite reader only — the TSDB layout stores no endpoint label').

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 '[READ][risk=low] Query a tag's historical samples from a historian.' The verb 'Query' and resource 'tag's historical samples' are specific, and it contrasts with sibling historian_push and live-sample 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?

Description says 'so the RCA copilot / an agent can see real pre-incident windows instead of only short live samples,' giving clear context for historical analysis. It does not explicitly name an alternative tool for exclusion, so a 4 rather than 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 indicate a safe read-only operation. The description adds behavioral context by mentioning that the tool 'connects' and reports status, and it discloses the structure of the returned dictionary. This goes beyond the annotations without contradicting 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 compact and well-structured: purpose, args, returns, and example. Every sentence earns its place, and the front-loaded title bracket gives an immediate safety/risk hint.

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 one-parameter, read-only tool with no output schema, the description fully covers the tool's behavior, parameters, and return value. It provides enough information for an agent to invoke and interpret the result without ambiguity.

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 the param name and type, with 0% description coverage. The description compensates by explaining that 'endpoint' is a config name for protocol 'iec104', is optional, and provides a concrete example. This adds meaningful semantic information 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 states a specific action ('Connect and report') and resource ('IEC-104 link status + discovered stations'), clearly distinguishing it from sibling tools like iec104_interrogate or iec104_read_point, which focus on data operations rather than connection status.

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 usage context (endpoint from config, optional default) and an example, but does not explicitly state when to use this tool versus alternatives. The guidance is implied by its purpose, but no direct exclusions or comparisons to siblings are given.

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 '[READ][risk=low]' and details return structure including point fields. No contradictions with annotations.

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

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

The description is compact and well-structured: a header tag, one-line purpose, then Args/Returns/Example sections. Every sentence adds value 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?

For a read-only interrogation tool, the description covers parameters, return format, and example. It does not mention pagination or potential large responses, but given the annotations and simplicity, it is sufficiently 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 has 0% description coverage, so the description fully compensates by explaining both params: common_address as ASDU common address with omit behavior, and endpoint as endpoint name. 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 'General interrogation: all monitored points of a station (ASDU CA)', a specific verb and resource. It distinguishes from sibling iec104_read_point by indicating it covers all points rather than a single point.

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

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

The description implies use when needing all monitored points, and provides endpoint and common_address context. It does not explicitly name alternatives or exclusions, but the scope is clear from 'all monitored points'.

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 provide readOnlyHint=true, and the description adds the return dict structure including 'found' and 'quality', plus guidance to omit common_address for the first station. It does not describe error handling for missing points, but the 'found' key partially addresses this.

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, front-loaded with a clear one-line summary, followed by args, return dict, and example. No wasted words; every sentence earns its place.

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

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

Given the tool's simplicity, the description is complete: it explains how to invoke, what each parameter does, what the return looks like, and provides a concrete example. No output schema exists, but the return dict is documented sufficiently.

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 description explains all three parameters (io_address, common_address, endpoint) with semantics beyond the schema, including default behavior for common_address and endpoint resolution from config. Since schema description coverage is 0%, this fully compensates.

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 ('Read') and resource ('one monitored point by information-object address'), which clearly distinguishes it from sibling tools like iec104_interrogate. It is unambiguous about what the tool does.

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 for reading a single point but does not explicitly state when to use it vs alternatives such as iec104_interrogate or iec61850_read. No exclusions or alternative recommendations are provided, leaving the agent to infer based on the tool name.

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, so the primary burden is satisfied. The description adds that only immediate children are returned (non-recursive) and specifies the return dict shape, which provides meaningful 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 compact and well-structured: it opens with a purpose tag, then lists args, return format, and an example. Every sentence earns its place 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 simple read-only browse tool with no output schema, the description covers the essential aspects: purpose, parameter semantics, return structure, and an example. It does not mention error handling or explicitly guide alternative tool selection, but that is a minor gap given the tool's simplicity.

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 compensates by documenting 'reference' with concrete examples (e.g., 'IED1LD0' or 'IED1LD0/LLN0') and 'endpoint' as a config name. This adds meaning over the bare schema, though the endpoint description is somewhat terse.

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 browses immediate model children under an LD/LN/DO reference, using a specific verb and resource. This distinguishes it from sibling tools like iec61850_read and iec61850_device_directory, which likely handle reads or full directory listing.

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 for hierarchical navigation by saying 'browse immediate model children', but it does not explicitly state when to use this tool versus alternatives. It lacks exclusions or guidance about when to prefer a full device directory or point read.

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, so the safety profile is covered. The description adds behavioral detail about the return dictionary structure and the optional children inclusion, which is helpful. However, it does not disclose potential edge cases like empty results or errors, but given the simple read-only nature, the bar is slightly lower. No contradictions with annotations.

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

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

The description is well-organized: a one-line summary, an Args section, a Returns section, and an example. Every sentence adds value—no fluff. It is appropriately sized for a tool with two parameters, and the example reinforces usage.

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 listing tool with 2 optional parameters and no output schema, the description provides everything needed: purpose, parameter meanings, return format, and an invocation example. It is complete without over-explaining.

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), so the description carries full burden. It explains 'include_children' as 'Also browse each logical device's immediate model children' and 'endpoint' as 'Endpoint name from config (protocol 'iec61850'); omit for default.' Both parameters get clear, non-schema-derived meaning, plus a concrete example.

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 'List' and a clear resource 'the IED's logical devices', immediately conveying the tool's scope. It also mentions optional behavior ('optionally their children') which distinguishes it from sibling browse/read tools. This is a strong, unambiguous purpose statement.

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: it lists logical devices and optionally children, with endpoint from config ('omit for default'). It does not explicitly name alternative tools or when-not-to-use, but the read-only listing nature is self-evident. The instructions are actionable without being misleading.

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, which the description reinforces with '[READ][risk=low]'. It adds context by noting that the return is a dict with an error field, but it does not disclose potential failure modes or endpoint configuration requirements beyond a brief mention. That said, with annotations covering the safety profile, the additional context is modest.

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 with a front-loaded tag, clear Args section, Return type, and a working example. Every sentence serves a purpose with no filler, making it easy to scan and absorb.

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 single-read tool with no output schema, the description covers purpose, parameters, return shape, and an example. It omits explicit error-handling details but includes an 'error' field in the return dict, which implies failure reporting. The lack of a defined output schema is offset by the return dict description, making it sufficiently complete for the tool's simplicity.

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 compensates by explaining each parameter: reference with an example, fc with sample values, and endpoint with source from config. It also shows defaults (fc defaults to MX, endpoint null). This provides enough semantic meaning for correct usage, though fc's full range is not exhaustively listed.

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 '[READ][risk=low]' and states 'Read one data attribute by object-reference + functional constraint.' This is a specific verb, resource, and scope, clearly distinguishing it from sibling browse tools like iec61850_browse. The example further clarifies the exact use case.

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 for reading a single attribute via the phrase 'Read one data attribute' and provides a concrete example, but it does not explicitly mention when to use this tool versus alternatives like iec61850_browse. No exclusions or alternative guidance is given.

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

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

Beyond the readOnly and non-destructive annotations, the description discloses important behavioral traits: it is 'pure + explainable', uses Laplace smoothing and a per-cause min-sample guard to prevent overfitting, falls back to defaults for thin corpora, and only tunes ranking without executing anything. This adds significant context not available from annotations alone.

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 opening summary, detailed behavioral explanation, parameter descriptions, return format, and a concrete example. Every sentence adds value, with no filler or redundancy, despite the length needed 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?

For a tool with 3 parameters, no output schema, and no nested objects, the description is remarkably complete. It explains the input format, the output dictionary with all fields, the algorithm's safeguards, and provides an example. There are no significant gaps in understanding how to invoke and interpret 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?

Even though the schema provides no parameter descriptions, the tool description thoroughly explains each parameter: history (with taxonomy enum values), min_samples (with default and behavioral consequence), and smoothing (with interpretation as a pseudo-count). 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: 'Learn a per-site RCA {cause: weight} profile from history.' It specifies the resource (per-site cause-weight profile) and verb (learn), and distinguishes it from related tools by explaining how it feeds into downtime_root_cause.

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: to adapt downtime_root_cause to this site's evidence, based on confirmed past incidents. It also states it is advisory and never executes anything. However, it does not explicitly mention when not to use it or list 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 read-only and non-destructive, but the description adds significant behavioral detail: hard caps on duration and max_changes (preventing infinite loops), polling interval semantics, deadband threshold meaning, and the exact return shape with timestamps. This goes well beyond the annotations and helps the agent anticipate real-world 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 structured logically: summary, behavioral note, argument list, return spec, and an example. Every sentence adds value, and the formatting makes it easy to scan. Length is justified by the tool's complexity and the lack of schema documentation.

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 supplies a full return dict. It covers all six parameters, constraints, protocol support, and even gives a concrete example. In the context of many sibling monitoring tools, this description uniquely clarifies the change-only, bounded-window behavior, making it complete for an AI agent to select and 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?

Schema coverage is 0%, so the description fully carries parameter meaning. It explains each argument (ref, endpoint, duration_s, interval_ms, deadband, max_changes) with types, constraints, defaults, and protocol-specific context. The return dict is also detailed, making the tool self-contained despite the empty schema.

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

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

The description opens with a specific, actionable statement: "Capture only the value CHANGES of a point over a bounded window." It clearly identifies the resource (value changes of a point) and the action (capture) while explicitly contrasting with every-sample polling. The deadband-report pattern mention further distinguishes it from sibling historian 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?

It provides clear context on when to use the tool: when only changes matter, via the deadband-report pattern, and lists supported protocols. It doesn't explicitly state when not to use it or name alternative tools, but the bounded-window and change-only behavior implicitly set it apart from continuous or full-history query 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?

Annotations already mark the tool as read-only and non-destructive, and the description reinforces this with [READ][risk=low]. It adds substantial behavior detail: optional parameters split loss categories, energy block activates only when actual_kwh is provided, and emission factor default is a flagged placeholder. No contradictions with annotations.

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

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

The description is well-structured with a formula, Args block, Returns block, and Example. It is longer than average, but each parameter definition and return detail earns its place given the tool's 13 parameters. The information is front-loaded and organized.

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 and a complex computation, the description is comprehensive: it covers all inputs, output keys, loss breakdown, energy/carbon behavior, and provides a representative example. It leaves little ambiguity for an agent selecting and invoking 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 has 0% description coverage, so the description carries full responsibility. It defines every parameter with units and semantics, explains how optional parameters split losses, and includes a worked example. This fully compensates for the schema's lack of 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 computes OEE using the formula Availability × Performance × Quality and describes the returned dictionary. However, it does not distinguish this from the sibling tool oee_multidim, so it lacks sibling differentiation.

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?

There is no explicit guidance on when to use this tool versus alternatives. The description reads like a function specification with parameters and returns, but it does not mention oee_multidim or any conditions for choosing this tool over others.

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

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

The description adds behavioral details beyond annotations: it explains that energy data triggers an energy_baseline block with anomaly flagging, notes the emission factor placeholder requires user action, and describes the return dict contents. Given annotations already declare safety, this is rich additional 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 well-structured with purpose, args, returns, and example. Front-loaded core action, uses bullets for readability, and no wasted sentences.

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

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

For a tool with no output schema, the description thoroughly explains the return format, including conditional energy_baseline, and provides an illustrative example. Combined with parameter details, an agent has sufficient information 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 coverage is 0%, so the description fully documents all four parameters with meanings, defaults, and expectations. It even specifies the record structure including required fields and optional energy fields.

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 'Aggregate OEE (+ optional energy) across dimensions', a specific verb-resource pair. It explains return structure and gives an example, distinguishing it from single-point OEE tools like oee_compute (which appears in 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 clearly specifies that dimensions can be passed, with a default of ['machine','part','shift'], and explicitly suggests using ['shift'] for by-shift energy comparison, giving use-case context. However, it doesn't explicitly name alternative tools or state when not to use it.

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

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

Annotations declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with '[READ][risk=low]', 'read-only', 'pure over the provided series', and 'no device I/O'. It also discloses behavioral details beyond annotations: robust Theil-Sen fitting, refusal of thin history, timestamp-dependent ETA units, and structured uncertainty reporting. No contradictions found.

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 a one-sentence summary and risk/read indicator, followed by a contextual paragraph, Args, Returns, and an Example. The length is justified by the tool's complexity (7 parameters, multiple output blocks, edge cases), and every section adds distinct value 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?

This is a complex forecasting tool with no output schema, so the description must compensate by explaining input requirements, behavioral constraints, and return structure. It does so comprehensively: return dict fields, degradation/rule/waveform sub-blocks, example call, and edge cases like thin history. The description is fully self-sufficient for correct invocation and interpretation.

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 zero description coverage (0%), so the description bears full responsibility for explaining parameters. It does so thoroughly: series format and minimum length, limit directionality, imminent_within_s default, and include_waveform semantics. Each parameter is given meaningful context that the schema alone cannot convey.

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 action: forecasting a value's trend and time until it crosses a warn/alarm limit. It explicitly distinguishes itself from sibling baseline_check by positioning itself as the predictive step above that violation-flagging tool. The scope (trend extrapolation, ETA estimation) is concrete 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 clearly states when to use this tool (predictive early warning before a limit is crossed) versus baseline_check (which flags violations that already happened). It also provides practical usage conditions: requires >=30 samples, refuses thin history, and notes when to disable waveform features (slow trend-only signals). This is explicit, actionable guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds substantial behavioral context: file size limit (≤5 MB), format support with content sniffing, graceful degradation to parse_errors, citation requirements, and truncation limits for variables (≤100) and blocks (≤50). This goes well beyond the annotations and helps the agent understand 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 a leading summary, then parameter details, return value breakdown, and example. It is longer than average but every sentence adds value, explaining formats, error handling, and citations. The only minor issue is slight redundancy in restating the file size (≤5 MB) multiple times, but this is not a serious flaw.

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, and the description provides a detailed return structure including stats, blocks, call graph, parse_errors, and citation_note. It also covers edge cases (malformed sections, truncation) and practical usage guidance (quote citations). Given the tool's complexity, the description is complete enough for an agent to select and invoke it correctly without needing external documentation.

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

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

The schema only defines a single string parameter 'path' with 0% coverage. The description fully compensates by specifying allowed extensions (.st/.scl/.awl/.l5x/.txt), existence requirement, size limit (≤5 MB), and a concrete example. This provides semantic meaning 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 clearly states the tool's purpose: it parses an exported PLC program file and returns a structural outline, including blocks, branches, timers/counters, and call graph. It specifies the verb 'Parses' and the resource 'exported PLC program file', and distinguishes from siblings like plc_program_visibility (live) by emphasizing 'Never uploads from a live PLC'.

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: for analyzing exported text files, not live PLCs. It states 'Never uploads from a live PLC' and 'reads exactly the named file', which implies when not to use it. It does not explicitly name alternative sibling tools, but the context is strong enough for an agent to infer appropriate usage.

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 specific behavior: 200-line cap with a truncated flag, case-insensitive block names, list of available blocks on failure, and the exact return dictionary keys. This adds substantial 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 summary, args, returns, and an example. Every sentence adds value and is concise, making it easy for an agent to parse quickly.

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: it covers input constraints, output structure (including all return keys), failure behavior, and a practical example. Even without an output schema, the agent knows exactly what to expect.

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?

Since the schema provides no parameter descriptions, the description fully compensates by detailing path (file extensions, existence, ≤5 MB) and block (case-insensitive, quotes optional). This 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's purpose: returning the exact source text of a single named block from an exported program. It distinguishes itself from sibling tools like plc_program_outline (outline) and plc_program_xref (cross-reference) by focusing on raw source retrieval.

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: it is for reading exactly the section the agent is explaining, capping at 200 lines, and failing unknown blocks with a list. However, it does not explicitly state when to use this tool instead of alternative siblings (e.g., outline for overview), 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 non-destructive annotations, the description discloses concrete behavioral traits: reads only the named file (≤5 MB), never performs live PLC uploads, every finding cites source_file+line, the risk score is transparent with cited reasons, and parse errors are reported. These details significantly aid the agent in predicting 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 front-loaded with a bracketed [READ][risk=low] tag and a concise summary sentence, then expands into structured Args/Returns/Example sections. It is longer than average, but the detailed return dict is justified given the absence of an output schema. A slight trim could improve clarity, but every section serves a 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?

This is a complex analysis tool with one parameter and no output schema. The description provides a comprehensive return structure with nested fields, explains input constraints and behavioral limitations, and gives an example. It fully equips the agent to understand what the tool does, what it takes, and what it returns.

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 lists only a bare 'path' string with no description, so the description carries the full burden. It adds critical semantics: acceptable file extensions (.st/.scl/.awl/.l5x/.txt), existence requirement, and the ≤5 MB size limit, plus an example. 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 clearly states the tool's purpose: producing a maintainability/operational-risk profile for an exported PLC program, with specific outputs like documentation coverage, unreferenced blocks, complexity hotspots, and risky constructs. This goes beyond a generic verb+resource and distinguishes it from sibling tools like plc_program_outline or plc_program_xref.

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 cues: it is the 'what am I inheriting?' view for reviewing legacy code, works on exported files only, and explicitly excludes semantic understanding and live PLC uploads. It implies when to use (risk assessment of static files) and when not (live data or semantic analysis), though it does not name specific alternative 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?

Annotations already declare readOnlyHint=true and destructiveHint=false; the description reinforces this with '[READ][risk=low]' and adds substantial extra context: the access classification is heuristic (op/regex, not data-flow analysis), specific classification rules for SCL/AWL/L5X are given, hits are truncated at 200, and the file must exist and be ≤5 MB. This goes well beyond the annotations and fully discloses limitations such as the verbatim source quoting and L5X line-as-rung 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 dense but well-organized: it opens with a one-line summary, then details search scope, access classification, arguments, return structure, and an example. Every sentence provides necessary information—no filler or redundant repetition of schema fields. The layout makes it easy to scan and quickly extract key constraints and behavioral nuances.

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 2 params, no output schema, and moderate algorithmic complexity, the description is remarkably complete. It explains what the tool returns (dict with source_file, format, symbol, hit_count, hits, hits_truncated, by_access), lists the classification rules, specifies file size and word-boundary matching, and even includes a usage example. This is more than sufficient for an agent to select and invoke the tool correctly 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?

The input schema provides only 'path' and 'symbol' with no descriptions (0% schema coverage). The description compensates fully: 'path' is defined as an exported program file with accepted extensions, existence requirement, and size limit; 'symbol' is described as a symbol/tag/absolute address with word-bounded match semantics. This adds essential meaning that the schema completely 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 'Cross-reference one symbol in an exported PLC program,' which uses a specific verb ('cross-reference') and resource ('symbol in exported PLC program'). It further distinguishes itself from siblings by detailing exactly what it finds (read/write/call/declare sites) and providing concrete symbol examples. This is unmistakably distinct from tools like plc_program_outline or plc_program_section.

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 the tool: whenever an agent needs to trace all references to a given symbol or address in an exported PLC file. It does not explicitly mention alternatives or exclusions, but the specificity of the purpose ('finds every... site') and the file format constraints make the intended context very clear. No explicit when-not guidance is provided, so slightly below 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 annotations (readOnlyHint, openWorldHint, destructiveHint:false), the description adds a risk level ('[READ][risk=low]'), clarifies that read/write authorization is the caller's decision, and discloses that every call is audited. It also explains the no-egress gate reporting behavior, adding significant context not present in 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 compact tag, a one-line summary, an explicit usage directive, a detailed list of contents, an essential server-posture note, and a return-dict sketch. Every sentence serves a purpose, and the front-loading ensures the core intent is immediately clear.

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 absence of an output schema, the description provides a detailed return key structure. It also covers the no-egress gate and audit behavior, which are critical for an agent deciding whether to proceed. This is complete for a zero-parameter discovery 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?

With zero parameters, the schema provides full coverage. The description includes an example call ('protocols_supported()') to reinforce the no-argument usage. This meets the baseline for a parameterless tool.

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 identifies the tool as a 'capability map' with the specific verb 'discover', listing protocols, status, tools, and connection params. It clearly distinguishes itself from sibling tools by framing itself as the pre-choice discovery step ('Call this to discover what iaiops can do before choosing a protocol/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 when-to-use context: 'before choosing a protocol/tool'. It also explains a specific benefit (learning about the no-egress gate) but does not explicitly state when-not-to-use or name alternative tools. This is clear context without formal 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?

Beyond the readOnly/destructive annotations, the description discloses the full decision pipeline (explicit taxonomy > synonym table > unambiguous keyword inference), states that unmapped rows are returned with reasons rather than silently guessed, and notes that signals may be empty with no fabricated evidence. It also explains the 'advisory' nature and behavior when learn=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 summary line, behavioral explanation, args list, return format, and example. Every element adds information without filler; 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?

No output schema exists, but the description explicitly lists the return dict structure and provides an example. It covers purpose, fallback logic, parameter semantics, and output format, making it comprehensive for a tool with this complexity and sibling 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?

With 0% schema description coverage, the description fully compensates by detailing recognized cause and free-text columns for rows, providing a concrete synonym example, and explaining learn, min_samples, and smoothing as parameters passed to learn_cause_weights. This gives far more meaning than the bare schema types/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 opens with a specific verb+resource statement: 'Turn a CMMS/work-order export into the RCA incident corpus.' It further explains it auto-builds the labeled history needed by learn_cause_weights, distinguishing it from sibling tools like learn_cause_weights or downtime_root_cause.

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 tool's context is clear: use it to build an RCA corpus from closed maintenance records, optionally feeding learn_cause_weights. It references learn_cause_weights as a downstream consumer but does not explicitly list when-not-to-use alternatives or exclusions, 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.