set_sample_time

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

No annotations are provided, so the description carries the full burden of explaining side effects and behavior. 'Set capture length by time in seconds' describes the operation's surface intent but does not disclose whether this applies immediately to the next capture, whether it conflicts with previously set depth, or what other settings may be affected. The 'alternative to depth' hint is useful but not sufficient.

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, front-loaded sentence with no filler. Every word contributes to the core meaning: the action, the value type, and the relationship to the alternative sibling. This is an example of appropriately concise tool documentation.

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

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

For a one-parameter setter, the description is minimally viable: an agent knows to pass a number of seconds to define the capture length. However, it lacks contextual details such as when the setting takes effect, how it interacts with sample rate or depth, and whether any constraints apply. With no annotations and no output schema, the description could reasonably provide more surrounding 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%, and the only parameter is 'seconds' with type number. The description adds that this value represents the capture length in seconds, which helpfully maps the parameter to its real-world meaning. However, it provides no range, default, or constraints beyond the schema, so the description only partially compensates for the missing schema descriptions.

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

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

States a specific verb and resource: 'Set capture length by time in seconds.' It clearly identifies the operation and unit, and the parenthetical '(alternative to depth)' distinguishes it from the sibling set_sample_depth. This makes the tool's purpose immediately unambiguous.

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

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

The description gives an implied usage signal by calling itself an alternative to depth, which suggests choosing this tool when time-based capture length is desired rather than depth-based. However, it does not explicitly state when to prefer this over set_sample_depth or explain the relationship with capture/start. More direct guidance would improve this dimension.

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