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

Annotations already cover read-only/idempotent/no-destructive, and the description still adds substantial behavior: the 200 MiB `.mcap` fallback rule, the `bag_duration` basis and `note`, which error conditions raise MCP errors, the 45 s ceiling, and single-call lock serialization. The only small gap is that the `latched`/1 s rule is described operationally without saying how the caller should interpret a null `frequency_hz`.

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 return shape, then falls back to computation semantics, modes, error cases and timing — a sensible information hierarchy with no filler sentences. It is dense to the point of being a wall of bolded clauses, which costs a point on scannability.

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

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

For a single-parameter tool with an output schema, the description still covers modes, format gate, fallback math, error surface, lock contention and timeout — everything needed to call it correctly and to interpret a degraded result. Nothing material is left for the agent to guess.

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 parameter is already self-documented, so the baseline is 3; the description nonetheless adds that existence and format are validated live while mock accepts any well-formed path, which is meaning beyond the schema. It largely restates the accepted extension list, which caps it below 5.

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

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

Opens with a specific verb and resource ('Summarize a ROS 2 bag at `path`') and names the concrete return type (`BagAnalysis`) plus its fields, so the agent knows exactly what it gets back. It also routes ROS 1 `.bag` users to `peek_bag_samples`, distinguishing it from the closest sibling in the same sentence.

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 splits live mode (`.mcap`, `.db3`, `rosbag2_*`) from mock mode (any bag-like path, anomaly detection only) and states the alternative (`peek_bag_samples`) for the format this tool rejects. It even gives retry guidance for the `busy` lock error.

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?

Adds plenty beyond annotations: read-only by architecture, raises an MCP error without an active DDS module, runs under a DDS lock with a 45 s bound and `busy` retry, caps lists at 200 with `truncated`/`*_total`, and flags that discovery shows declared QoS rather than runtime behaviour. It also explains that `late_joiner` matches are normal and that suggested fixes are text only.

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 and the returned scan fields, then the caveats and error/latency notes. It is dense and long, and some content (read-only, return shape) duplicates annotations or the output schema, but nearly every sentence carries operational value.

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?

Complete for a scan tool with an output schema: it covers scoping, truncation, lock/duration behaviour, error conditions, and the important false-negative caveat about empty results. 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?

Only one parameter, and the schema already documents `topic` at 100% coverage, including the omit-to-scan-all behaviour. The description repeats this rather than adding syntax or format details, 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?

Names a specific verb and resource: explains why DDS readers and writers on a topic cannot communicate and reports who can. It clearly differs from siblings like get_topic_info or list_endpoints by describing a pairwise QoS compatibility scan with a named return type.

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?

Says to pass `topic` to scope the scan, and that omitting it scans all topics. It also points at `verify_with` for confirming repairs and warns that an empty `reports` still means no data flows. It does not explicitly state when to prefer a sibling such as get_topic_info, but the context is clear.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial non-obvious behavior: a timed-out parameter read is a finding rather than an error (partial result with `parameters_note`), secrets matching password/secret/token/api_key/credential are replaced with `<masked>`, long values are truncated, and duplicate node names raise `duplicate_count`. The duration/lock model (up to three CLI calls, 8 s each, 45 s ceiling) is unusually precise and consistent with the read-only 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?

Front-loaded with the purpose and the sibling alternative before any detail, and nearly every sentence carries operational information. It is dense and heavy with bold emphasis, which costs some readability, but there is no filler to cut.

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 three-parameter, open-world read tool with an output schema, this covers everything an agent needs: scope, alternative, error conditions, partial-result semantics, masking, time bounds, and concurrency. Nothing required 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 semantic weight beyond the schema: `timeout_s` governs only the parameter read and a miss is reported rather than raised, and `params_file` is explained by its effect (`param_diff` listing differ / declared_only / masked entries). It does not restate the `node` name format, leaving that to the schema, which 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?

Opens with a specific verb and resource ("Describe one ROS 2 node as a `NodeInfo`") and immediately enumerates what that record contains: topics, services/actions, parameters, use_sim_time. It is trivially distinguishable from siblings like get_topic_info and list_participants, which the description names as the alternative in the DDS 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?

Explicitly scopes itself ("ROS 2 graph only") and routes the agent elsewhere when that scope fails ("on a DDS-only setup use `list_participants`"). It also states the failure boundary — an MCP error when the node is absent from the graph, the name is malformed, or no `ros2` CLI exists — and the `busy` retry condition.

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

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

