splithub_push

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

With no annotations, the description carries the full burden and does substantial work: it discloses return contents (kept experiments, dashboard-created experiments written back into the file), the destructive effect of prune, the non-mutating dryRun mode, and the KEY_CONFLICT failure mode with its two resolutions and their differing effects on numbers. It does not mention authentication, permissions, or what happens on partial failure.

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 primary action and return values are front-loaded, and every subsequent sentence conveys a distinct behavioral fact (kept set, prune, dashboard-created experiments, dryRun, KEY_CONFLICT). Some sentences are long and clause-stacked, which slightly reduces scanability, but there is no filler.

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 zero annotations and no output schema, the description supplies what an agent needs: what gets uploaded, what is preserved, what gets removed, how to preview safely, what comes back, and how to recover from the one named error. Missing only auth/permission prerequisites and idempotency behavior.

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?

All four parameters carry meaning from the description: prune, dryRun, replace, and same are each explained in terms of consequence ('numbers stay' vs 'old numbers cleared'). This is especially valuable for dryRun, which has no schema description. Coverage is 75% and the description closes the remaining gap rather than restating 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?

The description opens with a concrete verb and resource: upload splithub.config.ts to SplitHub Cloud, plus the 'cloud mode' qualifier. This is clearly distinct from read-side siblings like splithub_status or splithub_results. It does not explicitly compare itself to close neighbors such as splithub_plan, splithub_ship, or splithub_pull, so an agent must infer the division of labor.

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?

It gives explicit conditions for the optional flags: prune 'only when the user asked for it', dryRun 'only check the config and show what would change'. It also prescribes the escalation path on KEY_CONFLICT (ask the user, then choose replace or same). It never states when to choose this tool over splithub_plan or splithub_ship, which is the main gap.

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