splithub_experiment_status

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

With no annotations present, the description carries the full burden and does add real behavioral detail: the config file is updated and validated, and cloud mode propagates changes live within about a minute. It also discloses the important side effect that variants remain in the code after finishing. It does not mention permissions/auth, whether transitions are reversible, or what happens on invalid transitions.

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 action, then behavioral notes, then the downstream instruction. No filler or repetition.

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 two-parameter mutation tool with no annotations and no output schema, the description covers the main behavioral traits an agent needs: config mutation, propagation latency, and the required follow-up tool. The missing piece is disambiguating the experiment identifier and its relationship to the near-identical set_status sibling.

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 should compensate. It implies the status values through the verbs 'start, pause or finish', which loosely map to the enum running/paused/finished, but the mapping is not stated explicitly and the 'experiment' parameter (name vs. key vs. id) is never explained.

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 set (start, pause, finish) and resource (experiment), which is much clearer than a tautology. However, the sibling splithub_set_status sounds like it does the same thing, and the description never distinguishes the two, leaving an agent to guess which tool to call.

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 workflow guidance for the post-finish path: ask the user which variant to keep, then call splithub_ship. That is a genuine routing instruction. It lacks any when-not guidance or comparison to splithub_set_status / splithub_experiment_create.

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