Credit notes against issued invoices and purchase orders to suppliers, with VAT and A4 PDFs.
Scored across 16 tools
The tools split cleanly into credit-note, purchase-order, licensing, and reporting groups. Within each group, actions are distinct: create/delete/get/list/pdf/text/receive have clear boundaries, and the pdf/text pairs are explicitly differentiated by output format.
All tool names use snake_case and follow a predictable domain_entity_action or domain_entity_output pattern. The few noun-only names like license_status and billing_docs_report still fit the same readable convention.
Sixteen tools cover two document domains plus licensing and reporting, with each tool earning its place. The count is reasonable for the scope and does not feel bloated.
Core lifecycle coverage is strong: create, read, list, delete, export, and receive are all present for the document types. Minor gaps exist, such as no update/edit operation for purchase orders and no invoice lookup to support credit-note creation, but these are workable around the stated domain.
Over a date range: what was credited back per currency and against how many invoices, what is still on order per currency, and every open order past its delivery date with days late. Pro; the list tools are free.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | YYYY-MM-DD, latest document date to count | |
| from | No | YYYY-MM-DD, earliest document date to count |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds real behavioral context beyond the annotations by disclosing the Pro-tier gating and by spelling out the three report sections. It says nothing about permissions, output format, or whether the date range is optional (required parameters is 0), and it sits in mild tension with readOnlyHint=false / idempotentHint=false for what reads as a pure aggregation.
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 that spends every clause on a distinct report section, plus one short tier note. It leads with the date-range scoping rather than the tool's identity, but nothing is wasted or repetitive.
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 carries the full burden of describing return values and does so explicitly across all three sections, including the day-count for late orders. For a two-parameter read-style report this is enough for an agent to call it and interpret 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%, so both parameters are already documented as YYYY-MM-DD bounds on document date. The phrase 'over a date range' confirms that the range filters document dates rather than, say, delivery dates, but adds no syntax, default, or inclusivity detail beyond 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 enumerates three concrete outputs — credited-back amounts per currency with invoice counts, still-on-order amounts per currency, and open orders past their delivery date with days late — so the agent knows exactly what the tool produces. It implicitly contrasts with the free list tools (credit_note_list, purchase_order_list) but never names them, so sibling differentiation is present but soft.
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 clause 'Pro; the list tools are free' hints that a free-tier user should route to the list tools instead, which is a partial alternative signal. However, it never states when to prefer this aggregation over those list tools, nor what happens with an omitted or inverted date range.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Credit one invoice: the whole invoice, a GROSS amount_minor split over its VAT rates, or named lines. Amounts store negative, reusing the invoice's own rates. Free: 5 a month. Send it with credit_note_text.
| Name | Required | Description | Default |
|---|---|---|---|
| lines | No | Credit only these invoice lines. Leave out with amount_minor for a full credit note | |
| notes | No | Free text printed under the totals | |
| reason | Yes | Why the money is being given back, e.g. "returned goods" or "billed twice". Printed on the document | |
| invoice | Yes | The invoice number to credit, e.g. INV-2026-0001 | |
| issue_date | No | YYYY-MM-DD, defaults to today in your business profile's timezone | |
| amount_minor | No | Credit this GROSS amount, VAT included, in minor units. Split across the invoice's VAT rates in proportion to each rate's share of the total |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as a non-destructive write that is not idempotent. The description adds meaningful behavioral context beyond that: amounts are stored negative, the invoice's own VAT rates are reused, and there is a free-tier limit of five per month.
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 core modes before adding storage and quota details. 'Free: 5 a month' and 'Send it with credit_note_text' are abrupt but still informative rather than wasteful.
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 six-parameter write tool with full schema coverage and annotations, the description covers the important creation modes, rate behavior, quota, and companion workflow. It does not explain failure cases or return data, but no output schema exists and the annotations already carry the safety profile.
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 schema already explains each parameter thoroughly, including amount_minor's gross VAT-inclusive behavior and line quantity semantics. The description reinforces the mutually exclusive modes but adds little parameter meaning that the schema does not already provide.
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 gives a specific verb and resource ('Credit one invoice') and enumerates three operating modes: full credit, gross amount_minor, or named lines. It distinguishes create from the text companion by saying 'Send it with credit_note_text', though it does not clarify differences from other credit-note siblings like get/list/delete.
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 clearly frames the three supported credit scenarios and the follow-up workflow with credit_note_text. It does not state explicit exclusions or when to choose this over sibling tools, so the guidance is strong but not complete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove one credit note never posted to its invoice and never rendered, freeing that month's slot; the invoice becomes creditable again. One with a dependent is refused: issue a fresh note to reverse a sent one.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Credit note id such as CN-2026-0001, or an exact client name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, it discloses the concrete consequences: the month's slot is freed and the invoice becomes creditable again, plus the failure mode when a dependent exists. It does not say what happens for an unknown or already-deleted id, which matters given idempotentHint=false.
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 tight sentences with the eligibility constraint front-loaded and the refusal case second. Phrasing such as "One with a dependent is refused" is slightly telegraphic but costs no clarity overall.
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 destructive tool with full annotation coverage and no output schema, the description supplies everything an agent needs: preconditions, side effects, and the blocking failure case.
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 id property already documents both the CN-YYYY-NNNN format and the exact-client-name option. The description adds no parameter-level meaning, so the baseline 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?
"Remove one credit note" states a specific verb and resource, then narrows the scope to notes never posted to an invoice and never rendered. That scope plus the stated eligibility conditions make it unmistakable against siblings like credit_note_create or credit_note_pdf.
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 defines when the tool applies (unposted, unrendered notes) and when it will not (a note with a dependent), and routes the agent to the alternative action in that case: issuing a fresh note to reverse a sent one. Both the use case and the fallback are explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return one credit note in full by id or exact client name: every negated line, VAT lines, totals, the reason, and the invoice number and date it reverses. Reads only. Use credit_note_list for the ids.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Credit note id such as CN-2026-0001, or an exact client name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description asserts "Reads only," but the annotations declare readOnlyHint=false, i.e. the tool may modify state. That is a direct conflict about the tool's safety profile, the single most important property for an agent deciding whether to invoke it. Whatever accurate detail the description adds about returned fields is undercut by this contradiction.
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 sentences with zero filler: the return payload is front-loaded, then the read-only claim, then the routing pointer. Every clause carries information and the ordering puts the most decision-relevant content first.
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 correctly carries the burden of explaining return values and does so concretely (lines, VAT, totals, reason, reversed invoice details). The one gap is that it doesn't clarify how it relates to credit_note_text/credit_note_pdf for an agent choosing between them.
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 single parameter already documents both accepted forms ("CN-2026-0001" or an exact client name), so the schema does the heavy lifting. The description's "by id or exact client name" restates that without adding format or disambiguation detail, so the baseline 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?
Specific verb and resource ("Return one credit note") plus an explicit inventory of what comes back: negated lines, VAT lines, totals, reason, and the reversed invoice number and date. It also names the lookup keys (id or exact client name), so an agent can distinguish it from credit_note_list 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?
It gives explicit routing advice: "Use credit_note_list for the ids," which tells the agent when to pick the sibling instead. What's missing is any guidance versus credit_note_text and credit_note_pdf, which are the other retrieval-style siblings and could plausibly be confused with this one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List credit notes newest first: id, invoice, client, basis, reason, currency and the NEGATIVE total, with the amount credited per currency. Filter by invoice, client or issue date range.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | YYYY-MM-DD, latest issue date | |
| from | No | YYYY-MM-DD, earliest issue date | |
| client | No | Only credit notes for clients whose name contains this text | |
| invoice | No | Only credit notes issued against this invoice number |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description depicts a pure read/listing operation, yet the annotations declare readOnlyHint=false, which is inconsistent and could make an agent hesitate or expect side effects; the description does nothing to reconcile this. It does add useful behavioral detail beyond the annotations — deterministic newest-first ordering, the fact that totals are NEGATIVE, and per-currency aggregation — but omits result-size/pagination 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?
One front-loaded sentence covering purpose, return shape and filtering, with zero filler. It is dense — the return-field list and the filter list are packed together — but 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?
There is no output schema, so describing the returned fields, ordering, and the negative-total convention is genuinely necessary and well done. Missing: any indication of pagination, limits, or default result size for an unfiltered list, which matters for a 0-required-parameter listing 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% with format hints (YYYY-MM-DD) and substring semantics for client, so the description only restates the filters. It adds no syntax or combination rules beyond what the schema already documents, making the baseline 3 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 ('List credit notes') and enumerates exactly what each row contains (id, invoice, client, basis, reason, currency, negative total, credited amount per currency). This clearly separates it from siblings like credit_note_get, credit_note_text and credit_note_pdf, which return a single note or a rendered document.
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 usage context: browse all notes newest-first, or narrow by invoice, client, or issue-date range. It does not explicitly name alternatives (e.g., 'use credit_note_get for a single note by id'), so the agent must infer routing from the sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call this tool to render one credit note as an A4 print-ready document and return a download link valid for one hour: the invoice layout titled CREDIT NOTE, with the invoice it reverses. Pro.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Credit note id such as CN-2026-0001 | |
| out_path | No | Name for the downloaded file, e.g. acme-credit. Defaults to the document id; the document comes back as a download link valid for one hour |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare the mutability profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=false). The description adds genuinely new behavioral facts: the output is a download link that expires after one hour, the page format is A4, and the document embeds the reversed invoice. The trailing 'Pro' hints at a plan/entitlement gate, though it is unexplained and never states what happens if the account is not entitled.
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?
It is a single front-loaded sentence that puts the action and artifact first, then appends the return-value and layout details after the colon. Slightly run-on and the dangling 'Pro' token is unexplained, but there is 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?
For a two-parameter render tool with full schema coverage and no output schema, the description covers the action, the document content, and the shape of the return value (a one-hour download link), which is the critical missing piece an output schema would otherwise supply. It stops short of covering failure modes (invalid id, plan not entitled, expired link) which would round it out.
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%, covering both 'id' and 'out_path', so the schema already carries the parameter meaning. The description reinforces the download-link/one-hour lifetime for the out_path result but adds no syntax, format, or defaulting detail beyond what the schema says. Baseline 3 applies when the schema does the heavy lifting.
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 ('render'), a specific resource ('one credit note'), and states the output artifact ('A4 print-ready document' plus 'download link'). It also scopes the content ('the invoice layout titled CREDIT NOTE, with the invoice it reverses'), which distinguishes it from credit_note_text and from purchase_order_pdf without needing the sibling 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 opening 'Call this tool to render one credit note' gives an implied when-to-use, and the 'download link valid for one hour' implies the transient nature of the result. However, it never names the alternative (credit_note_text) or states when-not to use this tool, leaving the agent to infer that credit_note_text is the non-PDF path.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Turn a credit note into a plain-text summary to paste into an email: the negated line table, VAT lines, total, reason, and what now comes off the invoice. Also a .txt download link valid one hour. Free; credit_note_pdf writes the A4 document.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Credit note id such as CN-2026-0001 | |
| greeting | No | Opening line, default "Hello" plus the client name | |
| sign_off | No | Closing line, default your business name from the shared profile |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds behavior not present in the annotations: the result includes a downloadable .txt link that expires after one hour, and the call is free. The TTL detail usefully explains why idempotentHint=false (each call mints a fresh link). Nothing here contradicts the annotations, though permissions and whether the note must pre-exist are not addressed.
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-loads the core purpose and output contents in one dense sentence, then the link/cost/alternative facts in a short coda with zero filler. The telegraphic 'Free; credit_note_pdf writes the A4 document' fragment is efficient but slightly clipped in register.
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 compensates by listing exactly what the text contains and mentioning the download link's lifetime, which is what an agent needs to report results. The one remaining ambiguity — that this is not purely read-only because it generates a file — is only implicitly covered by the link sentence.
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 all three parameters (id, greeting, sign_off) carry their own descriptions including default behavior, so the schema does the semantic work. The description adds no parameter-level meaning at all, which is the baseline-3 case rather than a deficiency.
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 concrete verb and output form ('Turn a credit note into a plain-text summary to paste into an email') and enumerates the actual content produced: negated line table, VAT lines, total, reason, and what comes off the invoice. It also names the sibling it is not ('credit_note_pdf writes the A4 document'), so an agent can pick between the two 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?
The email-paste framing plus the explicit contrast with credit_note_pdf gives a clear selection rule (text for email body, PDF for a formal A4 document). It does not state exclusions such as when to use credit_note_get instead if only raw data is needed, or whether the note must already exist, so it stops short of full when/when-not guidance.
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 declare non-read-only, non-destructive, non-idempotent, closed-world. The description adds real value beyond that: the effect is scoped to 'this connection', existing data under the token is preserved, and a wrong or expired key is a no-op. It does not say whether the change is immediate or whether repeat activation is harmless, which is relevant given idempotentHint=false.
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 sentences, front-loaded with the effect and followed by the failure guarantee and verification pointer. No filler or restated boilerplate.
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, no-output-schema tool with annotations covering the safety profile, this is close to complete: effect, scope, failure behavior, and a verification sibling are all covered. Only minor gaps remain (immediacy of effect, behavior when already licensed).
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 single param already documents the MCPL1 format, so the baseline is 3. The description earns an extra point by adding provenance the schema lacks: the key is issued at checkout and must be for this server or the bundle.
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 action (turn Pro on) and its scope (for this connection), plus the exact credential shape required. It also positions the sibling license_status as the verification path, so an agent can distinguish activation from status checking 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?
It states the precondition clearly: the key must be an MCPL1.<payload>.<signature> token issued at checkout for this server or the bundle, and directs verification to license_status. It stops short of explicit when-not-to-use guidance (e.g., what to do if already Pro or if the key is for a different server).
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.
Raise a purchase order to a supplier from items and return its PO number and totals. unit_price is in MAJOR units; currency, VAT and the buyer block come from the shared profile. Free: 5 documents a calendar month.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | What is being ordered | |
| notes | No | Free text printed under the totals, e.g. delivery address or terms | |
| currency | No | Defaults to your business default currency | |
| supplier | Yes | Supplier name or client id. A name the invoice server already knows brings its address, email and VAT id onto the order | |
| tax_rate | No | VAT percent for lines with no rate of their own. Defaults to the business default | |
| issue_date | No | YYYY-MM-DD, defaults to today in your business profile's timezone | |
| supplier_email | No | Only if the user gave it; otherwise the stored client's email is used | |
| supplier_vat_id | No | Supplier VAT / tax registration id | |
| discount_percent | No | Discount applied to every line, in percent | |
| supplier_address | No | Postal address for the SUPPLIER block, newlines allowed | |
| expected_delivery_date | No | YYYY-MM-DD, when the goods or work are due |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish write, non-idempotent, non-destructive, closed-world, so the bar is lower. The description still adds real value: it says what comes back (PO number and totals), that currency/VAT/buyer block are inherited from the shared profile, and that the tool is rate-limited to 5 documents per calendar month — a quota note the annotations do not carry.
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, each earning its place: what it does, the unit/defaults caveat, the quota. No filler, front-loaded with purpose.
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 an 11-parameter write tool with no output schema, the description usefully names the return values and profile-derived defaults. But it omits any mention of nested line-item constraints (all lines must share one currency, max 200 items) and, worse, gives a unit convention that conflicts with the schema, leaving an agent materially misinformed on the most error-prone parameter.
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 sentence 'unit_price is in MAJOR units' directly contradicts the schema parameter unit_price_minor, whose own description says 'MINOR units: 9000 = 90.00 EUR ... Never a decimal'. An agent trusting the description would send prices 100x too high. The defaults note (currency, VAT, buyer block from profile) does add some meaning, but the unit error is material and dangerous; the schema's 100% coverage carries the rest.
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?
Name says it, and the description says it: specific verb 'Raise', resource 'purchase order', and states the inputs (items) and output (PO number and totals). Clearly distinguished from the sibling set (list/get/receive/pdf/delete), which all operate on existing POs rather than creating 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?
Creation intent is obvious, but the description never routes against alternatives — e.g., when to use purchase_order_create vs. purchase_order_receive, or that an unknown supplier gets created implicitly on the invoice server. The free-tier quota sentence gives useful routing context for constrained accounts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove one purchase order with nothing received and never rendered, freeing that month's slot. One with a receipt is refused, naming it. The PO number is never reissued. purchase_order_receive logs arrivals.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Purchase order id such as PO-2026-0001, or an exact supplier name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=false, and the description adds real value beyond them: the refusal condition, the fact that the error names the offending receipt, the quota effect ('freeing that month's slot'), and that the PO number is never reissued. No auth or confirmation requirements are mentioned, keeping it just short of 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, front-loaded with the action and its preconditions, with no filler. The phrase 'never rendered' is compressed to the point of obscurity and costs a little clarity.
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 single-parameter tool with no output schema, the description covers preconditions, failure behavior, and irreversibility of the PO number. It does not say what a success response looks like or whether confirmation is required, a minor remaining gap.
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?
With 100% schema coverage on a single parameter, the schema already documents 'id'. The description adds no clarification of the surprising schema detail that an exact supplier name is also accepted, which is the one place extra meaning would have helped.
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 plus the eligibility conditions ('nothing received and never rendered'), which distinguishes it from purchase_order_receive and the other PO siblings. The term 'rendered' is domain jargon left unexplained, slightly blurring the exact scope of what qualifies for deletion.
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 a clear eligibility rule (no receipt, never rendered) and states the refusal case, which effectively tells the agent when the call will fail. It points at purchase_order_receive for arrivals, but that is not a true alternative for this operation and no explicit 'use this instead of X when...' guidance is offered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return one purchase order in full by id or exact supplier name: buyer and supplier blocks, every line with unit price and VAT, totals, the delivery date, status and every receipt with its date and note.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Purchase order id such as PO-2026-0001, or an exact supplier name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description usefully discloses the return payload (buyer/supplier blocks, lines with unit price and VAT, totals, delivery date, status, receipts with date and note), which is real behavioral value since there is no output schema. However, it frames the operation as a pure retrieval while the annotations declare readOnlyHint=false and idempotentHint=false — an agent cannot tell whether calling this mutates or locks anything. The description also does not say what happens when a supplier name matches more than one order, despite promising to return exactly one.
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?
One front-loaded sentence that wastes no words and puts the operation and lookup key before the payload enumeration. It is dense but scanable; the only cost is that the long clause chain into the returned fields reads like a list rather than prioritized structure.
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 carries the return-value burden and does so thoroughly for a simple single-parameter lookup. Missing pieces are the sibling routing (list vs text vs pdf) and the multi-match/idempotency behavior, but nothing essential to invoking it is absent.
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 single parameter is already documented as 'PO-2026-0001 or an exact supplier name'; the description simply repeats that. No extra meaning (format rules, case sensitivity, multiple-match behavior) is added beyond the schema, 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 states a specific verb and resource ('Return one purchase order in full') and immediately scopes it ('by id or exact supplier name'), which cleanly separates it from the list tool in the sibling set. It also enumerates the returned content, so an agent knows exactly what it gets 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?
Usage is only implied: 'one purchase order in full' hints that this is the detailed single-record read versus purchase_order_list, and probably versus purchase_order_text/purchase_order_pdf. But no alternative is named and no condition for choosing between them is given, so the agent must infer the routing itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List purchase orders newest first: id, supplier, order and expected delivery dates, status open, partially_received or received, currency, total and received date. Filter by status, supplier or date range.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | YYYY-MM-DD, latest order date | |
| from | No | YYYY-MM-DD, earliest order date | |
| status | No | Default "all" | |
| supplier | No | Only orders to suppliers whose name contains this text |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations declare readOnlyHint=false, which is at odds with a pure listing operation; the description does nothing to explain what the tool does that is non-read-only, nor what permissions it needs. Beyond ordering ('newest first'), it adds little behavioral context such as result volume limits or whether all records are returned when no filters are supplied.
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?
One dense sentence that front-loads the verb, resource, and sort order, then the returned fields, then the filters. Every clause carries information, though the field enumeration makes the middle section slightly list-like for an agent that mostly needs the filters.
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 enumeration of returned fields (id, supplier, dates, status, currency, total) is genuinely useful and largely compensates. However, there is no limit or pagination parameter and the description says nothing about result size or truncation, which matters for an unfiltered list on a schema with zero required parameters.
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%, with date formats, the enum, and the 'all' default all documented in the schema itself. The description only restates the three filter dimensions, adding no semantics such as inclusive/exclusive date bounds or supplier matching behavior beyond what the schema says.
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 ('List purchase orders') plus the sort order ('newest first'), which no sibling name conveys. It does not explicitly distinguish itself from purchase_order_get or purchase_order_receive, so an agent must infer that this is the multi-record read.
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 names the three filter dimensions (status, supplier, date range) and enumerates the status values, which implicitly tells the agent how to narrow results. It never states when to prefer purchase_order_get for a single order or purchase_order_receive for receiving, and gives no guidance on omitting filters entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call this tool to render one purchase order as an A4 print-ready document and return a download link valid for one hour: the invoice layout titled PURCHASE ORDER, with the buyer and supplier. Pro.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Purchase order id such as PO-2026-0001 | |
| out_path | No | Name for the downloaded file, e.g. acme-credit. Defaults to the document id; the document comes back as a download link valid for one hour |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this is a non-read-only, non-idempotent, non-destructive, closed-world operation, and the description adds genuinely new behavior: the output is A4 print-ready, the return is a download link, and that link expires after one hour. It does not say whether a file is persisted server-side, which is the main remaining unknown for a write-flagged tool that produces an artifact.
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?
One front-loaded sentence that puts the action, the format, and the return value in a sensible order before the colon. The trailing fragment 'Pro.' is unexplained noise that slightly undercuts an otherwise tight definition.
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 two-parameter render tool with full schema coverage and no output schema, the description covers format, layout contents (buyer and supplier), and link lifetime, which is close to everything an agent needs. Only the persistence/regeneration story 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%, with both 'id' (example PO-2026-0001) and 'out_path' (filename, defaults to document id) already documented inline. The description only repeats the one-hour download-link detail for the output rather than clarifying parameter behavior, so baseline 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?
States a specific verb and resource ('render one purchase order as an A4 print-ready document') plus the concrete outcome ('return a download link valid for one hour'), which distinguishes it from purchase_order_get and purchase_order_text by output format. It stops short of naming those siblings, so the differentiation is inferential rather than explicit.
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?
'Call this tool to render...' implies the usage condition (you need a printable/downloadable PDF of a single PO), but there is no explicit when-not guidance and no named alternative for the text or JSON views despite three sibling tools covering those shapes. An agent can infer the choice but must do the work itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record that an order arrived. partial keeps it open and can be repeated, each receipt kept with its date and note; a full receipt closes it. An order already received, or a date before the order date, is refused.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Purchase order id such as PO-2026-0001 | |
| date | No | YYYY-MM-DD, defaults to today | |
| note | No | What arrived, e.g. "8 of 10 units, 2 back-ordered" | |
| partial | No | True when only some of the order arrived. The order stays open and can be received again. Default false |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (which only say non-read-only, non-idempotent, non-destructive), the description discloses the state machine: partial receipts keep the order open and can be repeated, each receipt is retained with date and note, a full receipt closes it, and two refusal conditions. That is exactly the side-effect and failure-mode detail an agent needs before mutating.
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 with no filler; the core action comes first, then the partial/full branch, then the rejection rules. Every clause carries information an agent would otherwise have to discover by error.
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 behavior changes and error cases well. It stops short of saying what the response looks like or whether stock/quantities are updated downstream, a minor gap for a write operation.
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 baseline is 3, but the description adds meaning beyond the schema: it explains the consequence of `partial` (order stays open, can be received again) and that `date` is validated against the order date. Only `id` and `note` semantics are left entirely to 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?
"Record that an order arrived" names a specific verb and resource, and the title/description together make clear this is the receiving action rather than create/get/list/delete in the purchase_order family. An agent can distinguish it from every sibling 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?
The partial-vs-full distinction gives explicit guidance on which mode to choose and what each does (stays open vs closes the order). It does not name an alternative tool for cases like checking current status, but the when-to-use condition is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Turn a purchase order into a plain-text order to paste into an email: the line table, VAT lines, total, and a line asking the supplier to deliver by the date and quote the PO number. Also a .txt download link valid one hour. Free on every tier.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Purchase order id such as PO-2026-0001 | |
| greeting | No | Opening line, default "Hello" plus the supplier name | |
| sign_off | No | Closing line, default your business name from the shared profile |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior: the exact sections produced and an ephemeral .txt download link valid for one hour, plus that it is free on every tier. It does not explain why the tool is non-read-only (the link artifact) or what happens on a bad PO id.
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, front-loaded with the transformation and its contents, with the link and pricing details after. Nearly every clause carries information, though 'Free on every tier' is commercial framing rather than invocation guidance.
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?
No output schema exists, and the description compensates well by enumerating the rendered sections and the download-link delivery mechanism. Combined with a fully documented input schema, an agent has enough to call it correctly; only error behavior is left unstated.
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 all three parameters are described there, including the PO-2026-0001 id format and the greeting/sign_off defaults. The description adds nothing about greeting or sign_off customization, so baseline 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?
States a specific verb and transformation (turn a purchase order into a plain-text order) and enumerates exactly what the output contains: line table, VAT lines, total, delivery line. The email-paste framing implicitly separates it from the PDF sibling, but it never names purchase_order_pdf or purchase_order_get as alternatives.
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 'to paste into an email' framing gives a clear intended use case, so an agent can infer when this is the right renderer. However, there is no explicit when-not guidance and no named alternative for PDF-style output, which matters given the sibling cluster of purchase_order_get/pdf/list.
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.
billing_docs_report1 field changedInput schema / additionalPropertiesRemoved value: -falsecredit_note_create4 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / lines / items / additionalPropertiesRemoved value: -falseInput schema / properties / lines / items / properties / line / maximumAdded value: +9007199254740991Input schema / properties / lines / items / properties / quantity / minimumRemoved value: --1000000000000credit_note_delete1 field changedInput schema / additionalPropertiesRemoved value: -falsecredit_note_get1 field changedInput schema / additionalPropertiesRemoved value: -falsecredit_note_list1 field changedInput schema / additionalPropertiesRemoved value: -falsecredit_note_pdf1 field changedInput schema / additionalPropertiesRemoved value: -falsecredit_note_text1 field changedInput schema / additionalPropertiesRemoved value: -falselicense_activate1 field changedInput schema / additionalPropertiesRemoved value: -falsepurchase_order_create3 fields changedInput schema / additionalPropertiesRemoved value: -falseInput schema / properties / items / items / additionalPropertiesRemoved value: -falseInput schema / properties / items / items / properties / quantity / minimumRemoved value: --1000000000000purchase_order_delete1 field changedInput schema / additionalPropertiesRemoved value: -falsepurchase_order_get1 field changedInput schema / additionalPropertiesRemoved value: -falsepurchase_order_list1 field changedInput schema / additionalPropertiesRemoved value: -falsepurchase_order_pdf1 field changedInput schema / additionalPropertiesRemoved value: -falsepurchase_order_receive1 field changedInput schema / additionalPropertiesRemoved value: -falsepurchase_order_text1 field changedInput schema / additionalPropertiesRemoved value: -falsebilling_docs_reportcredit_note_createcredit_note_deletecredit_note_getcredit_note_listcredit_note_pdfcredit_note_textlicense_activatelicense_statuspurchase_order_createpurchase_order_deletepurchase_order_getpurchase_order_listpurchase_order_pdfpurchase_order_receivepurchase_order_textCredit all or part of an invoice with the VAT reversed, raise purchase orders, print A4 PDFs.
Credit notes against an invoice or standalone: drafts, finalization, rendering, totals.
Numbered invoices with VAT as A4 PDFs, a client list, payments and a list of overdue invoices.
Render invoices and credit notes as PDFs, and check them against EN 16931 e-invoicing rules.
Add one secure layer between your agents and this server.