Deposit

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

Annotations declare destructiveHint=true and idempotentHint=true, but the description goes further by naming the concrete side effects: it 'may waive the deposit, mark it paid, or move a payment date.' That tells the agent exactly which downstream state (matching waive_deposit, mark_deposit_paid, move_payment_date) can be touched, which annotations alone cannot convey.

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 the action and precondition, then the consequences, then the caution. No sentence is redundant and nothing is buried.

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?

With an output schema present and rich annotations, the description only needs to cover intent, gating, and side effects, all of which it does. The residual gap is that the two identifier parameters are never explained, but the approval gate and destructive consequences an agent needs are fully covered.

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 all param meaning, yet it only explains 'confirmed' ('Pass confirmed true only then'). scheduleId and changeId are left to their UUID format hint alone, leaving two of three parameters materially undocumented.

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 ('Apply') on a specific resource ('one suggested schedule change') and immediately implies the pairing with suggest_schedule_change by scoping to already-suggested changes. An agent can distinguish this mutation from the sibling that proposes changes without opening either schema.

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 an explicit precondition ('after the freelancer explicitly approves that change') and an exclusion ('Calling it is not a substitute for the freelancer's approval'), so the gating condition is unambiguous. It does not name suggest_schedule_change or the read/list siblings as alternatives, which keeps it short of a 5.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: a hard state gate tied to schedule approval and the exact mechanism (accept_schedule_change applying an add_later_payment suggestion) that lifts it. It stops short of explaining what the mutation affects elsewhere in the schedule, which is where destructiveHint matters.

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?

Two sentences, no filler. The payload definition comes first and the state constraint second, so the operation is front-loaded before the edge case.

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 the mutation's main non-obvious behavior (the post-approval refusal) is disclosed. What is missing is the scope of 'later payment' relative to the existing schedule (e.g., whether it affects recomputation or prior payments), which would explain the destructive hint.

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 load, and it partially does: it clarifies that the amount is in whole minor units, which the bare 'amountMinor' integer does not. However 'payment date' is not tied to the dueOn field name or its YYYY-MM-DD pattern, and scheduleId is never mentioned, leaving ambiguity for an agent that must supply all four required 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 names a specific verb and resource ('Add one later payment') and enumerates the three payload pieces (label, amount, payment date), which map directly to required fields. It also distinguishes itself from add-type workflow siblings by naming accept_schedule_change as the path that must precede further additions.

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 gives a concrete usage condition: once the schedule is approved, direct additions are refused and accept_schedule_change (applying an add_later_payment suggestion) is the alternative. It doesn't say when to prefer this over suggest_schedule_change or move_payment_date, but the precondition and the named fallback are explicit.

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

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

Annotations declare the write/idempotent/non-destructive profile, and the description adds real behavioral context beyond that: the operation promotes a draft to approved and is gated on explicit human approval of specific terms. It does not describe what happens if the draft is already committed or missing.

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?

Two sentences, no filler, with the core action stated first and the gating condition immediately after. Every clause earns its place.

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 described, and annotations cover the safety profile. The description supplies the state-change and approval-gating context needed for correct invocation; only edge-case behavior (no draft, already committed) is unaddressed.

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 coverage is 0%, so the description must carry the load. It meaningfully explains the 'confirmed' parameter's required semantics (only true after explicit approval of deposit, payment dates, and client messaging); scheduleId is left unexplained but is self-evident as a UUID identifier.

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: 'Mark the current draft as the approved schedule.' An agent can tell this is a state transition that finalizes a schedule, though it never explicitly names how it differs from siblings like accept_schedule_change or start_schedule.

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?

Provides an explicit precondition for use: pass confirmed true only after the freelancer approves the deposit, later payment dates, and client messaging. It gives clear context but does not name alternative tools or state when this should not be called (e.g., already-committed schedules).

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed world, so the safety profile is covered. The description adds the useful constraint that ids must come from this call rather than be guessed, but says nothing about pagination despite the offset parameter, so it adds only modest 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?

Three short sentences, front-loaded with the purpose, then the follow-up action, then the warning. Nothing is redundant.

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?

With an output schema present, return values need no explanation, and annotations cover the safety profile. The remaining gap is pagination behavior for the offset parameter, which an agent would need for large result sets.

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% and the sole parameter (offset) is never mentioned in the description. The schema supplies bounds and a default but no meaning, and the description does not compensate by explaining pagination or how results are windowed.

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 (List) and a scoped resource (the signed-in freelancer's deposit schedules), and explicitly names the sibling read_schedule as the follow-up consumer of the returned ids. An agent can distinguish it from read_schedule without opening either schema.

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 clear workflow context: use a returned id with read_schedule, and 'Do not guess a schedule' warns against fabricating ids. It lacks an explicit when-not or an alternative for cases where the schedule is already known, so it stops short of full routing guidance.

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

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

The description adds substantial behavioral context beyond the annotations: it discloses a workflow refusal condition tied to schedule approval and accept_schedule_change, and it warns not to tell the client the deposit is paid unless the record already says so. These are meaningful operational and communication constraints that an agent would not infer from the structured fields alone.

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?

The description is three tight sentences: the action first, then the precondition, then the client-communication warning. Every sentence adds useful information with no 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?

Given the output schema exists and annotations already cover safety traits, the description covers the key workflow behavior well. However, it leaves the sole input parameter effectively undocumented, which is a notable gap for correct invocation.

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 schema has 0% description coverage for its only parameter, scheduleId, and the description does not explain the parameter's meaning, format, or source. It only indirectly references 'the schedule,' adding minimal meaning beyond the schema's field name and type.

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 states a specific verb and resource ('Mark the deposit paid') and names a related sibling tool with a workflow precondition. It does not fully differentiate the action from other deposit-related siblings such as record_deposit or waive_deposit, but the core purpose is clear.

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 gives clear conditional usage context: after schedule approval, the operation is refused until accept_schedule_change applies a mark_deposit_paid suggestion. That effectively names a when-not condition and a related alternative, though it does not state the positive case as explicitly as a 5 would require.

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

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

Annotations already declare destructive=true, idempotent=false, readOnly=false. The description adds non-obvious behavioral context beyond them: the post-approval refusal rule and the routing through accept_schedule_change, plus the paymentId requirement for 'later'. It does not describe reversibility or permissions, but adds real value on top of 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?

Three short sentences with the core action front-loaded, then target semantics, then the approval caveat. No filler, though the phrasing 'target deposit moves the deposit date' is slightly circular.

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 carry the safety profile. The description covers the key quirk (post-approval refusal) and the two operating modes, leaving only minor gaps around dueOn semantics and how suggestions relate to direct moves.

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 parameter meaning. It explains target's two enum values and that 'later' requires paymentId, covering two of four params, but says nothing about dueOn (a YYYY-MM-DD date) or scheduleId beyond their self-evident names/formats.

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 ('Move a payment date') and unpacks the two target modes, so an agent understands exactly what the tool mutates. It references accept_schedule_change but never explicitly contrasts itself with the sibling suggest_schedule_change, which is the closest neighbor, so sibling differentiation is only partial.

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 concrete conditions: 'target deposit' vs 'target later' (which requires paymentId), and states that after approval a different date is refused until accept_schedule_change applies a suggestion. That names an alternative and the trigger for it, but there is no explicit 'use this instead of X when...' framing.

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

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior. The description adds meaningful business semantics beyond annotations, clarifying mayTellClient/clientScript and warning that draft status and proposed changes are not commitments or authorizations.

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?

The purpose is front-loaded, and the following sentences add specific business rules without obvious repetition. Some phrasing is clipped and could be organized more cleanly, but it is appropriately sized for the tool.

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 and rich annotations reduce what the description must cover, and it supplies important semantic constraints. However, for a tool whose only input parameter is undocumented at the schema level, the description leaves scheduleId's meaning and format unexplained.

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 schema has one required parameter with 0% description coverage, and the description never mentions scheduleId, UUID format, or how to identify the schedule. It therefore fails to compensate for the missing schema documentation.

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 clear verb and resource with 'Read the schedule,' and the singular reference plus required scheduleId implies retrieving one schedule rather than listing. It does not explicitly distinguish this from list_schedules or name any sibling tool, so it misses the top tier.

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 clear usage context: read the schedule before answering, quote only this record, and treat draft/proposed changes as non-authorizing. It does not name alternative tools or explicitly say when not to use this tool.

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

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

Annotations already declare this a non-read-only, non-destructive, non-idempotent mutation. The description adds real behavioral context beyond that: the operation does not alter waiver or paid state, and after approval the amount/date is locked until an accepted schedule change. It stops short of describing permissions or the response payload, which the output schema covers.

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, front-loaded with the action and both input formats, followed by the exclusion and immutability constraints. No filler; every clause conveys a distinct rule.

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 mutation tool with an output schema and safety annotations already supplied, the description covers scope, formats, and the post-approval immutability rule. The only real gap is the un-explained scheduleId parameter, which is minor given its UUID format.

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 load, and it does for two of three parameters: it clarifies that the integer amount is in whole minor units and that the date must be YYYY-MM-DD. scheduleId is left unexplained, though its UUID format makes its role fairly evident.

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 ('Record the deposit amount ... and the deposit date') and then explicitly distinguishes itself from the sibling deposit tools by declaring 'This does not waive the deposit and does not mark it paid.' An agent can separate it from waive_deposit and mark_deposit_paid without opening either schema.

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 clear negative guidance ('does not waive', 'does not mark it paid') and a precondition ('After the schedule is approved, a different amount or date is refused until an accepted schedule change'). It does not name the alternative tools by name for those excluded operations, but the context for use is unambiguous.

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

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

Annotations already declare readOnly=false, destructive=false, idempotent=false and openWorld=false, so the safety profile is covered. The description adds genuinely non-structured context: the result is a *draft* that is not an approved commitment until commit_schedule, which is the two-phase lifecycle an agent cannot infer from annotations. It omits auth/permission requirements, keeping it from 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?

Four short sentences with the core action front-loaded and no filler. The phrase 'Amounts later are minor units of that currency' is slightly awkward and refers to later tools rather than this call's parameters, but overall it is tight.

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 described. For a non-idempotent draft-creating tool the description supplies the essential lifecycle context (draft vs committed) and the currency/unit conventions. Nothing critical for a correct invocation appears 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?

Schema description coverage is 0%, so the description carries the full burden for four required parameters. It clarifies currency (three-letter code) and the minor-unit/freelancer-ownership convention for amounts, but says nothing about clientName, projectTitle, or the ambiguous 'reference' field, leaving half the semantics unexplained. Partial compensation warrants a mid 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 ('Start a draft deposit schedule') with an explicit scope ('one client project'), and names the sibling commit_schedule to mark the boundary between draft and committed. An agent can distinguish this from commit_schedule or record_deposit without opening a schema.

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 frames this as the draft-creation step and points to commit_schedule as the action that turns figures into an approved commitment, giving clear sequencing context. It does not spell out when not to use it (e.g. when a schedule already exists) or other prerequisites, so it falls short of a 5.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, and the description adds the key behavioral fact that this records a proposal and does not alter the schedule. It does not mention downstream review/notifications or the non-idempotent consequence of duplicate submissions, but the central non-effect is well disclosed.

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?

Front-loaded with the most important constraint ('does not change the schedule') and then delivers a dense, non-redundant per-kind requirements list. The run-on 'kind X requires ...' chain is efficient though it would read better as a list; no sentence is 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?

For a 9-parameter tool with output schema present (return values need not be explained), the description supplies the conditional field requirements an agent needs to construct a valid call. The remaining gap is workflow context — what happens after a suggestion is recorded and how it gets accepted — which limits it slightly.

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% across 9 parameters, so the description carries the burden and largely does: it maps each of the six kind enum values to its required companion fields (dueOn, target, paymentId, amountMinor, label, script). It omits guidance on scheduleId, the summary field's purpose, and the meaning of target=deposit vs later beyond the paymentId rule.

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 ('Record a suggested change') and immediately clarifies the scope with 'This does not change the schedule,' which cleanly separates it from the applying tool. It stops short of naming accept_schedule_change, the natural alternative a caller would otherwise confuse it with.

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 per-kind requirement breakdown effectively tells the caller which inputs select which behavior, but there is no explicit when-to-use guidance relative to accept_schedule_change or commit_schedule. The suggestion-only nature is implied rather than routed ('use accept_schedule_change to apply it').

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

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

Annotations already declare destructive=true and idempotent=true, so the safety profile is covered. The description adds genuinely new behavior beyond them: a post-approval refusal condition and a client-communication guard ('Do not tell the client the deposit is waived unless the record already says so'), which prevents a real error.

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, front-loaded sentences that each carry distinct information. The middle sentence is slightly dense, but no sentence is filler and the imperative action leads.

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. The description covers the mutation's workflow position, a refusal condition, and a client-communication rule; it could say more about permissions or the effect on existing deposit records, but it is serviceable for a single-parameter 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 coverage is 0% and the description never mentions scheduleId, so it does not compensate for the undocumented parameter. With only one obvious required UUID param and an existing output schema, this is a modest gap rather than a critical one, warranting the 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+resource ('Waive the deposit'), and the second sentence ties it into the workflow with accept_schedule_change. It is clearly distinguishable from siblings like record_deposit or mark_deposit_paid, though it does not explicitly contrast the core action against 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?

Provides a concrete precondition and failure mode: waiving is refused after the schedule is approved until accept_schedule_change applies a waive_deposit suggestion. That tells the agent when the call will succeed, but it does not discuss alternatives (e.g., suggest_schedule_change) beyond the referenced workflow tool.

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

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.