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

Annotations already flag destructiveHint=true and idempotentHint=true, so the bar is lower, but the description adds concrete meaning to destruction ('archiving is final') and to idempotency ('repeating the call with the same input leaves the same result'). It does not disclose whether the body is a partial patch or a full replacement — critical for a mutation with all-optional body fields — which is the main remaining gap.

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?

Three short sentences, front-loaded with what can be changed and then the status semantics. The idempotency sentence largely restates an existing annotation, so it earns its place less than the others, but nothing is verbose.

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 destructive mutation with a deeply nested, validation-heavy schema and 0% parameter documentation, the description covers the status semantics well but omits partial-update behavior, the target identifier, and any confirmation that only supplied fields change. With no output schema, return values need not be explained, so the remaining gaps are moderate rather than severe.

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 0%, so the description must carry the burden, and it only names fields loosely ('title, instruction, timing or Slack delivery') without mapping them to schema keys or explaining the nested timing object (cadence, weekday, local_time, timezone, run_on). The required params.id identifier and the deliver_email/deliver_slack booleans are never mentioned, and the semantics of omitting a field is left unexplained.

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?

'Changes a scheduled agent task's title, instruction, timing or Slack delivery, or pauses, resumes or archives it' gives a specific verb plus resource and enumerates the mutable fields and status transitions. An agent can distinguish it from createAgentSchedule or listAgentSchedules from the verb alone, though no sibling is named explicitly.

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?

The description implies when to pick each status by contrasting 'Archiving is final' with 'pausing keeps it for later', which is real guidance for the status choice. It offers no guidance on when to use this tool versus createAgentSchedule, listAgentSchedules, or the separate schedule run tools, and no prerequisites or permission notes.

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