Draft a reply to a lead

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

Goes well beyond the annotations by disclosing required scopes (leads:write, luca:draft), data sensitivity (full_content), the Idempotency-Key requirement with server-generated fallback, and workspace override precedence. This is genuinely useful context for a write operation. The idempotentHint=false annotation plus a required idempotency key is a mild tension but is standard safe-retry semantics, not a contradiction.

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 behavioral purpose is front-loaded in the first sentence, followed by a compact operational block. Every line earns its place, though the endpoint/scopes/idempotency/workspace block is a dense laundry list rather than prose tuned for scanning.

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 an output schema present, return values need not be explained, and the description covers auth, idempotency, and workspace scoping. The main gap is that it never mentions the handoff to the luca_review_queue_* siblings that will actually action the queued draft, nor why this differs from luca_draft_reply.

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?

The description explains 'guidance' semantically (steers tone or content), which the bare schema does not, and covers workspaceId/workspaceSlug/idempotencyKey behavior. The undeclared `id` is only inferable from the POST /api/leads/{id}/draft path, leaving one required parameter's meaning implicit at 60% schema coverage.

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?

Names a specific verb (draft), resource (reply for a lead), and the resulting state (queued for review), so the agent knows this creates a reviewable draft rather than sending anything. It does not, however, distinguish itself from the very similar sibling luca_draft_reply or from luca_conversations_send, which is a real selection risk in this crowded namespace.

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?

"on demand" implies a manual, per-lead trigger as opposed to the campaign/cadence paths, and "queue it for review" implies a human-approval workflow. But there is no explicit when-to-use versus luca_draft_reply, luca_conversations_send, or the review-queue siblings, so the routing guidance is only implicit.

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