Goes well beyond the annotations by disclosing the ROS lock, the 45 s bound, the single-call-at-a-time serialization, the `busy`/retry path, and the MCP error conditions (malformed/unknown topic, missing CLI). Safety is already covered by readOnly/idempotent hints, so the only minor gap is that it does not say how counts behave when the topic exists but has no endpoints.

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 and then the operation, with a labeled Duration clause at the end. The QoS field enumeration is dense but earns its place; slightly heavy for one sentence's worth of content.

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

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

Covers routing, error modes, timing and lock behavior for a single-parameter read tool with an output schema that already explains the return shape. Only minor omission is what happens for a valid topic with zero endpoints (empty lists vs error).

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 constrains the format, so baseline is 3; the description adds value by restating the fully qualified requirement as a precondition for calling and by noting rejection happens before the CLI is reached, which hints at fast-fail 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?

Specific verb + resource: 'Describe one ROS 2 `topic` ... as a `TopicInfo`', with the fully qualified name format given inline. It distinguishes itself from siblings list_topics (list vs describe) and list_endpoints (ROS 2 graph vs DDS-only) explicitly.

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 ROS 2 graph constraint and names the exact alternative for a DDS-only setup (`list_endpoints`). It also states the retry condition on `busy`, so the agent knows what to do rather than giving up.

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 read-only/no-destructive annotations, it discloses stateful snapshot storage and its 16-entry in-memory cap, first-call note behavior, MCP errors, mock mode behavior, and lock/duration semantics. These are concrete behavioral traits that materially help an agent invoke it correctly.

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 purpose is front-loaded and most detail is useful, but the description is long and explains return fields like changes, added, and not_compared despite an output schema existing. 'Read-only' also largely repeats the annotations.

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 stateful diff tool with many edge cases, the description covers live vs bag modes, baseline selection, error conditions, snapshot retention, mock behavior, and timing constraints. With an output schema present, it does not need to explain every return value in depth.

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 carries the parameter semantics. The description mirrors bag_path and baseline meanings and adds first-call context, but it does not add much syntax or format detail 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 names a specific operation (snapshot and compare), resource (ROS 2 graph), and output shape (GraphDiff). It distinguishes the tool from single-resource siblings by focusing on what changed between a current snapshot and a 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?

It clearly frames the use case as 'what changed since it last worked' and explains live vs bag_path plus baseline options. It also lists pair-wise limitations in not_compared, but it does not explicitly name sibling alternatives for non-diff tasks.

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 establish read-only, idempotent, non-destructive behavior, and the description adds substantial context beyond that: it always succeeds, never waits for a lock, never runs the ros2 CLI, and answers at once. It also discloses field-level semantics such as observed_domain_note only reflecting the startup domain and tracker_* errors indicating 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?

It is a single front-loaded paragraph with no filler, and the dense field list earns its space by attaching operational meaning to fields like observed_domain_note and tracker_*. The critical advice to call it first is stated clearly at the end.

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 an output schema present, the description does not need to explain return values, but it still adds the failure-mode and field-semantics context an agent needs to interpret the report. It covers the always-succeeds guarantee, DDS-only and no-DDS cases, and the limited payload decoding and security scope.

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

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

The tool has zero parameters, so the baseline is 4 and there is no input schema detail the description needs to compensate for. The description appropriately focuses on the report and its semantics rather than inventing parameter 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 a specific verb and resource: report TopicForge environment state as a HealthReport. It distinguishes the tool from siblings by naming list_endpoints for DDS-only setups and by explaining how health_check differs from a live data-listing/query 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?

It gives clear usage guidance: call it first when something looks wrong. It also names the relevant alternative, list_endpoints, for the specific case where ros_backend is none, and explains what dds_inactive_note means when dds_backend is none.

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 cover the read-only/idempotent profile, and the description adds substantial operational context beyond that: MCP error without a `ros2` CLI, mock-mode behavior, 45 s duration bound, ROS-lock serialization with a `busy` retry, 3000-message listen cap with `truncated` flag, and wall-time vs stamp-time frequency caveats. It also discloses what empty results mean.

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 before the report schema and operational caveats, and nearly every clause carries information. It is a dense wall of text, however, and the TfReport field enumeration partly duplicates the output schema, making it heavier than needed.

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

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

An output schema exists, yet the description still names the finding kinds an agent must reason over (stale, two_parents, disconnected, cycle, no_path) and covers failure modes, time-base semantics, and mock behavior. Nothing needed for correct invocation or interpretation 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 baseline is 3. The description reinforces that `window_s` applies to `/tf` only (not latched `/tf_static`) and restates `stale_after_s` in stamp-time terms, but adds little that the schema does not already spell out.

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 ('Rebuild the TF tree from the transforms on /tf_static and /tf') plus its scope ('ROS 2 graph only'), which separates it from the topic/node/DDS inspection siblings. An agent immediately knows this is the transform-tree analysis tool rather than a generic graph lister.

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

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

