create_experiment

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

With no annotations, the description carries the full burden, and it does disclose that the tool creates a persistent definition, that it is 'bounded', and that it enables provenance tracking across runs and results. It omits key behavioral details for a mutation: permission requirements, whether titles must be unique, whether the experiment can be deleted or amended, and what 'bounded' actually constrains.

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?

Three short sentences, front-loaded with the core verb and resource, with no filler. The second sentence usefully explains the downstream tracking relationship, though the design advice could have been folded in more tightly.

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?

An output schema exists, so return values needn't be explained, and the purpose is clear. However, for a 5-parameter mutation tool with zero schema descriptions and no annotations, the definition leaves the caller guessing on parameter intent and on what happens after creation or how failures (duplicate titles, invalid bounds) surface.

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% across 5 parameters, so the description must compensate, and it only partially does. It adds qualitative meaning to 'parameters' and 'control_design' ('minimal and deterministic') but says nothing about title, hypothesis, or method beyond their obvious names.

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 ('Define a bounded scientific experiment', 'Creates an experiment definition') and positions it in a lifecycle with runs, results, and controls. It doesn't explicitly contrast with siblings like run_experiment or complete_experiment, so differentiation is inferable rather than stated.

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?

Usage is only implied: the phrase 'can be tracked with runs, results, and controls' hints this is the first lifecycle step before run_experiment, but no explicit when-to-use or when-not-to-use guidance or alternative is named. The only direct guidance ('Parameters and control design should be minimal and deterministic') concerns content quality, not tool selection.

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