Bagel

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

Annotations already mark destructiveHint and idempotentHint. The description adds valuable non-obvious behaviors: bare slugs are rejected due to shadowing, builtins refuse deletion, and unknown names raise instead of silently no-op-ing while listing existing user capabilities. 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?

Three dense sentences each add necessary information: the operation and source, the exact-name requirement and rationale, and the error behavior. No filler or repetition of 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?

With a single required parameter degraded by 0% schema coverage, the description fully compensates by explaining valid input, scope restrictions, and failure modes. Since an output schema exists, return-value documentation is not required here.

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 carry the semantic burden for the name parameter. It does so thoroughly: exact full name, user/ prefix, source via list_agent_capabilities, and rejection of bare slugs. This is far more useful than the raw 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?

The description opens with a specific verb and resource: 'Delete a capability previously saved with `save_agent_capability`'. It clearly scopes the tool to user-saved capabilities and distinguishes it from builtins, making it unambiguous among siblings like save_agent_capability and list_agent_capabilities.

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 concrete input guidance: use the exact full name list_agent_capabilities reports, with the user/ prefix, not a bare slug. It also states an explicit when-not case: builtins cannot be deleted and will refuse with a clear message.

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 directly contradicts the idempotentHint: true annotation: it explicitly states that deleting an unknown name raises and 'a second delete of the same name also raises,' meaning repeated calls with the same arguments produce an error rather than a harmless repeat. Per the rubric, a contradiction with annotations forces a score of 1. The safety-confinement and error-behavior details are otherwise excellent, but the idempotency conflict is a serious signal for an agent deciding whether re-invocation is safe.

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?

Three sentences, front-loaded with the core purpose, and every clause adds a distinct safety or behavioral fact (provenance, directory confinement, refusal-before-touch, error-on-unknown, re-delete raising). The heavy use of em-dash parentheticals makes the sentences dense and requires careful parsing, but there is no wasted wording.

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 a single parameter, an output schema present, and annotations covering destructiveness, the description covers everything needed to invoke correctly: name provenance, path-confinement safety, and error behavior. The one gap is that the conflicting idempotency signal between the annotation and the description leaves the agent with ambiguous guidance about repeat calls, which keeps this from being fully complete.

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

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

Schema description coverage is 0% and the bare schema offers only a 'Name' string, so the description carries the full burden for the name parameter and meets it completely: it specifies that the name must have been written by save_pipeline, must match what list_pipelines reports, must not resolve outside the trusted directory, and that unknown names raise with a list of existing names. An agent can determine exactly what value to pass and what will happen if it is wrong.

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 precise verb+resource statement: 'Delete exactly one pipeline YAML file previously written by save_pipeline, by the same name list_pipelines reports.' It names the exact resource, scopes it to previously saved pipelines, and connects to the two sibling tools that define valid names, which cleanly separates it from delete_capability and the run/preview pipeline 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 tells the agent where valid names come from (save_pipeline / list_pipelines) and frames the safety contract: there is no directory argument, so the tool is confined to settings.PIPELINES_DIRECTORY and refuses out-of-directory names before touching anything. It does not, however, explicitly state when not to use it or name an alternative tool for deleting other resources, so it stops just 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: it discloses that no message rows or anomalies are returned, and that path resolution and runtime/schema support depend on the selected service. This helps set expectations and avoid misinvocation.

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?

Three sentences with no filler. The primary action is front-loaded, the sibling alternative follows immediately, and the exclusions and service dependency are packed into the final sentence. 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?

The tool has an output schema, so return value details need not be in the description. Purpose, workflow ordering, exclusions, and server-side behavior are all covered. The only gap is parameter semantics (especially args), which prevents a perfect score, but the overall context is strong for a simple read-only inspection tool.

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

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

Schema description coverage is 0%, so the description must compensate for both parameters. It only mentions that 'Paths are resolved on the Bagel server', which hints at the path parameter but does not explain its format or semantics. The optional args parameter is entirely undocumented, leaving a clear gap for a required-parameter 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?

Description opens with a specific verb and resource: 'Inspect a robotics, drone, or IoT log first'. It clearly states what the tool returns ('source metadata, available topics, and instructions') and differentiates from the sibling describe_topic by prescribing it as the next step for field schemas. No ambiguity remains about what this 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?

