mureo_batch_begin

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

With no annotations, the description carries the full burden and does well. It discloses side effects (every action_log entry tagged with batch_id), statefulness (refused if a batch is already open), and the rollback relationship. It also mentions cross-platform scope (native, hosted connector, bridged/plugin) and the batch lifecycle, providing rich behavioral context beyond the schema.

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 four sentences, each earning its place: purpose, tagging behavior, usage timing with examples, and a refusal condition. It is front-loaded with the primary function and contains no fluff 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?

Given no output schema, the description explains the key output concept (returned batch_id) and its downstream use with rollback_plan_get. It covers lifecycle, constraints, and platform scope. However, it does not describe the exact return format or any error conditions beyond the open-batch refusal, leaving a minor gap in completeness.

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 100%, so baseline is 3. The description itself does not add significant meaning beyond the schema for the parameters. It references the returned batch_id but does not elaborate on parameter usage or format, so it neither compensates nor adds extra value.

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 clearly states the tool's purpose: 'Declare the start of a bulk change so it can be reviewed and reversed as ONE unit.' It uses a specific verb ('Declare the start') and resource ('bulk change'), and distinguishes itself from siblings like mureo_batch_end and mureo_batch_status by mentioning batch_id and rollback integration.

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?

The description explicitly says when to use it: 'Call this BEFORE a multi-entity pass' with examples. It also points to a follow-up alternative: 'afterwards, rollback_plan_get with that batch_id reports what can and cannot be reversed.' However, it does not explicitly state when not to use it beyond the runtime refusal if a batch is already open.

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