Clear context is given: use source_frame+target_frame to get the chain between them, read `note` when `frames` is empty, retry on `busy`. It lacks explicit when-not-to-use guidance or a named alternative, but no sibling overlaps with TF analysis, so the routing risk is low.

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 cover the safety profile (read-only, idempotent, non-destructive), yet the description adds substantial behavior beyond that: a 500-endpoint cap with `truncated`/`total`, a 200-entry/1-hour departed-endpoint cache, `busy` lock errors within a 45s bound, an MCP error with no active DDS module, mock-fixture behavior, and that `domain_id` is ignored and only range-checked. It even discloses semantic limits (cannot distinguish silent/hung writers, cannot observe instance ownership at runtime).

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

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

Front-loads the core purpose and avoids fluff, but it is a long, bold-header-laden block; a few clauses (mock fixture, duration lock detail) could be tightened without loss. Every sentence remains informational rather than repetitive, so it stays readable for a discovery-heavy 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?

With an output schema present, return shape need not be restated, and the description fills the remaining gaps: error modes, truncation, filtering interplay, departed-endpoint semantics, QoS `None` meaning, and orphan definitions in `by_topic`. Nothing an agent needs to call it correctly appears 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 baseline would be 3; the description still adds value by explaining cross-parameter intent, e.g. that `compact` exists specifically for large buses and drops specific fields, that `topic` accepts either `rt/scan` or `scan`, and that `domain_id` does not switch domains. Most literal syntax is already in the schema, so it stops just short of a 5.

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

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

Opens with a specific verb and resource ('List every DDS endpoint... announced on the bus') and enumerates the returned fields, so an agent knows exactly what it gets. It explicitly differentiates from sibling peek_dds_samples ('instead of parsing peek_dds_samples and joining GUID prefixes') and names detect_qos_mismatches as a complement rather than a substitute.

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 explicit routing: use this instead of parsing peek_dds_samples, use `fields: compact` on large buses, scope with `topic`/`participant_guid` to read full QoS on one topic, and pair with detect_qos_mismatches because this tool cannot judge writer health. It also states what is excluded (observer, ROS 2 internal endpoints) and how to include them, leaving little to inference.

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

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

Beyond the readOnly/idempotent annotations it discloses concrete operational traits: raises an MCP error without the `ros2` CLI, completes within 45 s, serializes behind the ROS lock and can return a `busy` error requiring retry, and returns an empty `nodes` list rather than failing on an empty graph. It also notes hidden underscore-prefixed nodes and nodes on other `ROS_DOMAIN_ID`s are invisible — a genuine discovery caveat.

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 ROS 2 vs DDS scoping rule and error/duration notes bolded for scanning. The middle sentence enumerating every `NodeListing` field is dense and slightly over-stuffed given an output schema exists, but nothing is wasted.

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

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

Covers call path, failure modes, timing, concurrency, visibility exclusions and empty-result semantics, and the return structure is backed by an output schema. An agent has everything needed to invoke and interpret this 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 tool takes zero parameters, which is the baseline-4 case; there are no argument semantics to explain. The description instead spends its words on return shape and error behavior, which is the right allocation.

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 the nodes on the ROS 2 graph') and immediately scopes it against siblings: `list_participants` for DDS-only setups and `get_node_info` for a single node's interfaces. The agent can pick the right tool 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?

Explicit routing rules are given in both directions: use this tool on the ROS 2 graph, use `list_participants` on a DDS-only setup, and use `get_node_info` to get one node's interfaces. Preconditions (ros2 CLI required) are also stated.

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 read-only and idempotent behavior, the description adds substantial behavioral detail: startup discovery wait up to 3 s, visibility limited to the startup domain, mock backend behavior, MCP errors when no DDS module is active, lock contention with a busy error, and a 45 s duration bound. This is unusually complete transparency 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 long but front-loaded and structured with bold sections, and almost every sentence conveys operational meaning. Some return-field detail may duplicate the output schema, but the field semantics it adds, such as unknown vendors and optional names, are useful 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?

For a complex DDS discovery tool with an output schema and safety annotations, the description covers the important operational gaps: domain visibility, restart counting, lifecycle timestamps, error conditions, backend requirements, and duration limits. An agent has enough context to invoke and interpret 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?