Explicitly says to use this tool 'first' and directs the agent to 'Use describe_topic next for field schemas before SQL', giving an exact sequence and alternative. It also states exclusions ('Does not return message rows or detect anomalies') and notes server-side path resolution, making the invocation context unambiguous.

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

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

Annotations already mark the operation read-only, idempotent, and non-destructive. The description adds non-obvious behavioral traits: it returns schema, definition, and query instructions but not message rows, and explicitly warns against inferring units from field names. 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?

Three sentences, front-loaded with the action and purpose. Each sentence adds distinct value: when to use it, what it returns, and a critical data-interpretation warning. There is 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?

For a read-only inspection tool, the description covers when to call it, what it returns, and a critical unit-safety warning. An output schema exists to detail return values, but the input parameters are not fully defined, which is a minor completeness gap.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies that 'topic' is a known topic and references describe_data_source for discovery, but it never defines 'path' or the optional 'args' object, leaving required inputs under-specified.

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 action—inspect a known topic—and the resource (a topic in a data source). It explicitly distinguishes itself from describe_data_source by pointing to that tool for discovering topic names, so an agent can select the right one.

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 usage as a pre-step before writing SQL or event predicates, and directs topic discovery to describe_data_source. It does not explicitly name query_messages as the alternative for retrieving message rows, though the 'without message rows' clause implies that boundary.

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?

Discloses behaviors beyond annotations: confirms it writes a new dataset (consistent with readOnlyHint false), implies idempotency (consistent with idempotentHint), describes LOCF resampling, mentions return values (dataset directory, counts, loading instructions), and notes beta status with a specific caveat. These details add substantial transparency not captured in 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?

Three sentences, front-loaded with purpose and process, then returns, then usage guidance and beta caveat. Every sentence adds value without redundancy or irrelevant detail.

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?

While the description covers high-level behavior and return values, it omits any explanation of the 9 parameters, including nested structures like 'features' and 'episodes'. Given the complexity and zero schema coverage, the agent lacks essential input semantics. The beta note and usage guidance are helpful but do not compensate for this 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 description provides zero parameter-specific semantics. It mentions 'scalar signals grouped into feature vectors' and 'uniform fps' but does not explain how parameters like 'features', 'episodes', 'topics', 'task', or 'path' map to the schema. With 0% schema coverage, this is a critical gap for an agent to construct valid inputs.

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 ('Write') and resource ('event windows as a LeRobotDataset v3.0'), details the conversion process (episode per window, feature vector grouping, LOCF resampling), and differentiates from sibling export tools by naming the target format and use case. An agent can clearly distinguish this from export_for_plotjuggler, export_for_rerun, and export_for_lichtblick.

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 instructs when to use ('Choose this for robot-learning dataset preparation') and when not ('not interactive viewing or model training'). While it doesn't name alternative tools, the guidance is unambiguous and sufficient to route the agent correctly.

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 include idempotentHint=true and destructiveHint=false. The description adds meaningful behavioral context beyond this: it writes files, auto-selects up to eight numeric plot curves, returns paths/curves/instructions, and does not launch a viewer. 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?

Three sentences carry all key information without fluff: purpose, alternatives, usage constraint, parameter hints, and limitations. The most important action is front-loaded.

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

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

The description covers the core workflow, output nature, and viewer behavior, and the output schema covers return values. However, the meaning of path, topics, name, and args is not fully specified, so an agent may need to infer whether path is the output destination, a directory, or a file prefix.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies units for start_seconds/end_seconds and explains the optional signals behavior and default auto-selection, but it leaves path, topics, name, and args semantics mostly implicit, which is a significant gap for a 7-parameter 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 states a specific action ('Write a selected time window as JSON-encoded MCAP plus a plot layout') and clearly identifies the target viewers (Lichtblick or Foxglove). It distinguishes itself from byte-preserving native ROS/CDR export, which is meaningful given sibling export tools for other viewers.

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 tells the agent when to choose this tool ('Choose this for those viewers') and when not to ('not byte-preserving native ROS/CDR export'). It also gives practical constraints: inspect topic schemas, use source timestamps in seconds, and remember that the viewer is not launched.

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 annotations already marking this as non-read-only, non-destructive, and idempotent, the description adds useful behavioral details beyond them: it returns paths, plotted curves, and an opening command, automatically selects up to eight numeric curves unless signals are specified, and does not launch the viewer. These disclosures help an agent set expectations around side effects and output.

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: the core output behavior and purpose come first, followed by selection guidance, parameter hints, and a launch caveat. Every sentence contributes information, and there is no redundant restating of the title or 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?

