Credit notes against an invoice or standalone: drafts, finalization, rendering, totals.
Scored across 10 tools
Each tool has a clearly distinct purpose: create, delete, finalize, get, list, render, summary, update for credit notes, plus two separate license management tools. No overlap in functionality even between get and list, as get returns a single document while list provides filtered summaries. The license tools are unambiguously separate and clearly named.
All credit note tools follow a consistent verb_noun pattern (credit_note_create, credit_note_delete, etc.) with exactly the same prefix. The license tools similarly use a consistent license_ prefix with action verbs. This uniform style makes the tool names predictable and easy to navigate.
With 10 tools, the server is well-scoped for its purpose of credit note lifecycle management. It includes CRUD operations, a finalize state transition, rendering, and reporting, without superfluous additions. The two license tools are necessary for tier management and fit within the overall count.
The tool set covers the full credit note lifecycle: create, read (get and list), update, delete (for drafts), finalize, render, and summary. It also handles filtering and reporting, making it functionally complete for the domain. No obvious missing operations that would block typical workflows.
Issue a credit note against an invoice, or standalone: the recipient, the reason (returned goods, overcharge, discount correction, service issue, other), line items with quantity, unit price and tax rate, and the currency. Returns a draft you can still revise; credit_note_finalize burns the final CN number.
| Name | Required | Description | Default |
|---|---|---|---|
| lines | Yes | What is being credited, line by line | |
| notes | No | Text printed at the foot of the document, e.g. how the credit will be settled | |
| reason | Yes | Why the credit is issued: returned_goods, overcharge, discount_correction, service_issue or other | |
| currency | Yes | ISO code the credit is in | |
| recipient | Yes | Who the credit is for, e.g. Acme GmbH | |
| issue_date | No | The date the credit is issued, YYYY-MM-DD. Default today; a future date is refused | |
| invoice_ref | No | The invoice this credits, e.g. INV-2026-0042. Omit for a standalone credit | |
| duplicate_ok | No | Create it even though an identical draft or note exists, for a genuinely repeated credit. Default false | |
| reason_detail | No | One line of specifics, e.g. Client was billed 10 seats, used 7 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide readOnly=false, idempotent=false, destructive=false, so the description adds the key behavior: it returns a draft that can still be revised, and credit_note_finalize later burns the final CN number. This is the most important non-obvious behavior, though it does not discuss duplicate handling or side effects beyond the draft state.
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: the first scopes the operation and enumerates key fields, the second explains the draft workflow and the finalize step. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter creation tool with no output schema, the description covers the core workflow: create draft, revise later, finalize later. It does not describe the draft response shape, but 'returns a draft' plus the fully documented schema is adequate for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description does not need to compensate for missing parameter docs. It repeats some param names and adds the standalone-vs-invoice distinction, but the schema already documents invoice_ref as omit for standalone. Minimal added semantic 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?
States a specific verb and resource: 'Issue a credit note against an invoice, or standalone.' It also distinguishes itself from credit_note_finalize by noting this returns a draft, so an agent can separate creation from finalization.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context for when to use it (to issue a draft credit note) and names the finalize sibling as the next step. It does not explicitly rule out update/delete or compare against all siblings, but the draft-vs-finalize workflow is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a draft credit note entered wrongly, by its draft id. A finalized note is refused by name: it is a document the client may have seen, and deleting it would leave their copy pointing at nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The draft id, e.g. CN-DRAFT-2026-0001 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description explains the rationale for refusing finalized notes (client may have seen them, deletion would leave dangling copies). This adds meaningful behavioral context that the annotation alone does not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler. It front-loads the core purpose and then immediately states the critical constraint, making it efficient and easy to parse.
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 delete tool with one parameter and a destructive annotation, the description covers the essential behavioral constraints. It could potentially mention return values or side effects, but given the simplicity, it is sufficiently 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?
There is only one parameter and the schema description already provides the id format and an example (CN-DRAFT-2026-0001). The description does not add additional semantic meaning beyond what the schema already covers, so the baseline 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 clearly states the action (delete), the target (draft credit note), and the identifier (draft id). It also differentiates from siblings by specifying that finalized notes are refused, which is a key distinction from other credit note operations.
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 clear use case (entered wrongly) and explicitly states when it cannot be used (finalized notes). It doesn't explicitly name alternative tools, but the context is sufficient to guide the agent away from using this on finalized notes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Finalize a draft: burn the final CN-YYYY-NNNN number and freeze the note. From here it cannot be edited or deleted, only rendered and listed, because it is now the document the client sees. Free tier: 10 finalized credit notes; Pro removes the limit.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The draft id, e.g. CN-DRAFT-2026-0001 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the generic annotations by disclosing that the operation is irreversible, freezes the note, prevents future edits/deletions, and restricts future actions to rendering and listing. It also adds quota context ('Free tier: 10 finalized credit notes; Pro removes the limit'), which is valuable operational information an agent could not infer from the schema or annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences each earn their place: the first states the core action, the second explains irreversible behavioral consequences, and the third covers quota constraints. The most important information is front-loaded, with no redundant wording or schema repetition.
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 operation with no output schema, the description covers the essential context: what happens, what becomes impossible afterward, and the quota constraint. The only minor gap is that it does not describe what the API returns after finalization or what happens if the tool is called on an already-finalized note, but these are secondary to successful invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the single id parameter is already clearly documented as 'The draft id, e.g. CN-DRAFT-2026-0001'. The description reinforces that the input is a draft, but adds no meaning beyond the schema, so the baseline 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 starts with a specific verb and resource: 'Finalize a draft', and then clarifies the exact outcome by 'burn the final CN-YYYY-NNNN number and freeze the note'. It distinguishes this from sibling tools by stating that after finalization the note 'cannot be edited or deleted, only rendered and listed', making its role and boundary clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes it clear this tool is for converting a draft into the final client-facing document. It also implies when not to use it: after finalization, editing and deletion are no longer possible, so credit_note_update and credit_note_delete are no longer applicable. It does not explicitly name alternatives, but the usage context is sufficiently clear.
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 by its CN number or draft id: every line with quantity, unit price and tax, the totals per tax rate, the reason, the invoice it credits, and the notes. Reads only; use credit_note_list for the ids.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The credit note number CN-2026-0001 or draft id CN-DRAFT-2026-0001 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states 'Reads only', but the annotations declare readOnlyHint: false. This is a direct contradiction: the structured metadata says the tool is not read-only while the description claims it is. Per the rubric, this inconsistency forces a score of 1 and triggers the annotation_contradiction flag.
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 front-loads the purpose and then lists useful return details and the sibling pointer. Though long, every clause earns its place; it could be broken into two sentences for readability, but it has 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?
There is no output schema, so the description carries the burden of explaining return values—and it does so thoroughly (lines, taxes, reason, credited invoice, notes). It also covers the input format and the relationship to credit_note_list, making the tool fully usable by an agent.
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 parameter is fully documented in the schema with the exact formats ('CN-2026-0001' and 'CN-DRAFT-2026-0001'). The description only repeats 'CN number or draft id' without adding new meaning, so it matches the baseline of 3 rather than exceeding it.
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 ('Return') and identifies the exact resource ('one credit note by its CN number or draft id'), and then enumerates the returned contents (lines, totals, reason, invoice, notes). It also contrasts with the sibling credit_note_list, making the tool's unique role 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?
The description explicitly says 'use credit_note_list for the ids', which is a clear when-not and alternative directive. This tells the agent that if it lacks an ID, it should first call the list tool, leaving no ambiguity about when to invoke this getter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List credit notes: number or draft id, recipient, reason, status, issue date and total. Filter by recipient (a part of the name is enough), by reason, by status draft or final, and by issue-date period with from and to.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Last issue date to include, YYYY-MM-DD | |
| from | No | First issue date to include, YYYY-MM-DD | |
| limit | No | Maximum notes listed, default and ceiling 2000 | |
| reason | No | Only notes with this reason | |
| status | No | Only drafts or only finalized notes | |
| recipient | No | Match the recipient, case-insensitive, a part of the name is enough |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a read-only operation via the verb 'List', but it does not explicitly state that there are no side effects or that it is safe to call without mutation risk. Annotations provide no help (all false), so the description carries the full burden. The absence of explicit behavioral disclosure is a minor gap for a list 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 concise sentences. The first states the output fields, and the second explains the filters. It is front-loaded with the core purpose and contains no filler or redundancy. Every word 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 list tool with no output schema, the description is complete: it states the returned fields and all filter capabilities. The 'limit' parameter is documented in the schema, and pagination is implicitly handled by the limit. No critical information is missing for an agent to invoke the 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?
Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that 'from' and 'to' form a date-period filter and that 'recipient' supports partial matching (though the schema already mentions partial match). It also summarizes the filter categories (recipient, reason, status, date) in a way that groups parameters logically, aiding an agent in selecting the right combination.
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 'List credit notes' and enumerates the fields returned (number/draft id, recipient, reason, status, issue date, total). It also distinguishes the tool from siblings like credit_note_get (single note) and credit_note_summary by specifying the listing and filtering nature. The verb-resource pairing is specific and unambiguous.
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 explains the available filters (recipient partial match, reason, status draft/final, date period via from/to), giving clear context for when to use this tool for listing. However, it does not explicitly mention when not to use it or name alternatives, though the title and sibling list make the intended use obvious.
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 the document: Markdown to paste into an email or ticket, or a self-contained printable HTML page with every style inline. Drafts render with a DRAFT banner so a half-finished credit cannot be sent by mistake. Writes nothing. Free; the free tier stamps a one-line footer.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The credit note number CN-2026-0001 or draft id CN-DRAFT-2026-0001 | |
| format | No | markdown (default) or html, a self-contained printable page |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states 'Writes nothing,' which contradicts the annotation readOnlyHint=false. Since readOnlyHint=false tells the agent this tool may modify state, the description directly conflicts with structured metadata, so this is an annotation 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?
The description is three tight sentences: the purpose is front-loaded, followed by the safety behavior for drafts and the free-tier footer limitation. Every sentence adds useful information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity two-parameter tool, the description covers formats, draft rendering behavior, side effects, and free-tier limitations. It does not specify the exact return payload or error cases, but these are not required by an output schema and the usage intent is clear.
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 fully documents both parameters. The description adds only format-choice context and does not contribute new parameter semantics beyond what the schema provides.
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 a specific action (render), a resource (credit note), and the two output formats (Markdown and printable HTML). It distinguishes this tool from CRUD siblings like credit_note_get and credit_note_list by focusing on document generation rather than data retrieval.
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 provides concrete use context: Markdown for pasting into emails/tickets and HTML for a self-contained printable page. However, it does not explicitly guide the agent toward alternatives for raw credit-note data, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
How much you have credited: totals per currency over finalized credit notes, broken down by reason and by month, in an optional issue-date period. Drafts count for nothing until they are finalized. Currencies are never added together.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Last issue date to include, YYYY-MM-DD. Default: today | |
| from | No | First issue date to include, YYYY-MM-DD. Default: the beginning |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With all annotation hints set to false, the description carries the burden of explaining how the tool behaves. It adds meaningful non-obvious details: drafts count for nothing until finalized, currencies are never added together, and the grouping is by reason and by month. It could more explicitly state whether the call is side-effect-free, but the summary semantics are clear enough for safe invocation.
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 carry all the essential information with no filler. The core aggregation is front-loaded, and the two critical caveats—draft neglect and currency separation—are concise and immediately useful.
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 tool with only two optional date parameters and no output schema, the description provides the key semantics: what is totaled, how it is grouped, which documents are included, and how currencies are handled. It stops short of describing the exact response shape, but an agent has enough context to call and interpret the result 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 input schema already documents both parameters fully, including YYYY-MM-DD format and defaults. The description's 'optional issue-date period' only restates what the schema provides and adds no new 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 clearly states the resource (credit notes) and the operation (totals per currency, broken down by reason and month, over an optional issue-date period). This aggregation focus distinguishes it from sibling tools like credit_note_list, credit_note_get, and credit_note_create. The title reinforces the same message without relying on the tool name alone.
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 makes the useful context explicit: only finalized credit notes count, drafts are excluded, and currencies are never combined. It also signals that the date window is optional. It does not explicitly name an alternative tool for viewing individual credit notes, but the aggregate-versus-list distinction is strongly implied by the summary phrasing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change a draft credit note while it is still a draft: recipient, reason, lines, currency, invoice reference, issue date or notes. Pass only what changes; new lines replace all old ones. A finalized note is immutable and is refused by name.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The draft id, e.g. CN-DRAFT-2026-0001 | |
| lines | No | The full new line set, replacing every existing line | |
| notes | No | New notes text, or null to remove the notes | |
| reason | No | ||
| currency | No | ISO code. Changing it reprices nothing: the stored minor units carry over, so only change it to fix a wrong currency | |
| recipient | No | ||
| issue_date | No | ||
| invoice_ref | No | New invoice reference, or null to detach the note from its invoice | |
| reason_detail | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds important behavior beyond the annotations: partial-update semantics ('Pass only what changes'), full replacement of lines, and the immutability of finalized notes. These are meaningful operational details not present in the sparse 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?
The description is tight and front-loaded: the action and scope appear in the first sentence, followed by two high-value behavioral notes. 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?
It covers the critical rules for correct use: draft-only, partial updates, line replacement, and refusal of finalized notes. The main gaps are the absence of return-value information (no output schema) and the undocumented reason_detail parameter, but these are minor against the overall clarity.
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 description lists most updatable fields and clarifies that only changed values need to be passed, which is valuable. However, schema description coverage is only 56%, and reason_detail is not described anywhere in the description or schema, while recipient and issue_date also lack semantic 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 opens with a specific verb and resource ('Change a draft credit note') and enumerates the mutable fields, making the tool's job unmistakable. The draft-only scope clearly separates it from credit_note_finalize, credit_note_create, and credit_note_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 explicitly states the tool applies only to drafts and that finalized notes are immutable and refused, giving a clear when/when-not signal. It does not name the alternative tool for finalized notes, but the sibling context makes the intended use obvious.
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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
credit_note_createcredit_note_deletecredit_note_finalizecredit_note_getcredit_note_listcredit_note_rendercredit_note_summarycredit_note_updatelicense_activatelicense_statusCredit notes against your invoices and purchase orders to suppliers, with VAT and A4 PDFs.
Issue a credit memo against an invoice or standalone, with per-line tax and totals.
Statements of account, aging buckets and dunning letters from your invoices.
Quotes and estimates: VAT line items, a validity date, an A4 PDF, accept makes an invoice.
Add one secure layer between your agents and this server.
