Update alert delivery settings

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

Beyond the annotations, the description discloses the required OAuth scope (insights:write / luca:draft), the data sensitivity level (redacted), and the Idempotency-Key requirement plus fallback behavior when the key is omitted — none of which the annotations carry. It does not explain why destructiveHint=true for a merge-patch or what the resulting state looks like, which keeps it short of a 5.

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?

Merge-patch semantics are front-loaded in the first sentence, and the operational metadata is compact and grouped. The idempotency requirement is stated twice ('Requires Idempotency-Key' then 'Provide idempotencyKey for safe retries'), which is a minor redundancy but not bloat.

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?

For a settings mutation, the definition covers the operations-critical facts: patch semantics, auth scope, idempotency, and workspace override, and an output schema exists so return values need no explanation. The remaining gap is that an agent wanting to set specific thresholds has no guidance on units or ranges beyond the numeric bounds encoded in the schema itself.

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 adds real meaning for idempotencyKey (safe retries, server generates one if omitted) and workspaceId/workspaceSlug (override the environment default), which the schema only partially covers at 75%. But the required `body` object — toggles, thresholds, feedEnabled, pushEnabled, digestEnabled — is entirely undocumented in both schema and description, so the main payload must be inferred from field names.

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?

Opens with a specific verb+resource pair: 'Merge-patch the coach's alert-delivery settings', which is far more precise than 'update settings' because it names the patch semantics. It does not explicitly name luca_insights_settings_get as the read counterpart, so sibling differentiation is left to the name pattern rather than stated.

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?

'Send only what you are changing; anything left out keeps its current value' implies the partial-update use case and rules out full replacement, which is useful guidance. However, there is no explicit statement of when to use this versus luca_insights_settings_get, nor any precondition beyond the scope note.

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