The description covers the main workflow, output, and key behavioral constraints, and an output schema exists to define return values. Still, with 7 parameters and no schema-level parameter descriptions, the omission of path, name, and especially the free-form args object leaves the definition incomplete for an agent that needs to construct a fully correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It adds real meaning for start_seconds/end_seconds ('inclusive source timestamps in seconds'), signals ('unless signals are specified'), and topics ('Inspect topic schemas'). However, path, name, and args remain undocumented in both the schema and the description, which leaves meaningful gaps for a 7-parameter 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 names a specific verb and resource: writing a selected time window as flattened scalar CSV plus a PlotJuggler XML layout, with return values also stated. It also distinguishes itself by saying 'Choose this for scalar plotting in PlotJuggler, not native bag preservation', which sets it apart from sibling export tools like export_for_rerun and export_for_lichtblick.

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 when to use this tool ('Choose this for scalar plotting in PlotJuggler') and what it is not for ('not native bag preservation'). It also adds practical context such as inspecting topic schemas and using inclusive source timestamps in seconds, but it does not name a specific alternative tool for bag preservation.

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 idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it requires a separate viewer, does not launch the viewer, does not produce camera/3D replay, and instructs to inspect topic schemas and use source timestamps in seconds. 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?

Three sentences with no filler. The core action and return value are front-loaded, followed by usage conditions and exclusions. 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?

The description covers purpose, prerequisites, exclusions, and return value. With an output schema present, the return value doesn't need full enumeration. The only minor gap is that it doesn't explain the 'signals' parameter's relationship to 'topics' in detail, but the scalar time series framing and output schema compensate.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the core parameters conceptually: 'selected time window' maps to start_seconds/end_seconds, 'scalar time series' maps to topics/signals, and 'returns its path' maps to path. It doesn't enumerate each parameter, but it gives enough semantic framing for an agent to understand the tool's purpose. The 'use source timestamps in seconds' note adds crucial unit semantics for the time 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 states a specific verb ('Write'), a resource ('selected time window as scalar time series in a Rerun .rrd recording'), and the return value ('path, signals, and an opening command'). It also distinguishes itself from other exporters by naming the Rerun format and explicitly noting it does not produce camera/3D replay.

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 when-to-use guidance ('Choose this when the user requests Rerun'), prerequisites ('Requires rerun-sdk (uv sync --group viz) and a separate viewer'), and exclusions ('does not produce camera or 3D scene replay and does not launch the viewer'). This clearly routes an agent away from sibling exporters like export_for_plotjuggler or export_for_lichtblick.

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, idempotentHint, destructiveHint), the description adds meaningful behavior: the pipeline is confined to settings.PIPELINES_DIRECTORY and names resolving outside it are refused. This security-relevant boundary is valuable for an agent to know before 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?

Two sentences with no filler. The primary purpose is front-loaded, the workflow context follows, and the security constraint is stated last. 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?

For a single-parameter read tool with an output schema and comprehensive annotations, the description is complete: it explains what is returned, how the parameter is sourced, and the filesystem safety constraint. 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?

The schema provides only 'name' as a string with no description, so the description carries the full burden. It clarifies that name must be one saved by save_pipeline and reported by list_pipelines, and that it must resolve within the trusted directory, adding critical 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 an exact verb and resource: 'Return the full configuration of one pipeline saved by save_pipeline'. It also names the related tools list_pipelines and run_pipeline, making the tool's role in the pipeline lifecycle clear and differentiating it 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 gives clear workflow context by explaining the returned configuration can be inspected, edited, saved again, or passed to run_pipeline, and identifies list_pipelines as the source of valid names. It does not explicitly state when not to use it, but the usage context is strongly implied.

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 readOnly, idempotent, and non-destructive behavior. The description adds meaningful behavioral context beyond that: it names the sources of capabilities, the supported file extensions, the user/ prefix convention, and the fields returned, which helps the agent trust and use the result 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 description is three sentences with no wasted text. It front-loads the core purpose, then adds only high-value details about scope, return fields, and usage intent.

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 zero-parameter listing tool with an output schema and strong annotations, the description is complete. It tells the agent what will be listed, what each entry contains, and how the results connect to run_poml_capability, so no critical information is missing.

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

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

