Retry a stopped draft

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

Goes well beyond the annotations: it warns that with auto-send enabled the new draft can go out without review, discloses the 3-attempt ceiling, states the required scopes, and explains that confirm: true is mandatory and an Idempotency-Key is required (or auto-generated). That is exactly the operational context annotations cannot carry.

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?

Purpose and preconditions are front-loaded in the first sentence, followed by the operational constraints as short declarative lines. The boilerplate scope/endpoint lines are compact and each sentence carries decision-relevant information.

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?

With annotations, an output schema, and 80% parameter coverage already present, the description fills the remaining gaps: side effects, idempotency, confirmation, and workspace scoping. The only missing piece is an explicit routing rule against luca_review_queue_regenerate and luca_review_queue_drafting.

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 coverage is 80%, so the baseline is 3, but the description adds meaning on top: it clarifies that turnId refers to the lead's latest turn in a conversation, restates the confirm gate, and explains that workspaceId/workspaceSlug override the environment-configured default workspace. Only turnId's format is left to 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?

States a specific verb and resource ("Have Luca draft again") plus the exact preconditions (cancelled, paused, or failed turn), which lets an agent recognize the recovery scenario. It does not distinguish itself from the near-identical sibling luca_review_queue_regenerate, which it only alludes to via the shared 3-attempt cap.

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 concrete when-to-use conditions (a turn that is cancelled, paused, or failed) and an explicit scope constraint (only the lead's latest turn restarts, max 3 times across retry and regenerate). It stops short of saying when to choose regenerate over retry, which is the most likely sibling confusion.

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