There is one parameter and schema description coverage is 100%, so the schema already explains that domain_id is only range-checked and does not switch domains. The description reinforces that constraint but does not add syntax or format details beyond what the schema provides.

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

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

The description states a specific verb and resource: list DDS participants observed on the bus, returned as a ParticipantListing. It also distinguishes the tool from ROS-graph tools by noting it works at the raw DDS layer, so non-ROS participants appear too.

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

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

Usage context is implied through domain restrictions and restart semantics, but the description never explicitly names alternatives such as participant_events or list_nodes and never says when to choose this tool over them. An agent can infer the use case, but the guidance is not explicit.

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

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

Goes well beyond the readOnly/idempotent annotations: discloses empty-result semantics, MCP error behavior without the `ros2` CLI, a 45 s duration bound, and lock contention with a `busy` error requiring retry. That is exactly the operational context an agent needs before calling a discovery tool that can block on a lock.

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

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

Front-loads the scope constraint and then uses bolded fragments for empty results, errors, and duration, so it scans well. Slightly dense and includes one redundant phrase ('Read-only; no side effects') already covered by annotations, but nearly every sentence carries distinct 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?

Even though an output schema exists, the description adds result-field meaning (`mode_effective`, publisher/subscriber counts) and the critical edge cases: empty topics, discovery timeout, missing CLI, and lock contention. Nothing an agent needs to decide whether to call it or interpret its failure modes 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?

With zero parameters the baseline is 4, and the description correctly avoids inventing parameter details. It instead explains the shape of what comes back, which is useful but belongs more to the output schema than to parameter semantics.

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

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

