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

With no annotations, the description carries the full burden and does so: it declares read-only/no side effects, enumerates the exact MCP error conditions (malformed path, missing in live mode, unparseable, no ros2 CLI), documents the large-.mcap fallback with a `note` field, and discloses that anomaly detection exists only in mock mode.

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

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

Front-loaded with the one-line purpose, then layered detail; nearly every sentence carries distinct behavioral information (latched-topic rate rule, fallback, error list). It is dense to the point of being heavy, and the bolded mode blocks add visual weight without new semantics, so a 4 rather than 5.

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

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

For a tool with fallback paths, two execution modes, and error conditions, this is complete: return shape is named, edge cases (latched topics, oversized .mcap, unreadable bags) are handled, and an output schema exists so deeper return-value detail is unnecessary.

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 single `path` parameter already has 100% schema description coverage covering accepted suffixes, whitespace stripping, and live-vs-mock validation. The description restates the format rules and the ROS 1 exclusion but adds little path syntax that the schema does not already carry, so the baseline 3 applies.

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

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

States a specific verb and resource ('Summarize a ROS 2 bag at path') and names the concrete artifact returned (a BagAnalysis with storage format, duration, per-topic stats). It also differentiates itself from the sibling peek_bag_samples by noting that ROS 1 .bag files must go there instead.

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

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

Explicitly routes the ROS 1 .bag case to peek_bag_samples and explains when the live adapter falls back to count/bag-duration. It does not explain how live vs mock mode is selected (no mode parameter exists), which leaves a small inference gap, so not a full 5.

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

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

No annotations are provided, so the description carries the full burden and does so thoroughly: read-only by architecture, raises an MCP error when no DDS module is active, mock backend returns fixtures, results capped at 200 with truncation flags, and explicit disclosure that discovery shows DECLARED QoS not runtime behavior. It also explains the late_joiner flag as normal rather than a fault.

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?

It is long and dense, but purpose is front-loaded in the first sentence and each subsequent sentence covers distinct output fields, caveats, or limits that a caller needs. The length is largely earned by the tool's complexity, though some field enumeration borders on restating the 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?

Despite an output schema existing, the description goes further to explain what each field means and, critically, how to interpret ambiguous results (empty reports with non-empty not_matched still means no flow; all-empty does not prove health). Combined with error and mock-backend disclosure, nothing needed to invoke or interpret it correctly is missing.

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

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

There is a single optional parameter and schema coverage is 100%, with the schema already documenting the bare vs ROS 2 mangled name formats and the omit-to-scan-all behavior. The description restates the scoping semantics but adds no syntax or meaning beyond what the schema provides, so the baseline 3 applies.

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

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

The opening sentence states a specific verb (explain why) and resource (DDS readers/writers on a topic), and frames it as a diagnostic question distinct from siblings like topic_metrics or list_endpoints. An agent can tell exactly what it gets back without opening a schema.

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

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

Gives clear context for use ('explain why readers and writers do not talk') and scoping instructions ('Pass `topic` to scope to one topic; omit to scan all'), plus a when-not-to-trust caveat about empty results. It stops short of naming alternative sibling tools or an explicit exclusion, so it 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?

With no annotations provided, the description carries the full behavioral burden and does so: it discloses the live/mock mode distinction, the specific QoS fields returned, and the exact error conditions (malformed name, unknown topic, missing ros2 CLI). It also states 'Read-only; no side effects,' which is the safety profile an agent needs and is not contradicted by any annotation.

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

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

Dense and front-loaded: the scope/routing constraint comes first, then the argument, then the return shape, then failure modes. Every clause adds information, though the detailed enumeration of TopicInfo fields partially duplicates the output schema and could be trimmed.

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?

All inputs, routing, failure modes, and the read-only contract are covered for a single-argument lookup tool. With an output schema present, the return-value prose is a bonus rather than a necessity, so nothing an agent needs is missing.

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

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

Schema description coverage is 100%, so the fully-qualified-name rule and character restrictions are already documented in the input schema. The description restates the format with the same `/cmd_vel` example rather than adding syntax or resolution behavior beyond it, so the baseline 3 applies.

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

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

States a specific verb+resource ('Return info for a single ROS 2 topic') and names the boundary condition against a sibling ('ROS 2 graph only; on a DDS-only setup use `list_endpoints`'). An agent can distinguish it from topic_metrics or list_topics without opening the schema.

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

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