The tool has zero parameters, so there is nothing for the description to clarify at the parameter level. The baseline 4 applies, and the description compensates by explaining what the returned path is for, which is the most semantically relevant 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 uses a specific verb ('List') and names the exact resource: every capability available to run, including predefined .poml capabilities and user-saved capabilities. It also distinguishes itself from related tools by tying entries to run_poml_capability and clarifying it is not about guessing file paths.

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 usage context: use this to discover available capabilities instead of guessing file paths. It does not explicitly exclude alternatives like list_pipeline_capabilities, but the focus on agent capabilities and run_poml_capability makes the intended use 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 declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds valuable behavioral context beyond that: it returns names 'without starting a persistent recording' and requires a reachable service, which informs the agent about network dependency and side-effect-free 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?

Three concise sentences, front-loaded with the core purpose. Every sentence earns its place: purpose, supported types, prerequisites, side-effect note, and alternative. 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?

With an output schema present, return format isn't needed. The description covers purpose, type_ values, network requirements, and the alternative tool. It could elaborate on host/port defaults or pagination, but for a listing tool it's adequately complete.

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

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

Schema description coverage is 0%, so the description must compensate. It lists supported type_ values explicitly ('mqtt, ros1.bridge, ros2.bridge') and mentions host/port defaults. However, the 'args' parameter is completely unexplained, and host/port are only vaguely referenced without format or default values.

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 ('Discover') and resource ('topic names from a live broker or ROS bridge') and clearly differentiates from siblings by noting 'before subscribing' and explicitly routing to 'describe_data_source for an existing recorded log'. An agent can immediately tell what this tool does and how it differs from similar 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 it before subscribing, requires a reachable service, and points to the alternative describe_data_source for recorded logs. It doesn't explicitly state when NOT to use it, but the alternative condition 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context about return contents (module paths, constructor parameters, summaries, availability) and clarifies that these are executable building blocks rather than saved workflows.

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?

Two sentences with no filler. The purpose is front-loaded, and the second sentence efficiently adds return details and sibling-tool routing.

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 largely complete for selection and invocation: it states purpose, timing, return contents, and alternatives. The only gap is the include_unavailable parameter, which is simple enough that the schema title and default mostly cover it, and an output schema exists for return details.

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 of explaining the include_unavailable parameter, but it never mentions it. The schema title and default provide some meaning, but the description does not add value beyond that.

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: 'Discover available task and gate modules before authoring pipeline YAML.' It also explicitly distinguishes itself from list_pipelines and list_agent_capabilities, so an agent can tell them apart without inspecting schemas.

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 timing ('before authoring pipeline YAML') and names alternatives with the conditions that select them: 'use list_pipelines for saved configs and list_agent_capabilities for reusable agent instructions.' This fully routes the agent to the correct tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description does not need to restate safety. It adds value by explaining the exact content of each entry (name, path, one-line summary with task count, site/asset, cadence), and implicitly communicates that this is a non-mutating discovery operation. There is no contradiction between description and 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 two sentences, front-loaded with the core purpose and output details, then a usage hint. No waste, and every sentence contributes meaning. It is appropriately concise for a simple read-only listing tool.

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

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

Given zero parameters, a rich output schema (implied), and annotations covering safety, the description fully covers what an agent needs: it specifies what is listed, where from, and why to use it. Nothing crucial 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 has zero parameters and schema description coverage is 100% (vacuously). The description clarifies that the list is scoped to the trusted pipelines directory (`settings.PIPELINES_DIRECTORY`), which adds meaning beyond the empty schema. Baseline for 0 parameters is 4, and the description meets it.

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

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

