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

Beyond the destructive/non-idempotent annotations, the description discloses the side effects that matter: changed paths are locked against other experiments and configuration edits until the experiment ends, creation happens immediately on this call, the reason is recorded with the change, and a default start time applies. What it omits is what the call returns and what happens on validation failure (e.g. mismatched baseValue), so it is strong but not exhaustive.

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?

Front-loaded with the core action and organized from mechanics to prerequisites to guardrails, with no filler sentences. It is dense at roughly seven sentences, and 'The experiment is created when this runs' restates the obvious mutation, but every other sentence carries load-bearing guidance.

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 four-parameter but deeply nested request with no output schema, the description covers the failure-prone parts (fresh baseValue, lock conflicts, skill prerequisite, immutability) that an agent would otherwise get wrong. The remaining gap is the absence of any mention of the response or what identifiers come back after creation.

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 75% and the schema itself documents many fields, yet the description still adds meaning the schema does not: baseValue must equal the real current value in the base configuration, weights must total 100, and reason is what the approver reads. It does not elaborate on rollout, targeting, or assignmentMode, leaving those entirely to 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?

States a specific verb and resource ('Create an A/B experiment on a configuration') and immediately explains the mechanism (groups apply set/add/delete operations to assigned units, weights split eligible units), which separates it cleanly from preview_experiment, get_experiment, terminate_experiment, and update_experiment_rollout.

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?

Gives explicit prerequisite sequencing: load the manage-experiments skill first, read exact current values via get_configuration or search_configuration and pass them as baseValue, and check list_experiment_locks for already-taken paths. It also states the lifecycle constraint (cannot be edited after creation, only terminated), which tells the agent when this tool is the right one versus a later update path.

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