add_user_parameters

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

With no annotations, the description carries the behavioral burden and does so well: it discloses that values are cycled by thread number and applied once at thread start unless perIteration is true. It does not cover mutation side effects, permissions, or failure modes, but the 'Add' verb plus placement context makes the core intent clear.

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 tightly written sentences with no filler. The core behavior is front-loaded, the perIteration nuance is included, and the sibling distinction earns its place at the end.

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

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

For a mutation tool with no annotations and no output schema, the description is solid: it defines element type, placement, data semantics, and the key alternative. It does not disclose return shape or error behavior, but those are minor for this kind of add-element operation and the description covers the essential agent decision-making 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 coverage is low (33%), so the description must compensate. It meaningfully explains valueSets as per-thread value sets cycled by thread number and defines perIteration's timing effect, while also implying parentId is the target Thread Group. planId and variableNames are not explicitly expanded, but their meanings are inferable from names and context.

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 ('Add'), a specific resource type ('User Parameters pre-processor'), and a placement target ('under a Thread Group'). It also differentiates the behavior from add_user_defined_variables, so an agent can distinguish this tool without opening the schema.

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

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

The description explicitly names the closest alternative, add_user_defined_variables, and explains the deciding difference: per-thread values vs. the same values for every thread. It also clarifies when perIteration changes the behavior, giving clear selection context.

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