product_experiment_design

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

Annotations already carry the safety profile (destructiveHint=true, idempotentHint=false, readOnlyHint=false), so the bar for additional disclosure is lower. The description adds useful context beyond annotations: the action routes through a domain-agent dispatcher under JWT, tenant, and company scope, which signals auth context and indirection. It does not contradict the annotations, though it says nothing about what side effects may occur (e.g., creating or modifying experiments), which would matter given the destructive hint.

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 compact — a one-line action statement, a routing context sentence, and a two-item Args block — with no filler or redundant prose. The key invocation line is front-loaded. It could be tightened slightly since the Args block partly duplicates schema property names, but overall every sentence earns its place.

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 description covers the invocation essentials: what action to run, how it routes, and what the two parameters mean at a high level. Given an output schema exists, return-value documentation is not required here. However, it lacks the conceptual meaning of experiment_design, any expected structure for the inputs JSON, and any caution about consequences consistent with destructiveHint=true — gaps that matter for an agent dispatching to an autonomous domain agent.

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%, so the description must carry the parameter documentation burden. It does provide basic semantics — 'message: Free-text objective for the action' and 'inputs: Optional JSON string of structured inputs' — which adds meaning beyond the bare schema titles. However, the explanation is thin: there is no indication of what keys or structure the inputs JSON should contain, which is the primary ambiguity an agent faces when calling this tool.

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 description states a specific verb and resource ('Run the product domain agent action experiment_design'), so it is not a pure tautology, and it scopes the action to the product domain. However, it never explains what experiment design actually accomplishes — 'experiment_design' is opaque and effectively restates the tool name. It also fails to distinguish itself from the sibling product_experimentation, which appears to cover the same conceptual territory.

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?

No guidance is given about when to use this tool versus alternatives such as product_experimentation, product_analysis, dispatch_domain_agent, or invoke_tool. The routing note ('Routes through the platform's domain-agent dispatcher') describes mechanism, not selection criteria. There are no when-to-use, when-not-to-use, or prerequisite instructions.

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