The description clearly states the specific action (list) and resource (pipeline YAML files saved by `save_pipeline`), and details the output fields (name, path, summary). It differentiates from sibling tools like save_pipeline and delete_pipeline by focusing on discovery and referencing the trusted pipelines directory.

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: before reusing, editing, or deleting a saved pipeline, and cautions against guessing file names. While it does not explicitly name alternative tools or when not to use it, the guidance is actionable and points to the intended workflow.

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, idempotentHint=true, destructiveHint=false, so the description correctly aligns with these (no contradiction). It adds valuable behavioral context beyond annotations: it mentions learning a rolling baseline, modeling screen mode, every: N cadences, and gate ordering (list anomaly gate first). It also notes what it does NOT do (calling decision model, writing artifacts), which helps set expectations. Minor deduction for not explicitly stating output schema details, but the output schema is provided separately.

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 efficiently packed, with multiple clauses per sentence. It front-loads the purpose and main output, then adds usage guidance. However, it is a long paragraph that might be better split into sections (e.g., purpose, usage, behavior) for readability. It's not overly verbose relative to the complexity, so it earns 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 tool's complexity (12 params, output schema rich, many siblings), the description covers the essential decision points: when to use (before saving an anomaly pipeline), what it returns (flag counts, z-scores, advice), what inputs to avoid (positions/orientations), and how it models the anomaly gate. The output schema likely lists the return structure, so return values aren't needed in the description. It is complete for an agent to decide and call 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 default values and types but zero descriptions for parameters (0% coverage). The description compensates by explaining the meaning of key parameters: 'signals' must be rates/errors, not positions/orientations; 'window_seconds' is part of the required params; mentions cadence and warm-up concepts, which map to cadence_seconds and warmup_minutes. It doesn't explicitly define every parameter (like max_signals, z_threshold), but the context is enough for an agent to infer their roles from the defaults and overall description. Given the high parameter count (12) and low schema coverage, this is a strong effort.

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 does a dry-run of the anomaly gate over a recorded log, specifying the verb (preview/dry-run), resource (anomaly screen/gate), and scope (on a log, no decision model or artifacts). It distinguishes from siblings like preview_pipeline by emphasizing on-robot real-time screen behavior and the anomaly gate specifically, and it provides a concrete list of output types (flags, z-scores, advice).

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 says 'Inspect topics first and pass signals as rates and errors... never positions or orientations' and 'Use it to choose signals and thresholds before saving an anomaly pipeline'. It also hints at when not to use it implicitly by requiring a recorded log and the specific screening mode. This gives clear prerequisites and a purpose that distinguishes it from other preview/run 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?

Beyond the readOnly/idempotent annotations, the description discloses concrete behavior: detecting false-to-true transitions, debouncing events, merging overlapping windows, and returning timestamps, intervals, and kept seconds/fraction. The explicit caveat that it does not predict output byte size adds useful limitation 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 three dense but purposeful sentences: purpose, input constraints and behavior, then workflow and limitation. Every sentence earns its place and the core purpose is front-loaded.

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

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

It covers behavior, outputs, input constraints, the required confirmation workflow, and a known limitation, while the output schema handles return-value detail. The remaining gap is the under-specified path, event_topic, and args semantics, which keeps this from being fully 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?

With 0% schema description coverage, the description must compensate, and it partly does: predicate is a SQL boolean, pre/post seconds are nonnegative, and debounce_seconds maps to debouncing nearby events. However, path, event_topic, and especially the catch-all args parameter remain semantically unexplained beyond their schema titles.

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

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

The description opens with a specific verb and resource: 'Preview an event-window reduction without writing artifacts.' It also distinguishes itself from the run_pipeline siblings by explicitly framing this as a pre-execution preview step.

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

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

It gives clear usage context: inspect source and topic schemas, provide a SQL predicate and nonnegative pre/post seconds, then report results and get user confirmation before running run_pipeline or run_pipeline_batch. It does not provide explicit when-not-to-use exclusions beyond the byte-size caveat.

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, and non-destructive behavior. The description adds valuable context beyond that: time bounds are 'inclusive source timestamps in seconds, not offsets from the first message,' and the return format is 'rows as dictionaries.' It also mandates showing the SQL to the user, which is a behavioral requirement not captured in annotations. No contradiction 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?

The description is three packed sentences, front-loaded with purpose, then usage prerequisites, then time semantics. Every sentence earns its place; there is no filler or redundant restatement of the title or annotations. It is concise without sacrificing critical 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?

Given the tool's complexity (SQL over messages, six parameters) and that an output schema exists, the description covers the essential context: prerequisites, output format, usage pattern, and time semantics. It does not explain 'path' or 'args', which might be non-obvious, but the presence of an output schema reduces the need to describe return structure. Overall, it is fairly complete for a read-only query 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 schema description coverage at 0%, the description must compensate for parameter meaning. It clarifies start_seconds and end_seconds as inclusive source timestamps in seconds, and implies topic is the single topic being queried. However, it leaves 'path' and 'args' unexplained. This is partial compensation but not complete, so a mid-range score 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?

