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 provided, the description carries the full behavioral burden. It discloses that verification happens offline against a built-in public key, that the key is persisted to the config file, and that invalid keys are refused and left unsaved. This is substantial transparency for an activation tool, though it could mention overwriting an existing key or the exact return 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?

The description is two sentences with no filler. The first sentence front-loads the main action, source, verification method, and persistence. The second sentence efficiently covers error handling and points to the related read-back tool. Every clause adds value.

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

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

Given a single-parameter tool with no output schema and no annotations, the description covers activation behavior, verification mechanism, persistence, error outcomes, and how to read the result later. The only minor gap is an explicit statement of what the function returns upon success or failure, but the phrase 'refused, unsaved' implies a feedback mechanism. Overall, it is sufficiently complete 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 at 100% coverage, so the baseline is 3. The description adds meaningful semantics by giving the concrete key format ('MCPL1.xxx.yyy'), confirming the key comes from the checkout page, and explaining that malformed or expired keys will be rejected. This goes beyond the schema's one-line 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 states a specific action ('Activate a Pro key'), the exact key format ('MCPL1.xxx.yyy'), the source ('from checkout'), and the core mechanism ('verified offline against a built-in public key'). It also differentiates itself from the sibling license_status by noting that license_status reads the activation back, so there is no ambiguity about which tool does what.

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

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

The description gives clear context: use this when you have a Pro key from checkout that needs to be activated. It also points to license_status as the read-back tool, which implies when to use a related sibling. It does not explicitly spell out 'do not use for checking status' or list other alternatives, but the context is strong enough to avoid misuse.

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?

Annotations are absent, so the description carries the full burden of behavioral disclosure. It discloses that the call is local ('no network') and argument-free, and it mentions a specific explanatory behavior. The word 'Report' implies read-only, though it does not explicitly state non-destructive or permission requirements; this is adequate for a status command.

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 filler. The first sentence lists the output fields; the second adds constraints and the sibling pointer. Every clause contributes meaningful 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 zero-parameter status tool with no output schema, the description lists the expected output fields, behavioral constraints, and the relevant alternative tool. Nothing an agent needs to call it correctly is missing.

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

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

The schema has zero parameters and the description reinforces this with 'No arguments'. It adds value by listing the reported fields, helping an agent understand what the empty input will yield. The baseline for zero-parameter tools is high, and the description meets 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 states a specific verb ('Report'), a clear resource ('this server's licence state'), and enumerates the exact fields returned. It also names the sibling 'license_activate' as the tool that does something different, so an agent can distinguish them immediately.

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 explicit usage constraints: no arguments, no network, and explains a free-tier refusal. It also directs the agent to license_activate when the task is to install a key, serving as an explicit pointer to the relevant alternative.

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