Deposit keeps a freelancer’s approved deposit and later payment dates, and what an assistant may tell the client, then lets an assistant read that record before it answers. A 14-day trial, then Pro. The price is only at checkout.
Scored across 12 tools
Each tool has a documented role, but every direct mutation (waive_deposit, mark_deposit_paid, move_payment_date, add_later_payment) has a near-identical dual path through suggest_schedule_change(kind=...) plus accept_schedule_change, which can make an agent uncertain which to call before it knows the approval state. The descriptions do resolve this by explicitly stating when each path is refused, so confusion is limited.
All twelve tools use snake_case with a leading action verb (start_schedule, read_schedule, commit_schedule, suggest_schedule_change), forming a predictable verb_noun pattern throughout. No mixed conventions or vague verbs.
Twelve tools sit comfortably in the ideal range and each maps to a distinct step in the deposit-schedule lifecycle (list/read/start/commit, plus the individual mutation and suggestion operations). Nothing feels redundant at the count level.
The surface covers scheduling, approval, deposit recording, waiving, payment-date moves, later payments, and client scripting, with a suggestion/accept mechanism for post-approval edits. Minor gaps exist — there is no way to remove a later payment or delete/abandon a draft schedule.
Apply one suggested schedule change after the freelancer explicitly approves that change. Pass confirmed true only then. This is the path that may waive the deposit, mark it paid, or move a payment date. Calling it is not a substitute for the freelancer's approval.
| Name | Required | Description | Default |
|---|---|---|---|
| changeId | Yes | ||
| confirmed | Yes | ||
| scheduleId | Yes |
| Name | Required | Description |
|---|---|---|
| data | No |
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.
Add one later payment: a label, an amount in whole minor units, and a payment date. After the schedule is approved, a new later payment is refused until accept_schedule_change applies an add_later_payment suggestion.
| Name | Required | Description | Default |
|---|---|---|---|
| dueOn | Yes | ||
| label | Yes | ||
| scheduleId | Yes | ||
| amountMinor | Yes |
| Name | Required | Description |
|---|---|---|
| data | No |
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.
Mark the current draft as the approved schedule. Pass confirmed true only after the freelancer explicitly approves the deposit, the later payment dates, and what the assistant may tell the client.
| Name | Required | Description | Default |
|---|---|---|---|
| confirmed | Yes | ||
| scheduleId | Yes |
| Name | Required | Description |
|---|---|---|
| data | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare non-read-only, destructive, idempotent, and closed-world behavior, so the safety profile is covered. The description adds the valuable approval gate, but does not disclose what happens to the previous approved schedule, whether the commit can be reversed, or what state the draft ends in.
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, purpose front-loaded, followed by the critical precondition. No filler, no repetition of schema or annotation content.
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 carry the mutation/safety profile. Combined with the approval gate, the definition is nearly sufficient, missing only the effect on any previously committed schedule and on the draft 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?
Schema description coverage is 0%, so the description must compensate. It explains the semantics of confirmed well (a deliberate approval gate), but scheduleId is only inferable from its uuid format and name, with no statement that it must be the current draft's id.
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 — marking the current draft as the approved schedule — which is concrete and actionable. It differentiates implicitly from draft-handling siblings like start_schedule and read_schedule, but never names an alternative 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?
It gives a clear precondition for calling the tool: only pass confirmed=true after the freelancer approves the deposit, later payment dates, and client messaging. That is genuine when-to-use context, though it does not name sibling tools or describe the route for changing an already-committed schedule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the signed-in freelancer's deposit schedules. Use a returned id with read_schedule. Do not guess a schedule.
| Name | Required | Description | Default |
|---|---|---|---|
| offset | No |
| Name | Required | Description |
|---|---|---|
| data | No |
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.
Mark the deposit paid. After the schedule is approved, marking it paid is refused until accept_schedule_change applies a mark_deposit_paid suggestion. Do not tell the client the deposit is paid unless the record already says so.
| Name | Required | Description | Default |
|---|---|---|---|
| scheduleId | Yes |
| Name | Required | Description |
|---|---|---|
| data | No |
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.
Move a payment date. target deposit moves the deposit date. target later moves one later payment and requires paymentId. After the schedule is approved, a different date is refused until accept_schedule_change applies a move_payment_date suggestion.
| Name | Required | Description | Default |
|---|---|---|---|
| dueOn | Yes | ||
| target | Yes | ||
| paymentId | No | ||
| scheduleId | Yes |
| Name | Required | Description |
|---|---|---|
| data | No |
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.
Read the schedule before answering. Quote only this record. mayTellClient and clientScript are what the assistant may tell the client. Draft status is not an approved commitment. Proposed changes do not authorize a waiver, a paid deposit, or a new payment date.
| Name | Required | Description | Default |
|---|---|---|---|
| scheduleId | Yes |
| Name | Required | Description |
|---|---|---|
| data | No |
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.
Record the deposit amount in whole minor units and the deposit date as YYYY-MM-DD. This does not waive the deposit and does not mark it paid. After the schedule is approved, a different amount or date is refused until an accepted schedule change.
| Name | Required | Description | Default |
|---|---|---|---|
| dueOn | Yes | ||
| scheduleId | Yes | ||
| amountMinor | Yes |
| Name | Required | Description |
|---|---|---|
| data | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=false, so the description earns credit for adding a real state guard: after approval, a different amount or date is refused until an accepted schedule change. It does not explain what the destructive hint actually destroys, nor any auth requirement, so it is not exhaustive.
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 tight sentences with the core action front-loaded and the constraints following. The 'YYYY-MM-DD' restatement duplicates the schema pattern, a minor redundancy, but nothing else is wasted.
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 semantics plus approval-state guard are covered. The gap is scheduleId's meaning and any indication of the error shape when a call is refused.
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 burden; it clarifies 'whole minor units' for amountMinor and the date format for dueOn, which adds semantic value beyond the pattern. However, scheduleId — a required UUID — is never described, leaving a third of the parameters 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?
States a specific verb (record) and resource (deposit amount and date), and implicitly separates itself from siblings by negating the jobs of waive_deposit and mark_deposit_paid. It never names those siblings, so an agent must infer the routing rather than read it.
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 two exclusions ('does not waive the deposit and does not mark it paid') effectively tell the agent when NOT to use this tool, and the approval-state constraint tells it when a call will be refused. No alternative tool is named explicitly, 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.
Start a draft deposit schedule for one client project. Draft figures are not an approved commitment until commit_schedule. Currency is a three-letter code. Amounts later are minor units of that currency and are the freelancer's figures.
| Name | Required | Description | Default |
|---|---|---|---|
| currency | Yes | ||
| reference | Yes | ||
| clientName | Yes | ||
| projectTitle | Yes |
| Name | Required | Description |
|---|---|---|
| data | No |
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.
Record a suggested change. This does not change the schedule. kind waive_deposit and kind mark_deposit_paid need only a summary. kind move_payment_date requires dueOn and target; target later also requires paymentId. kind revise_deposit requires amountMinor. kind add_later_payment requires label, amountMinor, and dueOn. kind revise_client_script requires script.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | ||
| dueOn | No | ||
| label | No | ||
| script | No | ||
| target | No | ||
| summary | Yes | ||
| paymentId | No | ||
| scheduleId | Yes | ||
| amountMinor | No |
| Name | Required | Description |
|---|---|---|
| data | No |
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.
Waive the deposit. After the schedule is approved, waiving is refused until accept_schedule_change applies a waive_deposit suggestion. Do not tell the client the deposit is waived unless the record already says so.
| Name | Required | Description | Default |
|---|---|---|---|
| scheduleId | Yes |
| Name | Required | Description |
|---|---|---|
| data | No |
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.
Record what the assistant may tell the client about the deposit and payment dates. After the schedule is approved, different wording is refused until an accepted revise_client_script suggestion. The assistant must not go beyond this script and the facts in read_schedule.
| Name | Required | Description | Default |
|---|---|---|---|
| script | Yes | ||
| scheduleId | Yes |
| Name | Required | Description |
|---|---|---|
| data | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only give a generic safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false, openWorldHint=false); the description adds the non-obvious lifecycle semantics that the script becomes frozen after schedule approval and that the assistant is constrained to this script plus read_schedule facts. That is real behavioral context beyond the annotations. It does not explain why the operation is flagged destructive or how repeated writes behave, so it is not a full 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?
Three sentences, no filler, and the core action leads. The second sentence packs a locking rule plus a forward reference into one dense clause, which is slightly harder to parse than it needs to be, but nothing is wasted.
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 description supplies the freeze-after-approval rule and the assistant-scope constraint that the annotations cannot express. The remaining gap is what the tool does when called before approval or on an already-approved schedule, which is central to a tool whose siblings include commit_schedule.
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 burden, and it only partially does: 'script' is glossed as what the assistant may tell the client, but the 2000-character limit and the scheduleId (uuid) parameter are never explained. The partial gloss compensates somewhat but leaves the identifier parameter undocumented in both places.
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 concrete verb and object: record the script governing what the assistant may tell the client about deposit and payment dates. That is specific enough to separate it from read_schedule and the schedule-mutation siblings. It loses a point because it points at 'revise_client_script', which is not in the sibling set (the closest siblings are suggest_schedule_change / accept_schedule_change), so the cross-reference is ambiguous.
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 communicates an important boundary condition — after the schedule is approved, different wording is refused until an accepted revise_client_script suggestion — which tells the agent when writing is effectively blocked. However, it never states positively when to call this tool versus the many schedule-editing siblings, nor what happens if invoked before approval. Usage is implied rather than prescribed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
accept_schedule_changeadd_later_paymentcommit_schedulelist_schedulesmark_deposit_paidmove_payment_dateread_schedulerecord_depositstart_schedulesuggest_schedule_changewaive_depositwrite_client_script
Add one secure layer between your agents and this server.