Explicitly names the alternative tool and the condition that selects it (DDS-only setups -> list_endpoints), which is strong routing guidance. It doesn't cover adjacent siblings like topic_metrics, and the 'single topic' scope is only implicit in 'Return info for a single ROS 2 topic', so it falls just short of fully explicit when/when-not coverage.

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

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

With no annotations, the description carries the full burden and delivers: always succeeds, read-only, no side effects, the observation window (nothing before observer_started_ns was observed), domain visibility limits (only the DDS domain joined at startup), payload_decoding disabled, dds_security not_supported, and how to interpret tracker gaps.

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

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

Front-loaded with the purpose, then layered interpretation guidance. It is dense and verbose for a no-arg tool, and some field enumeration overlaps the existing output schema, but the interpretation rules (mode, gap meanings) earn their space.

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

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

An output schema exists, so return values need not be re-explained, yet the description adds interpretation guidance on top. Combined with the always-succeeds and read-only guarantees, nothing an agent needs to call this correctly is missing.

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

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

The tool takes zero parameters and has full schema description coverage, so the baseline of 4 applies. There is no parameter surface needing explanation in the description.

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

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

States a specific verb+resource: reporting the TopicForge environment state as a HealthReport, enumerating the fields it covers. It is clearly the diagnostic/health tool among the data-inspection siblings, but it never names a sibling to contrast against, so differentiation is implicit.

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?

"Always succeeds: call it first when something looks wrong" gives a clear when-to-use trigger. It offers no explicit alternatives or exclusions (e.g., "use X to diagnose Y"), so it stops short of full routing guidance.

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

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

With no annotations, the description carries the full behavioral burden and does so thoroughly: read-only, raises an MCP error when no DDS module is active, mock mode returns a fixture, output capped at 500 endpoints with `truncated`/`total_discovered`, departed endpoints retained (last 200, 1 h), `activity` is always None and why, observer participant excluded unless `include_observer`, and how `None` duration/policy fields should be read. These are exactly the non-obvious traits an agent needs.

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

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

It is long, but the bold-labeled sections (Spotting orphans, Reading qos, Ownership, Departed endpoints, Topic filter, This lists discovery facts) make it scannable and the core purpose is front-loaded in the first sentence. Nearly every sentence conveys a non-obvious behavior, though the volume is close to the upper bound of what is proportionate.

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

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

An output schema exists, so return-value documentation is not strictly required, yet the description still maps the fields, semantics of `None`, and the `by_topic` roll-up. Combined with the failure mode, cap behavior, and observer exclusion, an agent has everything needed to call and interpret this tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the topic-matching rule (`rt/scan` and `scan` match each other, exact name first, with a `note` indicating which form matched, and a closest-known-topics note on no match), the fact that `domain_id` does not switch domains, and that participant_guid composes from list_participants output. It goes beyond what the schema states.

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 gives a specific verb and resource ('List every DDS endpoint (writer and reader) announced on the bus') and enumerates the per-endpoint payload (role, topic, type_name, participant_guid joined with participant_name, structured qos). It explicitly separates itself from sibling `peek_dds_samples` by saying to use this 'instead of parsing `peek_dds_samples` output and joining GUID prefixes.' An agent can distinguish it from list_participants/list_topics without opening any schema.

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

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

It names an explicit alternative and the reason to prefer this tool ('instead of parsing `peek_dds_samples` output'), and points to a complementary tool ('Pair it with `detect_qos_mismatches` to see which pairs cannot match'). It also explains when the orphan and departed-endpoint views matter. There is no explicit 'do not use this when X' exclusions against other siblings, so it stops short of a 5.

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

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

With no annotations, the description carries the full behavioral burden and does so richly: read-only by architecture, raises an MCP error without a DDS module, waits up to 3 s for discovery warm-up, mock backend returns fixtures, and it discloses that `lost_ns` is only an upper bound with per-vendor lease timing. These are exactly the traits an agent cannot get from structured fields.

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

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

Front-loaded with purpose and return type, then bolded sub-sections keep the dense material navigable. It is long, and the exhaustive vendor enum restates what the output schema already lists, but nearly every sentence carries substantive semantic information rather than filler.

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

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

An output schema exists, so return values needn't be explained, yet the description supplies the semantic layer the schema can't (why `vendor` can be `unknown`, what `is_observer` means, how lease expiry bounds `lost_ns`). Error conditions, domain limits, and warm-up behavior round out everything needed 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 100% and the schema already explains that `domain_id` is accepted only for compatibility. The description echoes this and adds a small diagnostic hint (a missing participant may be on another domain), but does not add format or syntax meaning beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List DDS participants observed on the bus') and immediately names the return type (`list[ParticipantInfo]`). An agent can distinguish it from siblings like list_endpoints, list_topics, and participant_events from the first sentence alone.

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

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