States a specific verb and resource ('List the topics on the ROS 2 graph') and immediately scopes it against the DDS-only alternative by naming `list_endpoints`. An agent can distinguish it from siblings like `get_topic_info` and `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?

Explicitly routes usage: ROS 2 graph only, use `list_endpoints` for DDS-only setups, and use `get_topic_info` because QoS is not included here. It also names the error condition (missing `ros2` CLI) and the retry case (busy lock), which is when-to-use guidance no sibling name alone would provide.

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/idempotent/non-destructive, yet the description adds far more: the crash caveat (lost timestamp is an upper bound, lease expiry of 10s/20s/100s), restart semantics, the 200-event cap with truncated/note, the observer-start limitation, backend-specific behavior (Cyclone's 0.5s poll can miss fast cycles), an MCP error when no DDS module, and lock/busy/duration behavior. This is behavior the agent cannot get from annotations or schema.

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

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

Purpose and output shape are front-loaded, and bold section labels (crash caveat, restarts, backends) make the dense block scannable. It is long, but nearly every clause carries distinct behavioral information for a genuinely complex 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?

An output schema exists, yet the description still clarifies the non-obvious return semantics (time_source strengths, age_s being live-only, restarts_by_name), and covers the operational constraints an agent needs. Nothing required 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 both parameters are already documented, including the 'domain_id is ignored' caveat and lookback_s range. The description only restates the window-to-cap relationship ('reduce `lookback_s`'), which adds little beyond the schema's own note that a larger window may hit the cap.

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 a concrete example query ('who left in the last 5 minutes?'). The event/lifecycle focus clearly distinguishes it from sibling list_participants, which reports current membership rather than a history of joins and leaves.

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

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

Gives a clear usage scenario via the example query and actionable recovery steps ('reduce `lookback_s`' when truncated, 'retry' on `busy`). It never explicitly names a sibling (e.g. list_participants) as the alternative for the current-state case, so the when-not condition is left implicit.

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/idempotent/closed-world, and the description adds substantial context beyond them: which error conditions raise an MCP error, that it runs without a lock while other calls are busy, that it needs the ROS 2 side of the runtime, decode-status semantics, clamping behavior, and rate/verdict caveats for multi-publisher topics. Nothing contradicts the annotations — 'read-only by architecture' and offline/mock behavior match readOnlyHint and openWorldHint=false.

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 and well-organized: purpose and null-hypothesis sibling contrast come first, then time range, clocks, errors, rate, and duration in ordered blocks. It is dense and slightly over-stuffed — the clock-resolution and duration paragraphs border on reference documentation — but almost every sentence carries invocation-relevant information, and repeated facts (count default/clamp) are a minor redundancy with the 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 7-parameter tool with an output schema, the description is more than complete: it explains result fields (`_decode_status`, `timestamp_ns` sources, `summary`, `rate`), failure modes, and environment prerequisites, so an agent can predict both success and error behavior. Nothing needed 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; the description earns extra credit by explaining cross-parameter semantics the schema states only piecewise — that `min_log_level`/`node` apply only on `/rosout` and jointly keep the first `count` matching logs within the `start_s`/`end_s` window, and that `start_s` is measured from the bag's first message. Remaining parameters (path, topic) get no added meaning beyond schema text.

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

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

The first sentence names a specific verb and resource (peek samples from a recorded bag file) and immediately scopes it as offline/post-mortem, explicitly contrasting with `peek_dds_samples` and `sample_messages` which are live. An agent can distinguish it from every sibling 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?

It states when to use this tool (offline post-mortem on recorded bags) versus the live alternatives by name, and notes the ordering contract (first `count` messages, not newest like `sample_messages`). It also flags the ROS 1 `.bag` support that `analyze_bag` lacks, giving an explicit selection criterion between the two bag readers.

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 read-only and open-world annotations, the description discloses important behavior: payload decoding is disabled for user topics, such calls return a note and empty samples rather than proving silence, discovery can wait up to 3 seconds, and lock contention produces a retryable busy error. It also explains that the tool cannot publish and raises MCP errors when no DDS module is active or the topic is not announced.

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 purpose and sibling differentiation, then organized into builtin-topic and user-topic cases. It is dense and long, with some repetition of schema details, but most clauses carry operationally important edge cases.

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, error modes, discovery timing, and lock behavior, the description covers what an agent needs to call it correctly. An output schema exists, so return-value structure does not need to be spelled out further.

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 schema already documents both parameters, including the default, cap, and accepted topic forms. The description reinforces this with examples like `/scan`, `scan`, and `rt/scan`, but adds little 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 states a specific verb and resource: peeking recent samples on a raw DDS topic, returning a SampleResult. It explicitly distinguishes itself from `sample_messages` by reading from the DDS layer and working without ROS 2.

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 explicit branching guidance: builtin discovery topics return current-state records and should use `participant_events` for recent events, while `list_endpoints` should be used for user-topic presence, writers, readers, and QoS. It also explains error conditions and retry behavior when the DDS lock is busy.

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 read-only annotation, the description discloses QoS/latching behavior, timeout and truncation behavior, the 1 MiB cap, mock mode, MCP errors, lock contention and `busy` retry behavior, and total duration bounds. It never contradicts the annotations: it is consistently read-only and non-publishing.

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

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

The description is long and dense, but it is front-loaded with the graph/alternative caveat and then organized by mode, truncation, logging, summary/rate, and duration. Some parameter details duplicate the schema, which prevents a 5, but most sentences add useful operational context.

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 timeout, truncation, QoS, logging, and lock behavior, the description covers what an agent needs to invoke it correctly. An output schema exists, so it reasonably omits full return-value documentation while still explaining key result fields like `payload`, `note`, `summary`, and `rate`.

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 schema already explains each parameter, but the description adds operational meaning: `count` is the actual number returned, latched topics usually need `count` 1, and `node`/`min_log_level` apply only to `/rosout`. It also explains the practical effect of `max_array_length` and `arrays_summary_only` on large messages.

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

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

The description states a specific verb and resource: collect up to `count` live messages from a ROS 2 `topic` as a `SampleResult`. It immediately distinguishes the ROS 2 graph scope from DDS-only workflows by naming `list_endpoints` and `peek_dds_samples` as alternatives.

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 explicitly says this is for the ROS 2 graph only and routes DDS-only setups to `list_endpoints` or `peek_dds_samples`. It also distinguishes live versus mock mode and explains the `peek_bag_samples` ordering difference for log-style queries.

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 read-only annotations, the description explains status values, what null/zero values mean, the distinction between observed and declared frequency, error conditions, discovery wait, locking, duration, and busy retry behavior. This is unusually rich behavioral context for an agent.

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 front-loaded: purpose first, then critical status semantics, then limits, errors, and concurrency. Despite its length, every section provides operationally useful information with no evident 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?

Given the tool's complexity, existing output schema, and annotations, the description covers the critical gaps an agent needs: status interpretation, buffer limitations, domain behavior, errors, and timing. Nothing essential for correct invocation appears 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 schema already documents topic, window_s, and domain_id semantics thoroughly. The description reinforces window bounds and domain_id behavior but adds little parameter meaning beyond the structured 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 operation and resource: return temporal metrics for a DDS topic, naming frequency, sequence gaps, and latency percentiles. It clearly distinguishes the tool as a metrics-computation endpoint rather than a raw sample reader like peek_dds_samples.

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 operational guidance: read status first, and understand that the buffer is populated only when peek_dds_samples runs on the topic. It does not explicitly compare this tool against all sibling alternatives, so it stops short of a full when-to-use/when-not matrix.

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