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

Annotations declare destructiveHint=true and idempotentHint=true; the description complements this by explaining the idempotent 'setting the default again removes the change' behavior and that it returns settings after the change. It does not explicitly flag the destructive aspect beyond that, but the idempotency disclosure is genuinely value-adding context 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 in the first clause, followed by parameter grouping and the timezone caution. It's dense and slightly run-on, but every clause carries actionable information without filler.

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, and the description still notes 'Returns the settings after the change.' Combined with rich usage and behavioral notes for an 8-parameter mutation tool, nothing an agent needs to invoke it correctly is missing.

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 75% schema coverage, the schema already documents most params. The description adds meaning: grouping workspaceId/type/delivery 'together', framing digestHour/timeZone as the person's (not the agent's) clock, and clarifying tellPerson activates when no mailbox exists. This meaningfully supplements the two undocumented enum params (type, delivery) which are self-describing.

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+resource ('Change who hears about what by email') and scopes it to notification settings, clearly distinguishing it from the sibling notification_settings_get. An agent can tell this writes settings rather than reading them.

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?

Explicitly documents the 'for: me' vs 'for: person' choice, the requirement to pass workspaceId/type/delivery together, and the constraint to change digestHour/timeZone 'only when the person asks, since your clock is not theirs.' It even explains that re-setting the default removes the change. This is rich when/when-not guidance.

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