add_transaction_controller

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

No annotations are provided, so the description must disclose side effects. It does reveal the key non-obvious behavior: child samplers are not reported separately but rolled up into a single transaction. It also names the usual parent type. It could add details like the effect of includeTimers or what happens with non-Thread Group parents, but the central behavioral trait is present.

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, roughly 30 words, front-loaded with the verb and target resource. The behavioral explanation earns its place and no redundant phrases are present.

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 definition explains what the tool does and the grouping effect, but it leaves the required planId parameter undefined in both schema and description. It also doesn't state return behavior or error conditions, though there is no output schema. For a simple add operation the core is covered, but a required identifier being undocumented is a gap.

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

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

Schema description coverage is 50%: name and includeTimers have descriptions; planId and parentId are bare. The description helps only parentId ('under the given parent (usually a Thread Group)'), while planId remains undefined in both schema and description. includeTimers is documented in the schema but not reiterated, so the description adds modest value beyond the structured fields.

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 the action explicitly ('Add a Transaction Controller') and the target hierarchy ('under the given parent (usually a Thread Group)'). The second sentence defines its unique purpose among sibling controllers: grouping samplers into a single named transaction, so an agent can distinguish it from add_loop_controller, add_if_controller, and 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 communicates when to choose it: when samplers should be timed and reported as one named transaction instead of individually. It also hints at placement (under a Thread Group). It doesn't explicitly name exclusions or alternative tools, but the functional explanation gives enough context to select it.

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