credit-memo

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

With no annotations, the description carries the full burden. It discloses that the tool returns a draft that can still be revised, and that credit_note_finalize 'burns the final CN number,' which is important lifecycle context. It doesn't mention authentication requirements, rate limits, or that duplicate_ok exists, but the draft/finalize distinction is the key behavioral trait.

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 core action and immediately followed by the key lifecycle detail (draft vs. finalize). Every phrase earns its place; no repetition or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 9 parameters, full schema coverage, and no output schema, the description covers the essential context: what it does, how it differs from finalize, and the draft return. It omits mention of optional parameters like issue_date, invoice_ref, and duplicate_ok, but the schema covers them fully, so the description is adequate though not exhaustive.

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 documents all parameters thoroughly. The description lists the key parameters (recipient, reason with examples, line items with quantity, unit price, tax rate, currency) but adds no semantic nuance beyond what's in the schema. Baseline 3 is appropriate 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 states a specific verb+resource ('Issue a credit note') and specifies it can be against an invoice or standalone. It connects to sibling tools by explicitly naming 'credit_note_finalize' and explaining the draft vs. final distinction, which is critical for distinguishing it from credit_note_update and credit_note_finalize.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use this tool (when you want to create a credit note, either standalone or tied to an invoice) and clarifies the draft state, implying the finalize step is separate. However, it doesn't explicitly say when NOT to use it (e.g., for modifying an existing note, use credit_note_update) beyond the finalize contrast.

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

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

With no annotations, the description carries the full burden and does well: it discloses the failure mode (finalized notes are refused, identified by name) and the reason. It omits irreversibility/recoverability, idempotency on a non-existent id, and any permission requirements, so it is strong but not complete.

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 action, and the second sentence justifies the draft-only restriction rather than repeating it. The rationale ('leave their copy pointing at nothing') earns its place by explaining the guard.

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 delete with no output schema and no annotations, the description covers purpose, applicable state, and failure behavior. It leaves success behavior and permission/irreversibility details unstated, minor gaps for this simple a 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% and the schema already documents the single 'id' parameter with a format example. The description's 'by its draft id' reinforces that the id must reference a draft, but adds little syntax or format detail beyond the schema, 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?

States a specific verb and resource (delete a draft credit note) and constrains scope to drafts, which cleanly separates it from siblings like credit_note_finalize, credit_note_update, and credit_note_get. An agent can identify the correct tool without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear when-to-use condition ('entered wrongly') and an explicit exclusion (a finalized note is refused), so the agent knows this is only for mistaken drafts. It does not name an alternative action for correcting a finalized note, which keeps it short of a 5.

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

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

With no annotations provided, the description carries the full behavioral burden and does most of it well: it discloses irreversibility (cannot be edited or deleted), the number-burning side effect, client visibility, and a tier-based quota. It does not cover failure modes (e.g., finalizing an already-finalized note) or auth requirements.

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 front-loaded sentences, each carrying distinct information: the action, the irreversible consequence, and the quota constraint. No boilerplate or restatement of the title.

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 state-transition tool with no annotations and no output schema, this covers the essential agent questions: what it does, what it locks out, and any limits. Missing only error/precondition edge cases and whether the response returns the assigned final number.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds semantics: it clarifies that the input is a draft and that a different final number (CN-YYYY-NNNN) is assigned as a side effect, removing any ambiguity between the draft id and the burned number.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a precise verb and state transition ('Finalize a draft') on a specific resource, and distinguishes it from siblings by describing the resulting frozen document ('cannot be edited or deleted, only rendered and listed'). An agent can separate this from credit_note_update or credit_note_delete without opening any 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 clearly states the precondition (the note must be a draft) and what the alternatives become afterwards (render, list) rather than edit/delete. It even surfaces the free-tier quota of 10 finalized notes as a practical usage constraint. It stops short of explicitly naming credit_note_update or credit_note_delete as the pre-finalization alternatives.

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

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