The description states a specific verb and resource: 'Answer quantitative questions with read-only DuckDB SQL over one topic.' It clearly distinguishes from siblings like read_loggings (textual diagnostics) and describe_topic (schema description) by emphasizing quantitative SQL querying on a single topic. The mention of 'filtering, aggregates, downsampling, and event evidence' further specifies the tool's scope.

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, actionable usage guidance: 'Call describe_data_source and describe_topic first; use the returned schema and show the SQL to the user.' It also provides an explicit alternative: 'Use read_loggings for textual diagnostics.' This tells the agent exactly when to use this tool versus a specific sibling, and the prerequisite sequence 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 declare readOnly, idempotent, and non-destructive behavior. The description adds useful context: returns logging records or an empty list when no topics exist, inclusive time bounds in seconds, and a semantic caveat about empty logs. 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?

Three sentences with no wasted wording: purpose first, then return behavior, then routing to the alternative tool. 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?

Rich annotations, an output schema, and sibling context cover safety and return structure. The description covers purpose, time bounds, empty-list behavior, and alternatives. The only notable gap is the meaning of the optional args parameter.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies start_seconds and end_seconds as inclusive bounds in seconds, but leaves the required path and the opaque args parameter unexplained. This is only partial compensation for four undocumented 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?

Description uses a specific verb ('Read') and resource ('textual INFO/WARN/ERROR diagnostics from a recorded source'), and explicitly contrasts with query_messages. An agent can distinguish this tool from siblings without opening schemas.

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 directs numerical signals, statistics, and threshold detection to query_messages, and warns that empty diagnostics do not prove a healthy log. This gives clear when-to-use and when-not-to-use 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 indicate non-read-only, open-world behavior, but the description adds concrete side-effect context: tasks may write files or contact external services, and status should be inspected for failures. It does not cover auth or rate limits, but with annotations carrying the broad safety profile, this is a minor gap.

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?

Four sentences deliver action, workflow prerequisite, return behavior, side effects, and alternatives with zero filler. The key execution semantics are front-loaded, and every sentence contributes.

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 run tool with side effects, the description covers preconditions, confirmation flow, return inspection, and sibling routing. The main gap is the under-specified config object, which is more a parameter semantics issue; overall, an agent has enough context to call this tool safely and 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 must compensate, and it partially does by identifying config as a pipeline config and naming config.path as the execution target. However, it does not document the expected type, format, or any other config fields, leaving an open object with minimal 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 clearly states the tool executes a pipeline config and even cites the specific config.path that drives execution. It differentiates from siblings by naming save_pipeline (store without executing) and run_pipeline_batch (multiple sources), so an agent can distinguish it without opening schemas.

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 guidance for event reductions: call preview_pipeline first, report events and kept seconds, and get user confirmation. It also names alternatives and the conditions for choosing them, making when-to-use and when-not-to-use unambiguous.

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 indicate side effects (readOnlyHint=false), external interactions (openWorldHint=true), and non-idempotency (idempotentHint=false), but the description adds crucial context: 'Tasks may write files or contact external services' reinforces the side-effect risk. It also explains that each source runs independently and returns per-source statuses/errors and totals, which is behavior not in the annotations. The glob-literal-path fallback is a specific behavioral disclosure. This adds value beyond annotations, though it doesn't exhaustively cover all behavioral nuances (e.g., partial failure handling), so a 4 is appropriate.

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 five sentences, each serving a distinct purpose: the core action, the independent execution and return shape, the confirmation requirement for event reductions, the side-effect warning, and the single-source alternative plus glob edge case. It is front-loaded with the primary function, and there is 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 (batch execution, side effects, potential confirmation requirement) and the presence of an output schema (which presumably details the return structure), the description covers what an agent needs: the operation, how config.path is overridden, side-effect caveats, the guidance to preview for event reductions, the single-source alternative, and the glob edge case. Nothing critical for a correct invocation 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 must compensate. It does: 'paths' are described as 'explicit source paths or globs', and the config is 'one pipeline config' with the behavior that it overrides config.path for each source. This explains the meaning and relationship of both parameters. While it doesn't enumerate all possible config fields, it gives sufficient semantics for an agent to construct valid inputs.

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: 'Execute one pipeline config for multiple explicit source paths or globs'. It clearly identifies the resource (pipeline config) and the batch nature, and explicitly differentiates from the sibling run_pipeline by noting 'Use run_pipeline for a single source.' An agent can unambiguously determine what this tool does and when to select it.

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: it tells the agent to use run_pipeline for a single source instead, and instructs to preview sources before execution for event reductions and obtain confirmation of batch scope. This directly addresses when to use and when not to use the tool, going beyond mere implication. It also warns about the glob-matching-nothing edge case, adding operational 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 provide readOnlyHint=true and destructiveHint=false, but the description adds valuable behavioral context: it clarifies the tool returns a prompt, does not analyze data or write artifacts, and explains a critical difference between POML and Markdown regarding template context. This goes well beyond the structured annotation 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?

