measure_chain

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

No annotations are provided, so the description carries the behavioral burden. It does disclose useful behavior: detail levels, long-list truncation to 25 items with a count, and token-cheap YAML default. However, it never explicitly states that this is a read-only inspection operation with no side effects, permissions, or failure modes, which would matter given the total absence of 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 definition is tightly packed: one scoping summary line followed by three parameter lines. Every sentence carries meaning, defaults are front-loaded, and there is no filler or repetition of schema-only information. The inline parameter format is slightly unconventional but efficient.

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-style topology query with zero required parameters and no output schema, the description covers the core invocation details: scope, output granularity, and response format. It is slightly incomplete in that key terms like 'Bypass/Src/Srcpath truth' and 'chain orphan detection' are not expanded, and there is no example return shape, but the agent can still call it correctly with the provided information.

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 parameter description coverage is 0%, but the description fully documents all three parameters: path's root-container purpose and default '/', detail's three allowed values with their output implications, and response_format's yaml/json options with the token-cheap rationale. This substantially compensates for the empty schema and gives the agent actionable semantics.

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

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

The summary line names a specific resource and operation: per-device topology analysis with Bypass/Src/Srcpath truth and chain orphan detection for chained COMPs. It is specific enough to distinguish measure_chain from performance-oriented siblings like measure_fps or measure_cooktimes, though it does not explicitly name a sibling or use a clean 'verb + resource' form.

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

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

The description states what the tool measures but gives no explicit guidance on when to choose it over alternatives such as measure_verify or node_list. There are no when-to-use, when-not-to-use, or alternative-routing statements, so the agent must infer applicability from the domain jargon in the summary line.

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