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

Annotations already declare readOnlyHint=false and idempotentHint=false, so the mutation profile is partly covered. The description adds behavior annotations cannot express: post-approval wording is rejected outright, changes then require an accepted revise_client_script suggestion, and the assistant is constrained to this script plus read_schedule facts. It stops short of saying what happens to a prior script when written again or what an accepted/rejected write returns.

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 sentences, no filler, with the core purpose front-loaded and the constraint/refusal rule following. The final sentence about not exceeding the script is a useful guardrail rather than padding, though the middle sentence packs two rules into one line.

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 no explanation, and annotations cover the safety profile. The description supplies the governance rules an agent needs (approval gating, revise_client_script escalation, scoping to read_schedule facts). Only the overwrite/repeat-write semantics and scheduleId expectations are left implicit.

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 parameter burden. It explains conceptually that the 'script' is the client-facing wording, but adds nothing about the 2000-character limit, the free-text nature, or what scheduleId must reference (only implied by sibling read_schedule). Partial compensation justifies a middle score.

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 and resource: recording what the assistant is allowed to tell the client about deposit and payment dates, and names the sibling it relates to (revise_client_script for post-approval changes and read_schedule as the factual source). The resource being written ('a client-facing script') is somewhat abstract, but the intent is decidable and distinct from siblings like suggest_schedule_change or add_later_payment.

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?

Gives the operative condition: wording different from this script is refused after the schedule is approved until an accepted revise_client_script suggestion, which tells the agent when it may still write directly versus when it must route through a suggestion flow. It does not state the full prerequisite set (e.g. whether a schedule must exist first), but the gating rule is concrete and actionable.

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