watch_reply_batch

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

The description directly contradicts the annotations: it calls the batch 'idempotent' and instructs reusing request_id for retries, while idempotentHint is false. It does add useful behavioral context about Herald deriving fields and checking delivery_state, but the contradiction is fatal per the rubric.

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 five sentences with the core purpose front-loaded. It contains no filler, and each sentence adds operational or usage value. It could be better structured with separators, but it is appropriately sized.

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?

This is a complex tool with 8 parameters, no output schema, and contradictory idempotency annotations. The description provides important warnings and derivation context, but it does not explain how to construct parts, what the response looks like, or what most parameters mean. An agent would struggle to invoke it correctly.

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?

With 0% schema description coverage, the description must compensate. It gives meaningful semantics for request_id and delivery_id, and mentions parts generally, but leaves duty_id, subject, contents, template, and reply_part unexplained. This is insufficient for an 8-parameter 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: 'Reply to a claimed Watch delivery with a named, idempotent batch.' It also distinguishes the tool from simpler siblings by listing its intended use cases: clean client copy plus separate provenance reply, multiple text parts, files, or albums.

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 gives clear when-to-use guidance ('Use this for clean client copy plus a separate provenance reply, multiple text parts, files or albums') and a strong when-not-to-do instruction ('never create another id to retry an unconfirmed delivery'). It does not explicitly name alternative tools, but the usage context is clear.

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