Gives clear context: it observes only the startup domain, participants on other domains are invisible, and it redirects to `health_check` for `dds_domain_id`. It also explains it operates beneath ROS so non-ROS participants appear. It stops short of explicitly contrasting with the closest sibling (participant_events for history vs. this for current state).

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

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

With no annotations, the description carries the full burden and delivers: read-only/no side effects, mock vs live mode disclosure via mode_effective, the empty-list outcome on timeout or empty graph, the MCP-error outcome when no ros2 CLI exists, and the null-QoS-fields caveat. This is unusually rich failure-mode and state 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?

Front-loaded with the routing constraint before the return description, and every clause adds information (return fields, null caveat, empty/error states). It is dense and slightly over-loaded with back-to-back bolded outcomes, but nothing is genuinely wasted.

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

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

Given no annotations and a simple zero-param read tool with an output schema, the description still covers safety (read-only), both non-success outcomes (empty list, MCP error), mock-mode nuance, and pointers to siblings for QoS and DDS-only setups. Nothing an agent needs to invoke and interpret it correctly is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. No parameter semantics are needed or missing.

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

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

States a specific verb and resource ('List every ROS 2 topic on the current graph') and immediately scopes it ('ROS 2 graph only'), naming the sibling to use otherwise (list_endpoints). An agent can distinguish it from neighbors like list_participants or list_endpoints without opening a schema.

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

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