Three sentences, each earning its place: purpose, discovery, context behavior, non-effects, and alternative. The purpose is front-loaded, and there is no redundant or vague wording.

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, read-only tool with an output schema, the description covers what it does, what it doesn't do, how to find inputs, and when to choose a sibling tool. No critical information 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?

With schema description coverage at 0%, the description fully compensates by explaining poml_path as a path discoverable via list_agent_capabilities and poml_context as template context, including the rule that Markdown rejects nonempty context. Both parameters are meaningfully described beyond their raw 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 uses a specific verb ('load') and resource ('reusable agent instructions from a POML or Markdown file') and explicitly states the return value ('returns a prompt for the calling agent to follow'). It distinguishes itself from siblings by referencing list_agent_capabilities for path discovery and run_pipeline as the alternative for executable pipeline configs.

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 when-to-use guidance: 'Discover paths with list_agent_capabilities' and 'Use run_pipeline for an approved executable pipeline config'. Also gives a clear exclusion—'Loading the prompt does not itself analyze data, execute a pipeline, or write reduction artifacts'—so an agent knows this is not for execution 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 indicate destructiveHint and idempotentHint, but the description adds valuable details: it validates POML before saving, supports context parameterization, and restricts writes to the user-capabilities directory. It also clarifies that builtin capabilities cannot be modified, which is a behavioral constraint not obvious from the schema.

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

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

The description is concise and well-structured. It front-loads the purpose, then details content formats, and ends with a scoping constraint. Every sentence adds value without redundancy, making it easy 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 provides sufficient information for an agent to call the tool correctly: it explains the purpose, content format, and directory scope. Since an output schema exists, the return format does not need to be described. The only minor gap is the semantics of the overwrite parameter, which is not mentioned but is a boolean with a default in the schema, so it is discoverable.

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 must explain parameters. It does explain 'content' by specifying allowed formats (POML with validation and context parameterization, or plain markdown). It implicitly refers to 'name' as 'named capability', but it does not explain the 'overwrite' parameter at all, leaving its behavior unspecified. The description adds some meaning but does not fully compensate for the lack of schema documentation.

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

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

The description clearly states the verb 'Save' and the resource 'a reusable workflow as a named capability'. It also differentiates from siblings by specifying the destination directory and that builtin capabilities cannot be modified, making it distinct from tools like delete_capability or save_pipeline.

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 save a reusable workflow as a capability for future sessions. It also gives context on content formats (POML or markdown) and a constraint (builtin cannot be modified), which implicitly guides when not to use it. However, it does not explicitly name alternative tools or provide direct comparisons with 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 discloses that the operation writes to a YAML file and returns the file path, which adds useful behavioral context. It does not mention overwrite behavior or file-naming conventions, but the annotations already cover idempotency and non-destructiveness.

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 a single sentence that front-loads the action and resource, includes the key return value, and contains no filler. It is appropriately sized for the tool's purpose.

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

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

For a tool with three parameters and zero schema descriptions, the description leaves too much unspecified—config shape, directory behavior, file extension, and overwrite semantics. The return path is stated, but an agent cannot reliably construct arguments from the description alone.

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

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

Schema description coverage is 0%, and the description provides no meaningful detail about the 'config' object structure, the 'name' parameter, or the optional 'directory'. The generic phrase 'pipeline configuration' is the only hint and is insufficient 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 uses a specific verb ('Persist') and clearly identifies the resource ('pipeline configuration') and output format ('YAML file'). It is clear about what the tool does, though it does not explicitly differentiate from sibling tools like run_pipeline or preview_pipeline.

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 'so it can be reused, edited, or run later with run.py' provides clear context for when to use the tool. However, it does not explicitly state when not to use it or name 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?

All annotations are false, so the description carries the full burden, and it performs well: it discloses auto-detection behavior, the side-effect of writing a WaffleForm, the dependency footprint, and the post-condition of data-source queryability. Could be stronger with failure modes (e.g., what happens if no robot is available, whether the directory is created). Not a contradiction, just an opportunity for more.

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?

