Replace a call summary

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

Even though annotations already declare destructiveHint=true and idempotentHint=false, the description adds substantial context: required scopes (call_events:write, luca:queue_ops), data sensitivity full_content, the Idempotency-Key requirement for safe retries, and the hard precondition that confirm: true is mandatory or the call is rejected. This goes well beyond the annotations.

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 is front-loaded, then structured metadata (operation, scopes, idempotency, confirmation, workspace). Each line carries a requirement, though the destructive/confirm lines partly duplicate the annotations and the confirm schema description.

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?

An output schema exists so return values need not be explained, and the description covers auth, idempotency, confirmation, and workspace scoping. It does not clarify what happens to a prior generated summary downstream beyond the CRM note, leaving a minor gap for a destructive mutation.

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 67%, and the description mostly restates what the schema already documents for confirm, idempotencyKey, workspaceId, and workspaceSlug. It adds the practical framing of idempotency as 'safe retries' but gives no syntax guidance for the undocumented id/body parameters.

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 uses a specific verb+resource ('Replace the generated summary') and clarifies the effect ('push it', updates the same CRM note), so the agent can distinguish the action from luca_call_events_summary_generate. It stops short of explicitly naming that sibling as the alternative, so it is clear but not fully differentiated.

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 implies when to use it (to substitute the generated summary with the coach's wording) and notes the workspace-override path, but gives no explicit when-not or direct comparison to siblings like luca_call_events_summary_generate or luca_call_events_push_to_crm. Usage is inferable rather than stated.

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