Recurring subscriptions billing: schedule once, auto-generate due invoice PDFs.
Scored across 14 tools
Each tool targets a distinct operation: forecast, invoice generation, license management, and schedule lifecycle (create, read, update, delete, pause, resume, skip, list, history, upcoming). No two tools have overlapping purposes; even schedule_get vs list vs history vs upcoming are clearly separate.
Tools follow a consistent verb_noun pattern: schedule_create, schedule_delete, schedule_get, schedule_pause, license_activate, license_status. Even invoice_generate_due and forecast are clear and follow the same style. There is no mixing of conventions.
14 tools is well-scoped for a subscription management server. Each tool covers a distinct operation needed for the domain, and the count is within the optimal range (3-15) without feeling bloated or thin.
The surface covers the full subscription lifecycle: create, read, update, delete, pause, resume, skip, list, history, upcoming, plus forecasting, invoicing, and license management. There are no obvious dead ends; all operations are covered for both schedules and licensing.
Expected invoiced revenue per calendar month per currency from active schedules. Invoiced and skipped periods are excluded and paused schedules listed apart. Free: 3 months; Pro: up to 120.
| Name | Required | Description | Default |
|---|---|---|---|
| months | No | Months ahead including this one, default 12 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are all false and provide no safety or behavior coverage, so the description carries the burden. It discloses important behaviors: invoiced/skipped periods are excluded, paused schedules are listed apart, and plan-based month limits apply. It does not state what happens if a request exceeds the plan limit, but the disclosed behavior is substantial.
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 compact and front-loaded, with the core meaning stated first and exclusions/plan limits after. Every clause adds useful information and there is no filler or repetition of the schema.
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 one-parameter tool with no output schema and uninformative annotations, the description is mostly complete: it covers the output dimension, scope, exclusions, paused-schedule handling, and plan limits. The main missing piece is explicit behavior when the requested months exceed the free/pro allowance (clamp vs. error), which would make it fully self-sufficient.
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 100%, so the baseline is 3. The description adds meaningful parameter context beyond the schema by tying the 'months' ceiling to plan level ('Free: 3 months; Pro: up to 120'), which the schema does not express. This helps an agent choose a safe value.
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 resource ('expected invoiced revenue') and precise scope: per calendar month, per currency, from active schedules. It also distinguishes the tool from siblings by noting exclusions and special handling of paused schedules, so an agent can tell it apart from schedule_* and invoice_* tools.
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 provides useful context about what is included/excluded and plan-based limits ('Free: 3 months; Pro: up to 120'), but it does not explicitly say when to use this tool versus an alternative or when not to use it. Usage is mostly implied by the tool name and title.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a real invoice in the invoice server for every schedule occurrence on or before as_of that has not been invoiced yet, and render each PDF. Returns what was created, what was skipped and what is still due.
| Name | Required | Description | Default |
|---|---|---|---|
| as_of | No | YYYY-MM-DD, defaults to today. Every occurrence on or before this date that has not been invoiced is billed. Idempotent: one invoice per schedule per period, keyed by the occurrence date, so running it twice creates nothing the second time | |
| dry_run | No | List what would be created without creating anything. Default false. One run creates at most 60 invoices, oldest period first | |
| schedule_id | No | Only this schedule. Free and unlimited on every tier |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations are all false hints and therefore carry no real behavioral signal. The description compensates fully: it discloses write side effects, PDF rendering, idempotency keyed by occurrence date, the 60-invoice run cap, and the created/skipped/still-due return categories.
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 main description is one dense sentence that front-loads the core effect, then states the output categories. Each parameter description earns its place with distinct operational facts; there is no filler or redundancy.
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?
Even without an output schema, the definition tells the agent what side effects to expect, how to preview with dry_run, how many invoices can be created per run, how idempotency works, and what the response reports. That is sufficient to select and invoke it correctly.
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 100%, so the baseline is 3, but the parameter text adds more than a bare schema: as_of includes the dedup key and idempotency, dry_run adds the 60-invoice cap and oldest-period-first ordering, and schedule_id notes free/unlimited scoping.
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 precise verb and resource: create real invoices for uninvoiced schedule occurrences on or before as_of and render PDFs. The return summary (created/skipped/still due) makes the scope concrete and separates it from read-only schedule tools like schedule_upcoming and forecast.
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 trigger condition is explicit ('occurrences on or before as_of that have not been invoiced yet'), and dry_run plus schedule_id provide clear scoped/test usage. It does not name an alternative or state a when-not-to-use case, but no sibling tool performs invoice generation, so that omission is minor.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Turn Pro on for this connection with key, an MCPL1.. issued at checkout for this server or the bundle. Data under your token stays; a wrong or expired key changes nothing. license_status confirms it.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | License key from checkout, MCPL1.<payload>.<signature> |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is not read-only and not destructive, and the description adds useful behavioral detail: existing data under the token stays, and a wrong or expired key changes nothing. This goes beyond the annotation hints by explaining failure semantics and safety of the operation.
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 two sentences with no filler. It front-loads the core action, then gives the key format and safety guarantees, and closes with the verification tool. Every sentence contributes essential information.
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 single-parameter activation tool with annotations covering the safety profile, the description is complete: it states what the tool does, what input is needed, what happens on failure, and how to confirm success. There is no missing critical information for an agent to call it correctly.
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 already documents the key parameter and its format with 100% coverage. The description adds meaning by specifying that the key must be issued at checkout for this server or the bundle, which clarifies validity requirements not present in the schema.
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 uses a specific verb and resource: it 'turns Pro on' for the connection using a license key. It also distinguishes itself from the sibling license_status tool by saying license_status confirms the activation. This leaves no ambiguity about what the tool accomplishes.
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 provides clear context for use: the key must be an MCPL1.<payload>.<signature> issued at checkout for this server or the bundle. It does not explicitly list exclusions or alternative tools, but it does reference license_status as the confirmation path, giving the agent a sense of the workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report this endpoint's licence state for your token as JSON: the product, the tier free or pro, why it is not Pro, and the checkout URL. Call it to explain a free-tier refusal. No arguments, nothing changes.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds useful context beyond annotations by specifying the JSON response contents and stating 'nothing changes,' reinforcing the read-only nature of the call.
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 dense sentences cover output, purpose, usage context, and side-effect guarantee. Every sentence earns its place and the most important information is front-loaded.
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 no output schema, the description sufficiently describes the return value. With no parameters, annotations covering safety, and a clear use case, nothing essential is missing for an agent to invoke this tool correctly.
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?
There are zero parameters and the schema already fully documents that fact. The description explicitly says 'No arguments,' which is accurate and reinforces the schema without needing further elaboration.
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 begins with a specific verb ('Report') and a precise resource ('this endpoint's licence state for your token'), and enumerates the exact output fields: product, tier, reason, and checkout URL. This clearly distinguishes it from sibling tools like license_activate.
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 explicitly states when to call it: 'Call it to explain a free-tier refusal.' This is clear contextual guidance, though it does not name alternatives or explicitly state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Define a repeating invoice: a client, the line items, how often to bill, and when it starts and ends. Returns the schedule id, a summary and its next dates. Nothing is invoiced until invoice_generate_due runs.
| Name | Required | Description | Default |
|---|---|---|---|
| every | Yes | How often to bill: "weekly", "monthly", "quarterly", "yearly", or {days: 10}. Month steps keep the start date's day of month and clamp it to shorter months, so a schedule starting on the 31st bills on the 28th/29th in February and back on the 31st in March | |
| items | Yes | The line items billed every period | |
| notes | No | Free text printed under the totals of every generated invoice | |
| client | Yes | Client name or id, as in the invoice server. Unknown names are created on the first generated invoice | |
| currency | No | Defaults to your business default currency | |
| due_days | No | Days until each invoice is due, defaults to your payment terms | |
| end_date | No | YYYY-MM-DD, INCLUSIVE: an occurrence landing exactly on it is still generated | |
| tax_note | No | Why this schedule bills the tax it bills, e.g. 'Reverse charge: VAT accounted for by the recipient, art. 196 Directive 2006/112/EC'. It is printed under the totals of EVERY invoice this schedule generates, so a 0% retainer carries its reason on the document instead of only in the chat | |
| anchor_day | No | Pro: bill on this day of month instead of the start date's day. 31 means the last day of every month | |
| start_date | Yes | YYYY-MM-DD. The first invoice falls on this date, and for weekly/monthly/quarterly/yearly steps its day of month is the billing day for every later period | |
| end_of_month | No | Pro: always bill on the last day of the month | |
| auto_generate | No | Marks the schedule for the monthly_billing_run prompt. Default false. Nothing runs in the background either way: invoices are created only when invoice_generate_due is called |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only state broad hints (all false), so the description carries the disclosure burden. It adds significant behavior beyond structured data: 'Nothing is invoiced until invoice_generate_due runs' and the return values (schedule id, summary, next dates). It doesn't cover permission requirements or immediate activation state, but it addresses the most surprising side-effect boundary.
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 with no filler: the first states the action and scope, the second states the return values, the third states the critical caveat. Every sentence earns its place, and the most important differentiator ('nothing is invoiced until...') is placed at the end for emphasis.
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 create tool with 12 parameters but a fully descriptive schema, the description covers the essential behavioral contract: what is created, what is returned, and when side-effects occur (only via invoice_generate_due). No output schema exists, so the explicit return description is valuable. Nothing an agent needs to know before calling 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?
Schema description coverage is 100%, and the schema itself contains rich parameter explanations (e.g., the 'every' field's day-of-month clamping behavior). The tool description only summarizes parameter categories ('a client, the line items, how often to bill') without adding new meaning, so the baseline of 3 applies.
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 uses a specific verb and resource ('Define a repeating invoice') and enumerates the core components (client, line items, frequency, start/end), making the tool's job unambiguous. It also states the return contract (schedule id, summary, next dates), and implicitly differentiates from siblings like schedule_update and schedule_delete by being the creation tool.
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 provides clear context for when to use this tool: to set up a repeating invoice schedule. It does not explicitly name alternatives or exclusions (e.g., 'use schedule_update to modify'), but the title and sibling set make that distinction clear. The mention of invoice_generate_due as a downstream step rather than an alternative leaves the guidance slightly implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete one schedule permanently. Invoices already generated stay in the invoice server and the history is kept. Re-creating it gives a NEW id, so its old periods count as unbilled. schedule_pause is reversible.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Schedule id, or a client name. Deletion is permanent; re-creating the same schedule afterwards gives it a NEW id, so its old periods count as unbilled again |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true, but the description adds meaningful behavioral context beyond that: invoices already generated remain in the invoice server, history is kept, re-creating the schedule yields a new id, and old periods count as unbilled. It also clarifies that pause is reversible, giving the agent a fuller picture of consequences.
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, all informative and none wasted. The core action and permanence are front-loaded, and the sibling contrast is placed at the end without clutter.
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 one-parameter tool with no output schema, the description covers what happens to generated invoices, history, re-creation behavior, and the reversible alternative. An agent has enough context to invoke it correctly and understand the consequences.
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 100%, and the id parameter is already described as 'Schedule id, or a client name' plus the permanent re-creation consequence. The description does not add extra parameter-level meaning, so the baseline score of 3 is appropriate.
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: 'Delete one schedule permanently.' It also distinguishes itself from the reversible sibling operation by noting 'schedule_pause is reversible,' so an agent can tell delete apart from pause/resume/update without opening schemas.
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 use this tool by emphasizing permanence and contrasting with 'schedule_pause is reversible.' It gives clear context for choosing delete over pause, though it does not explicitly enumerate all alternative tools or state 'use schedule_pause if you need a reversible option.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return one schedule in full by id or client: items, cadence, dates, due days, anchor rules, notes, per-period amount, next due date and how many invoices it generated. schedule_history is the log.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Schedule id, or a client name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description is fully consistent with those. It adds behavioral value by defining what 'in full' means, listing the concrete fields returned, and noting the relationship to schedule_history. It does not mention auth or rate limits, but those are not necessary for a read-only lookup.
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 a single tightly packed sentence that front-loads the action and follows with a concise field list. The second sentence about schedule_history is a useful pointer rather than filler. There is no repetition of the tool name, title, or schema 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?
For a simple one-parameter getter, the description is complete: it states the purpose, the accepted identifier form, the full return contents, and the correct alternative for history data. The annotations cover safety, and the output-schema absence is compensated by the explicit field enumeration. 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?
The schema already describes the only parameter, id, as 'Schedule id, or a client name' with 100% coverage, so the description's 'by id or client' adds no new semantic information. There are no enums or nested objects to clarify. The schema carries the parameter-documentation burden, so the baseline of 3 is appropriate.
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 opens with 'Return one schedule in full by id or client', a specific verb-plus-resource statement that clearly differentiates this tool from list or log siblings. The enumerated payload fields (items, cadence, dates, due days, anchor rules, notes, per-period amount, next due date, invoice count) make its purpose unmistakable. The final clause about schedule_history also helps distinguish it from the history log.
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 gives clear context: use this when you need one full schedule by id or client, not a list or a log. It explicitly points to schedule_history for the log, but it does not spell out when to prefer schedule_list or schedule_upcoming. The by-id/full-record framing implies those boundaries well enough for a simple getter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The audit log for one schedule id, oldest first: period, invoice number, issue and due dates, amount, PDF path, and whether that invoice is unpaid, paid, skipped or since deleted. schedule_list finds the id. Pro.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds useful behavioral context: ordering, contents, invoice statuses including 'since deleted', and a 'Pro' access note. However, the annotations provide no safety hints and readOnlyHint=false sits awkwardly with the read-only-sounding 'audit log', so the agent gets no explicit statement about side effects or error behavior.
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?
A single dense sentence front-loads the core purpose and then efficiently lists the returned fields and statuses. The trailing 'Pro.' is minimal but adds a real access constraint without padding.
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 one-parameter lookup tool with no output schema, the description covers the output fields, ordering, and status semantics. It does not mention pagination or limits, which may matter for an audit log, but the description is otherwise enough for an agent to invoke it correctly.
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 only defines an opaque required string 'id', and description coverage is 0%. The description compensates by explaining that the parameter is a schedule id and directs the agent to schedule_list to discover it. It stops short of giving format examples, but for one parameter this is sufficient.
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 clearly identifies the tool as an audit log for one schedule id, enumerates the exact fields returned, and orders them oldest first. It also names schedule_list as the source of the id, which distinguishes it from sibling schedule tools without needing to inspect their schemas.
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 gives a concrete usage pointer: use schedule_list to find the id. It does not explicitly state when to prefer this over schedule_get or schedule_upcoming, but the audit-log framing and field list make the intended use clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List schedules: id, client, cadence, per-period amount and currency, start and end dates, status, next due date and auto_generate. Filter by status; a paused schedule reports no next due date.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds a behavioral detail beyond annotations: 'a paused schedule reports no next due date.' Since readOnlyHint, idempotentHint, and destructiveHint are already present, the description enhances transparency by explaining a subtle output nuance that annotations do not capture.
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 a single, efficient sentence that front-loads the core action 'List schedules' and packs the field list and filter behavior without redundancy. Every word adds value.
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 simple list operation with one optional filter, the description covers the returned fields and the key behavioral quirk (paused schedules). It omits pagination/ordering details, but given the simplicity and strong annotations, this is a minor gap. The absence of an output schema is mitigated by the explicit field enumeration.
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 compensate. It explains that the status parameter filters results and that the 'paused' status suppresses the next due date, adding meaning beyond the bare enum. However, it does not explicitly state that the parameter is optional or that omitting it returns all schedules.
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 clearly states the verb 'List schedules' and enumerates the specific fields returned (id, client, cadence, amounts, dates, status, next due date, auto_generate), which distinguishes it from single-fetch tools like schedule_get. It also mentions filtering, making the purpose unmistakable.
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 usage for listing schedules and supports filtering by status, but it does not explicitly contrast with sibling tools like schedule_get, schedule_history, or schedule_upcoming. There are no 'use this instead of X' directives, so the agent must infer when this tool is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stop one schedule generating invoices without deleting it; invoice_generate_due and forecast skip it. Its periods keep falling due and resuming back-bills them, so use schedule_skip to drop just one.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only indicate that the tool is not read-only and not destructive. The description adds meaningful behavioral context: paused schedules stop generating invoices, due periods continue accumulating, and resuming later back-bills them. This goes beyond structured fields, though it does not cover repeated-pause or error behavior.
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 dense, purposeful sentences. The first front-loads the core action and non-destructive nature; the second adds the critical resumption-side-effect and routes to the correct sibling tool. No filler or redundancy.
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 single-parameter mutation tool, the description covers the central side effects and the alternative tool. The main gap is that it never explicitly maps the 'id' parameter to the schedule entity, but the low complexity and strong sibling differentiation keep this from being a major omission.
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 sole required parameter 'id' has no schema description. The description never mentions that id identifies the schedule to pause. With low schema coverage, the description should compensate by explaining the parameter, but it does not.
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 uses a specific verb and resource: 'Stop one schedule generating invoices without deleting it.' It clearly differentiates the tool from schedule_delete (no deletion) and from generation tools like invoice_generate_due and forecast, which will skip the paused 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?
The description explicitly states when to use schedule_pause versus schedule_skip: pause stops invoice generation indefinitely while periods continue falling due; schedule_skip is for dropping a single occurrence. It also clarifies that generation and forecast tools will skip the paused schedule, giving an agent a clear decision path.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Make a paused schedule active again. Every period missed while it was paused is still due and the next invoice_generate_due creates them all. Refused when it would pass the free tier's 3 active.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the description doesn't need to restate those. It adds valuable behavioral context: missed periods remain due and are created by the next invoice_generate_due, and the operation is refused when it would exceed the free tier's active limit. This goes 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 sentences, each earning its place: the action, the behavioral consequence, and the refusal condition. Front-loaded with the core purpose. No wasted words.
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 single-parameter tool with no output schema, the description covers the action, the side effect (missed periods due), and a failure condition. It doesn't describe the return value, but with no output schema that's less critical. It also doesn't explicitly state prerequisites (e.g., schedule must exist and be paused), but 'paused schedule' implies that.
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. The description doesn't explain the 'id' parameter beyond what the schema provides (a string). However, with only one parameter named 'id', the meaning is fairly obvious: it identifies the schedule to resume. The description could have added 'id of the schedule to resume' but the context is sufficient.
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 ('Resume'), a resource ('a schedule'), and the state transition ('Make a paused schedule active again'). It clearly distinguishes from siblings like schedule_pause and schedule_create by focusing on the resume action.
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 use it: when a schedule is paused and should become active again. It also mentions a refusal condition (free tier's 3 active limit), which gives context for when it might not work. It doesn't explicitly name alternatives, but the sibling list and the verb 'resume' make the usage context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Close ONE occurrence for good without pausing the schedule, reporting what will not be billed. period must be a real occurrence of it. An invoiced period is refused; undo reopens a skip.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Schedule id, or a client name | |
| undo | No | Remove a previous skip so the period becomes due again. Works only on a period that has not been invoiced. Default false | |
| period | Yes | The occurrence date to skip, YYYY-MM-DD, exactly as it appears in schedule_upcoming or forecast. This is the answer to "pause this client for October": schedule_pause stops the whole schedule and a resumed schedule still back-bills the periods it missed, whereas a skipped period is closed for good |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important behaviors beyond the annotations: the operation is permanent ('for good'), irreversible only via undo, refused on invoiced periods, and reports what will not be billed. It does not detail response format or edge cases, but the core mutation semantics are clearly conveyed.
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 short and front-loads the most important fact. The sentence 'period must be a real occurrence of it' is slightly awkward and could more clearly say 'of the schedule,' but overall every sentence contributes meaning and the text is not bloated.
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 no output schema, the description covers the essential invocation conditions: required parameters, exact period format, invoiced-period restriction, and undo semantics. It does not describe the exact return payload, but the phrase 'reporting what will not be billed' gives a reasonable expectation of the result.
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 100%, and the parameter descriptions are thorough: id accepts a schedule id or client name, period requires a YYYY-MM-DD date appearing in schedule_upcoming or forecast, and undo is explained. The description adds reasonable context without needing to repeat every schema detail.
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 action ('Close ONE occurrence for good'), the resource (a schedule period), and the key effect (not pausing the schedule). It also distinguishes itself from schedule_pause by saying it skips one occurrence rather than stopping the whole 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?
The description explicitly contrasts this tool with schedule_pause, explaining that pausing stops the whole schedule and back-bills missed periods, while skipping closes one period for good. It also states the invoiced-period refusal and the undo behavior, giving clear conditions for correct use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Table every occurrence of every ACTIVE schedule due in the next N days (30 default), with its amount and the invoice due date, plus a total per currency. Free lists the first 3 in your horizon.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Days ahead, default 30. The free tier honours the horizon you ask for and lists the first 3 occurrences in it; Pro lists them all |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds useful behavioral context: it only considers ACTIVE schedules, defaulting to 30 days, and the free tier truncates results to the first 3 occurrences. However, since readOnlyHint is false and the description never explicitly states this is a read-only report, an agent cannot fully rely on its apparent list-only nature.
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 short, information-dense sentences. The core operation is front-loaded, the scope and returned fields are specified, and the free-tier limit is included compactly. There is no filler or redundancy.
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 one-optional-parameter tool with no output schema, the description supplies the essential return information (amount, invoice due date, total per currency) and the horizon/free-tier behavior. It lacks finer details like timezone handling or exact output field names, but those are minor given the simplicity of the tool.
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 100%: the `days` parameter description already documents the default, min/max range, and free-tier vs. Pro behavior. The tool description repeats the 30-day default and free-3 limit but adds no new parameter semantics, so it does not elevate beyond the schema baseline.
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 operation: 'Table every occurrence of every ACTIVE schedule due in the next N days,' specifying the resource (active schedules' due occurrences), the default horizon, and the returned data (amount, invoice due date, total per currency). This clearly distinguishes it from sibling tools like schedule_get, schedule_list, and schedule_history, which focus on individual schedules or different views.
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 gives clear context for when to use it: when you need an aggregate view of upcoming due occurrences across all active schedules within a horizon. It does not explicitly name alternatives or state exclusions, so it stops short of a fully explicit routing guide, but the intended use is strongly implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change one schedule by id: client, items, currency, cadence, dates, due_days, notes or auto_generate. Only the fields you pass change. Periods already invoiced are never re-issued, so a new amount applies to future ones.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| every | No | How often to bill: "weekly", "monthly", "quarterly", "yearly", or {days: 10}. Month steps keep the start date's day of month and clamp it to shorter months, so a schedule starting on the 31st bills on the 28th/29th in February and back on the 31st in March | |
| items | No | ||
| notes | No | ||
| client | No | ||
| currency | No | ||
| due_days | No | ||
| end_date | No | null clears the end date | |
| tax_note | No | Replace the tax reason carried onto every future generated invoice. Pass an empty string to clear it | |
| anchor_day | No | Pro | |
| start_date | No | ||
| end_of_month | No | Pro | |
| auto_generate | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses two important behavioral traits: partial updates and the fact that already-invoiced periods are never re-issued, with new amounts applying only to future periods. This adds meaningful context beyond the annotations, which only indicate non-read-only and non-idempotent behavior. No contradiction with annotations exists.
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 two sentences with no filler. It front-loads the purpose and scope, then states the critical invariants. Every sentence 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?
For a 13-parameter mutation tool with no output schema and minimal annotations, the description provides the key update semantics and the invoicing invariant, but it leaves many field-level details and return/error behavior to inference. It gives a solid first-order understanding without being fully operationally complete.
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 low at 38%, so the description carries part of the parameter-semantics burden. It lists the mutable fields and adds the valuable partial-update rule, but it does not explain fields like due_days, auto_generate, client, or currency beyond their names. This is adequate but not fully compensating for the schema gaps.
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 starts with 'Change one schedule by id', giving a specific verb and resource, and then enumerates the editable fields. This clearly distinguishes the tool from siblings like schedule_create, schedule_delete, and schedule_pause without needing to open their schemas.
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 clearly implies an update-to-existing-schedule use case through 'by id' and 'only the fields you pass change'. It does not explicitly name alternatives such as schedule_create for new schedules or schedule_pause/schedule_resume for state changes, so exclusion guidance is implicit rather than explicit.
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.
forecastinvoice_generate_duelicense_activatelicense_statusschedule_createschedule_deleteschedule_getschedule_historyschedule_listschedule_pauseschedule_resumeschedule_skipschedule_upcomingschedule_updateRecurring invoices on a schedule: define once, generate the due PDFs, forecast revenue.
Statements of account, aging buckets and dunning letters from your invoices.
Create PDF invoices from your AI chat: clients, numbering, VAT, overdue reports. All data is local.
Read subscriptions, customers, charges, orders; skip charges, cancel or activate subscriptions.
Add one secure layer between your agents and this server.