Explicit when-not routing: 'on a DDS-only setup use list_endpoints', plus a follow-up alternative for QoS ('call get_topic_info for a topic's QoS'). Both the primary alternative and the sub-case escalation path are named with their selecting conditions.

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

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

No annotations, so the description carries the full burden and does so richly: crash caveat with lease bounds per backend, restart semantics (one lost + one discovered per restart), 200-event silent cap, warm-up wait, backend-specific capture behavior, mock fixture mode, and the MCP error condition with required install/env settings.

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

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

Long but dense and front-loaded: purpose first, then return shape, then semantics, then caveats. Nearly every sentence carries a unique fact, though the field-by-field enumeration of the return type overlaps with the existing output schema and could be trimmed.

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 output schema exists, return values needn't be explained, yet the description goes further with time_source semantics (dds_source_timestamp vs observed_local, weakest) and observed_ns ordering. Combined with crash/restart/backend caveats, an agent has everything needed to call and interpret it correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters including the 200-event cap interaction with lookback_seconds and the domain_id compatibility note. The description's mention of reducing lookback_seconds largely repeats the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Return DDS participant lifecycle events (`discovered`/`lost`)') with explicit scope (recent window). It is clearly distinguishable from siblings like list_participants (current snapshot) and health_check (observer metadata), which it cross-references.

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

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

Provides concrete motivating questions ('who was on the bus 5 minutes ago and left?', 'when did this participant first appear?') that map directly to invocation. However, it never explicitly contrasts with the nearest sibling, list_participants, nor states when-not to use it.

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

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

With no annotations, the description carries the full burden and delivers: read-only by architecture, library dependency, explicit MCP error conditions (missing path, absent topic, missing library), silent clamping to 50, mock-backend behavior, decode-status annotation shape, and array truncation with `note`. This is the behavioral context an agent needs before calling.

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

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

Front-loads purpose and the sibling differentiation before drilling into formats and error behavior, and every sentence carries operational information. It is dense and long, but little of it is redundant.

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

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

Given a rich output schema, the description need not explain return values, and it still covers the reader's prerequisites, error cases, decode-status semantics, mock behavior, and format support. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter error semantics not in the schema (raises an MCP error when the bag path does not exist or the topic is not present) and reinforces the format-detection-by-extension behavior tied to `path`.

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

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

States a specific verb and resource ('Peek up to `count` samples from a recorded bag file') and immediately distinguishes itself from two named siblings, `peek_dds_samples` (live DDS) and `sample_messages` (live ROS 2 graph). An agent can tell exactly what this does without opening a schema.

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

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

Explicitly frames the use case ('reads offline bag content for post-mortem analysis') and names the alternatives it is not, with the condition that selects each. It also discloses the environment prerequisite (rosbags library, ROS 2 side of the runtime) and that it errors on a DDS-only setup.

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

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

No annotations are provided, so the description carries the full burden and does so richly: read-only by architecture (cannot publish), raises an MCP error in two specific situations, 3 s discovery warm-up, silent clamping of count, and payload decoding disabled on user topics returning count 0 with a note. This is exactly the behavioral context an agent needs.

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

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

Dense and front-loaded – the core distinction from `sample_messages` comes first, then topic categories, then failure modes. It is long, but nearly every sentence carries operational information; minor redundancy exists in restating the `SampleResult` shape that the output schema already covers.

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

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

For a two-param tool with no annotations, the description covers selection rationale, topic-name handling, per-category return semantics, limits, and error conditions. With an output schema present, the brief restatement of the return shape is not a gap.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: the three accepted topic name forms (`/scan`, `scan`, `rt/scan`) resolve to the same topic, and the builtin discovery topics have distinct return semantics. It also explains the clamping behavior for count, though that is largely mirrored in the schema.

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

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

States a specific verb+resource ('peek recent samples on a raw DDS topic') and immediately differentiates from the sibling `sample_messages`, explaining that this reads the DDS layer directly and works without ROS 2. An agent can tell it apart from the other sampling/list tools without opening a schema.

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

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

Explicitly routes the agent: use `participant_events` for discovery history, `list_endpoints` for a user topic's presence/writers/readers/QoS, and `sample_messages` if you need the ros2 CLI. It also states the failure conditions (no DDS module, unannounced topic) and the warm-up wait.

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

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

With no annotations, the description carries the full burden and does so: read-only/never publishes, live mode runs `ros2 topic echo --csv --once` so results are empty with no active publisher and capped at one message, 1 MiB size cap drops messages with a note, array cut at 128 with `_truncated_after_columns`/`_truncated_columns` markers, and an MCP error is raised when no `ros2` CLI exists.

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

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

Dense but front-loaded: the DDS-only routing caveat leads, then the core action, then behavior. Every sentence carries information, though the parameter-behavior detail makes it longer than strictly necessary for selection.

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

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

For a complex sampling tool with an output schema, the description covers failure modes, mode_effective semantics, timestamp provenance, CSV positional-column payload shape, and truncation markers. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: `count` clamping to 50 and the fact that returned `count` may be lower than requested, and how `max_array_length`/`arrays_summary_only` change truncation behavior. It reinforces rather than merely repeats the schema.

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

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

States a specific verb+resource+scope: 'Peek up to `count` recent ROS 2 messages from `topic`', and explicitly delimits itself from `peek_dds_samples` ('Distinct from `peek_dds_samples`, which reads the raw DDS layer'). An agent can select it without opening the schema.

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

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

Opens with the routing condition: ROS 2 graph only; on a DDS-only setup use `list_endpoints` or `peek_dds_samples` on `DCPSPublication`/`DCPSSubscription`. It names the alternatives and the precise condition that selects them.

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

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

No annotations are provided, so the description carries the full burden, and it does so thoroughly: status semantics and their meaning for the numbers, the observability limitation of frequency_hz_observed, the declared-vs-measured distinction for frequency_hz_declared, the read-only architecture, the MCP error conditions (no DDS module, out-of-range window), and the 3 s discovery warm-up delay. This is exactly the behavioral context an agent needs to avoid misinterpreting results.

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

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

Front-loaded with purpose, then progressively adds interpretation rules (status), limits, error conditions, and startup caveats using bold markers for scannability. Despite its length, every sentence carries distinct decision-relevant information with no filler.

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

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

An output schema exists, yet the description still names the payload fields and, more importantly, explains how to interpret them (status branches, null/0 caveats, declared-vs-measured). For a single-resource compute tool with three fully-documented params, this is complete.

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

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

Schema description coverage is 100%, so all three parameters are already fully documented in the schema (including the domain_id no-op explanation and window_seconds range). The description adds only the error condition for an out-of-range window, so the schema does the heavy lifting and a baseline 3 is appropriate.

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

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

States a specific verb (Return) and resource (temporal metrics: frequency, sequence gaps, latency percentiles) scoped to a DDS topic over a time window. The named metric set distinguishes it from siblings like peek_dds_samples or get_topic_info, which don't compute derived temporal metrics.

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?

Explains the operational context clearly: the buffer is populated only when peek_dds_samples runs, so the metric is a coarse presence signal. It also tells the agent to read `status` first and enumerates the branches. It stops short of an explicit when-to-use-this-vs-X directive against siblings, so it's a strong 4 rather than a 5.

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