Three tightly-scoped sentences: purpose, prerequisite/installation context, and side-effect/composition note. There is zero filler, and the most important information (what it does) is front-loaded. Every sentence adds distinct 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?

For the tool's complexity (1 optional param, no nested objects, output schema present), the description covers the essentials: core behavior, setup prerequisite, and downstream consumption model. Gaps include the role of the `directory` parameter and what happens on failure, but for a tool of this size these are minor. The description respects the line of what structured fields already convey and adds meaningful orchestration 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 burden falls on the description to explain the `directory` parameter, but it's never mentioned. The schema itself only gives a name and default ('.'), so an agent must guess whether it's the output destination, the robot's config directory, or a scan root. Given the description does zero compensation for its single parameter, a 2 is appropriate here.

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 uses a specific verb-resource pair ('Auto-detect the robot's current hardware, firmware, and software') and clearly states the output ('return the resulting hardware state' and 'writes a WaffleForm'). It clearly distinguishes this from siblings like run_pipeline or query_messages by establishing a unique outcome (queryable data source) and the experimental beta caveat in the title adds useful maturity context.

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?

Discloses a hard prerequisite ('Requires the waffle CLI on PATH (cargo install waffle-iron)') and implies when it's useful by noting the output is 'immediately queryable as a data source.' It stops short of explicitly naming alternatives or excluding contexts (e.g., 'don't use for X, use save_pipeline instead'), so it loses a point here, but the practical when-to-use context is well covered.

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 (destructiveHint=true, readOnlyHint=false), the description discloses that it runs in the background, persists messages locally, may continuously write/upload artifacts via an optional pipeline, and that overwrite=True clears existing topic buffers. These are meaningful behavioral details the agent would not otherwise know.

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 core action and return value. Every sentence adds useful context: sequencing, pipeline caveat, overwrite behavior, lifecycle, and an exclusion. No filler or redundancy.

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

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

Given the tool's complexity and the presence of an output schema, the description covers the essential operational context: background execution, local persistence, returned sink directory, optional artifact-writing pipeline, destructive overwrite behavior, and how to stop the subscription. Nothing critical is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It does explain type_ (mqtt, ros1.bridge, ros2.bridge), overwrite (clears buffers), and pipeline (continuous processing, may write/upload). However, it leaves host, port, topics, and particularly the opaque args object semantically unexplained, though some are inferable from their names.

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 ('Start a background subscription'), the resource types (mqtt, ros1.bridge, ros2.bridge), and the purpose (persist messages locally and return a sink directory). It clearly differentiates from siblings by saying to use list_live_topics first, to stop with unsubscribe_live_topics, and that it is not for inspecting an existing file.

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 sequencing ('Use list_live_topics first'), the lifecycle counterpart ('Stop it with unsubscribe_live_topics'), and an exclusion ('Not for inspecting an existing file'). This is strong guidance on when and how to use the tool relative to 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?

The description goes well beyond the annotations by disclosing that standing pipelines finish queued and end-of-stream runs first, may write or upload artifacts, that recorded messages remain in the sink directory, that the connection closes when nothing remains subscribed, and that the tool never opens a connection. These details meaningfully describe side effects and error behavior. No contradiction with the annotations is apparent.

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 information-dense with no wasted words and front-loads the core action. It is slightly long with several caveats, but each sentence contributes necessary behavioral 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?

The description covers the lifecycle of the operation: what is stopped, how to stop all, pipeline completion, artifact effects, retained recordings, connection closing, and the no-connection error case. This is sufficient for an agent to invoke the tool correctly without needing more context.

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

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

Schema description coverage is 0%, so the description must compensate. It does explain that type_, host, and port must match a running subscription and that omitting topics stops all topics. However, it does not clarify the meaning of null/default host and port values, nor the exact accepted values for type_, leaving some ambiguity 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 uses a specific verb ('Stop') and a precise resource ('topics started by subscribe_live_topics'), and ties it to a running mqtt, ros1.bridge, or ros2.bridge subscription. It clearly distinguishes this tool from its inverse sibling, subscribe_live_topics, and from list_live_topics.

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

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

The description makes the intended use clear: stop matching live topic subscriptions, with the explicit option to omit topics to stop all. It also gives an important boundary condition by stating that it errors when no running subscription exists. It does not explicitly contrast with other siblings, but the counterpart tool is named and the usage context is unambiguous.

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