No annotations exist, so the description must carry the behavioral burden, and it does the key part by stating 'Reads only' (safe, non-mutating). It also describes the returned payload in detail, which substitutes for an absent output schema. It stops short of covering edge cases such as a missing/invalid id or draft-vs-finalized 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 sentence front-loaded with the action, followed by a colon-delimited list of return contents and a trailing routing note. No filler; every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read tool with no output schema and no annotations, the description supplies the safety profile (reads only), the return shape, and the id-sourcing path. Nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single 'id' parameter is fully documented there, including the CN-2026-0001 vs CN-DRAFT-2026-0001 formats. The description repeats that dual-id capability rather than adding new syntax or constraints, 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?

States a specific verb and resource ('Return one credit note') and enumerates exactly what the response contains (lines with quantity/unit price/tax, totals per tax rate, reason, credited invoice, notes). The lookup key is named (CN number or draft id), so it is clearly distinguishable from credit_note_list, credit_note_summary, and credit_note_render.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly declares 'Reads only' and routes the agent to credit_note_list when it needs to discover ids first. That is a clear usage context and names the alternative sibling, though it does not spell out when this tool is the wrong choice beyond needing an id.

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

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

No annotations are provided, so the description carries the full behavioral burden. A list call is implicitly read-only and safe, but the description doesn't disclose ordering, pagination behavior beyond the schema's limit, or permission requirements.

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 with no wasted words, front-loading first what is returned and then how to narrow it. Slightly list-like but well structured and appropriately sized.

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 and no annotations, the description usefully compensates by naming the returned fields and the filterable dimensions. It is close to complete for a filtered-list tool; only ordering and pagination semantics are 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 description coverage is 100%, so the schema already documents all six parameters with types, enums, and the "part of the name is enough" matching rule. The description largely restates these filters, adding no syntax detail 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?

Clear verb+resource ("List credit notes") and it enumerates the fields returned (number/draft id, recipient, reason, status, issue date, total), so the agent knows this is a multi-record query. It does not explicitly distinguish itself from close siblings like credit_note_get or credit_note_summary, leaving that distinction to inference.

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 details the filter dimensions (recipient, reason, status, issue-date range), which implies how the tool is used, but never states when to prefer it over credit_note_get or credit_note_summary. Usage is implied rather than contrasted with alternatives.

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

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

No annotations are provided, so the description carries the full burden, and it does real work: "Writes nothing" discloses the read-only safety profile, drafts render with a DRAFT banner (state-dependent output), and the free tier stamps a footer (quota-based output modification). It does not cover auth requirements, error behavior for an unknown id, or whether finalized notes render differently.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the core action and the two output forms, then the draft-banner safeguard, then the side-effect and cost notes. Every sentence adds a distinct fact; the short "Writes nothing." fragment earns its place as an explicit safety signal.

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 must convey what comes back, and it does at the artifact level (a Markdown document or a standalone HTML page). Draft state and free-tier footer behavior are covered; minor gaps remain around failure modes for invalid ids and whether the returned HTML includes the DRAFT banner.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it explains that html output is "self-contained" with "every style inline," which clarifies the enum choice itself rather than just restating it. It adds nothing further about the id format, which the schema already documents.

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 (render/turn into a document) and resource (credit note), and names both output artifacts: Markdown for pasting and a self-contained printable HTML page. This clearly separates it from the sibling mutation tools (create/update/finalize/delete) and from credit_note_get, which retrieves data rather than formatting it.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear context for choosing between the two modes ("Markdown to paste into an email or ticket, or a self-contained printable HTML page"), and notes the draft-banner safeguard. It never names a sibling or states when-not to use this tool (e.g., use credit_note_get for raw 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.

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

With no annotations, the description carries the full behavioral burden, and it does disclose two genuinely useful traits: drafts are excluded until finalized, and currencies are never summed together (no cross-currency total). It stops short of covering auth needs, rate limits, or empty-result behavior, so it is good but not complete.

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 core aggregation semantics are front-loaded in the first sentence, followed by exactly two short clarifications on draft handling and currency separation. No sentence is filler and nothing important is buried.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter aggregate tool with no output schema, the description usefully describes the shape of the result (totals per currency, by reason, by month) and the inclusion rule. It is nearly complete; only edge cases like no-matching-notes behavior are unaddressed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so from/to and their formats are fully documented in the schema. The description adds only that the period is optional and keyed to issue date, which is marginal over the schema's own wording. 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 names a specific resource (finalized credit notes) and a specific operation (aggregate totals per currency, split by reason and month). It is trivially distinguishable from siblings like credit_note_list or credit_note_get, which deal with individual notes rather than aggregates.

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 implied — this is the reporting/roll-up tool rather than a CRUD tool — but no sibling is named as an alternative and there are no explicit when/when-not statements. The finalized-only scoping hints at the context, but an agent must infer that credit_note_list is the tool for viewing individual notes.

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

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

With no annotations, the description carries the full burden, and it delivers the non-obvious traits: draft-only precondition, immutability of finalized notes with refusal behavior, partial-update semantics ('Pass only what changes'), and destructive replacement of lines. It omits permissions/auth requirements and any hint about the error shape when a finalized note is refused.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, all load-bearing: what can change, how to send changes, and the guardrail. The mutability precondition is front-loaded and nothing is repeated from the schema verbatim.

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 mutation tool with no annotations and no output schema, the description covers the behavioral essentials (draft scope, partial update, line replacement, finalized refusal). The unexplained reason_detail parameter and the unnamed sibling for finalization are the only meaningful omissions.

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 only 56%, and the description compensates by naming the mutable fields that lack schema descriptions (recipient, reason, issue date) and by clarifying the partial-update contract. It also reinforces the replace-all-lines rule. It does not explain reason_detail or list the reason enum values, so some gap remains.

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 (change a draft credit note) and enumerates exactly which fields are mutable: recipient, reason, lines, currency, invoice reference, issue date, notes. The 'while it is still a draft' clause cleanly separates it from credit_note_finalize and credit_note_create in the sibling set.

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 use condition (only while still a draft) and an explicit exclusion ('A finalized note is immutable and is refused by name'), which routes the agent away from updating finalized notes. It stops short of naming the alternative tool (e.g. credit_note_finalize) for that case, leaving the next step to inference.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It explicitly states that data under the token stays and that a wrong or expired key changes nothing, which is valuable non-destructive and failure-mode context for an activation mutation.

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 front-load the action and key requirement, then add side-effect guarantees and a pointer to verification. No wasted words or repetition beyond the schema format.

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 activation tool with no output schema and no annotations, the description covers the action, key eligibility, non-destructive behavior, failure mode, and how to confirm success. It could add explicit return-value expectations, but license_status confirms it largely covers that 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?

The schema already fully documents the key parameter, so the baseline is 3. The description adds meaningful semantics by explaining the key must be issued at checkout for this server or bundle and that invalid keys are no-ops, going beyond the schema's simple format description.

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 action, 'Turn Pro on for this connection,' with a clear resource (license/Pro status) and key format. It also distinguishes itself from the sibling license_status by focusing on activation rather than checking status.

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 conveys when to use the tool: when activating Pro with a checkout-issued key for this server or bundle. It also references license_status as the follow-up confirmation step, though it stops short of explicitly saying 'use license_status instead to check current status.'

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It explicitly states 'No arguments, nothing changes,' indicating a read-only, side-effect-free operation. It does not detail error handling or authentication requirements, which are minor omissions for a simple status check, but the core behavioral trait (no mutation) is clearly communicated.

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, tightly packed with all essential information. It is front-loaded with the primary action and output, then adds the use case and side-effect note. Every sentence earns its place with no redundancy or fluff.

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 no input parameters and no output schema, the description fully covers what an agent needs: the return format (JSON with product, tier, reason, checkout URL), the trigger condition, and the lack of side effects. Nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, and the description confirms 'No arguments.' Per the scoring rules, 0 parameters earns a baseline of 4. The description adds no parameter-specific meaning because none exist, and it correctly reiterates the absence of arguments, aligning with the empty 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 states a specific verb and resource: 'Report this endpoint's licence state for your token as JSON'. It explicitly enumerates the returned fields (product, tier, reason, checkout URL), making the tool's purpose unambiguous. It also distinguishes itself from sibling tools like license_activate by focusing on status reporting rather than activation.

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 trigger for use: 'Call it to explain a free-tier refusal.' This tells the agent when to invoke this tool. It does not explicitly discuss alternatives or exclusions, but the purpose is distinct enough from siblings that the guidance is adequate; it could be improved by noting it is the only read-only license info tool, though that is implied.

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