Kema Invoice

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

The annotation already indicates destructiveHint=true and readOnlyHint=false. The description adds that it changes the quote's state to Accepted, which aligns with the destructive nature. This transparency is sufficient and consistent.

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 with no redundant information. It directly states the action and the recommended follow-up, making it highly efficient and well-structured.

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 presence of an output schema and the simplicity of the operation, the description provides all necessary context for an agent to understand when and how to use the tool. It also names the related sibling tool for the next step, completing the workflow context.

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 single required parameter quote_id is fully described in the schema as 'The Sent quote UUID.' No additional clarification is needed, and the parameter is straightforward and unambiguous.

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 tool's function: marking a Sent quote as Accepted. It also distinguishes it from sibling tools by referencing the follow-up convert_quote_to_invoice, making its purpose 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?

It explicitly instructs when to use this tool (after a quote is sent and client accepts) and provides a direct next step (convert_quote_to_invoice). This gives clear guidance and routes the agent to the correct sibling tool.

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?

The description discloses that totals are recalculated automatically, adding some behavioral context beyond the annotations. It does not contradict the readOnlyHint=false or destructiveHint=false annotations, but could mention rejection behavior for non-Draft invoices.

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 tool description is concise and front-loaded with the action and target. Parameter descriptions are informative without being bloated or redundant.

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

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

The description and parameter metadata cover the operation well for a simple add-item workflow, including the Draft-invoice constraint and automatic recalculation. It does not explain error conditions, but an output schema exists so return details are not required.

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?

Every parameter has a meaningful description, including conditional requirements (e.g., quantity and unit_price required for 'item' lines), enum semantics for line_type, and explicit guidance on tax_rate. This adds substantial clarity beyond the raw 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?

Clearly states the action ('Add a line item') and the target resource ('a Draft invoice'), distinguishing it from sibling tools like update_invoice_item, delete_invoice_item, and reorder_invoice_items.

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 the tool is only for Draft invoices and mentions automatic total recalculation, but it does not explicitly contrast with alternative tools or 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.

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

The description discloses the main side effects (updates advances_total and amount_due) and reversibility, which is helpful given the sparse annotations. It does not mention edge cases like duplicate applications or invalid invoice state, but the core behavior is transparent enough for correct 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?

The description is concise, using three short sentences that cover purpose, effect, and reversibility without redundant wording. It is well-structured 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?

The description covers the essential invocation context: prerequisites (DRAFT, PAID, same client/matter), the effect on invoice totals, and the reversal path. With input schema coverage at 100% and an output schema present, no critical information is missing for correct use.

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?

Both parameters are fully described in the schema: invoice_id is clearly identified as the Draft final invoice UUID, and provision_ids is described as Paid provision UUIDs with a direct pointer to list_available_provisions. No additional parameter explanation is needed.

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 (deduct provisions), the target (DRAFT final invoice), the constraints (PAID provisions, same client/matter), and the effect (updates advances_total and amount_due). It also distinguishes itself from the sibling remove_provision_from_invoice by explicitly naming it as the reversal operation.

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 usage conditions: apply only PAID provisions to a DRAFT final invoice of the same client/matter. It also references list_available_provisions as the source for provision IDs and notes the operation is reversible via remove_provision_from_invoice, giving the agent sufficient guidance on when and how to use it.

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 already mark this as destructive, but the description adds critical behavioral context: the cancellation is irreversible, only draft invoices are eligible, issued documents are fiscal records, and calling without confirm:true only returns a preview. This meaningfully extends the structured annotation data and prevents misuse.

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 concise, front-loads the core purpose and irreversibility, and then covers exclusions and invocation requirements in a few tight sentences. There is no filler or repetition; 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 destructive tool with an output schema and annotations, the description covers all necessary behavioral context: scope, irreversibility, when not to use it, and the confirm flag semantics. No important operational detail is missing for an agent to decide and invoke correctly.

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

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

Schema description coverage is 100%, so the schema already documents invoice_id, reason, and confirm. The description reinforces the confirm parameter's preview/act behavior but does not add significant information beyond what the schema provides, making the baseline score of 3 appropriate.

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

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

The description clearly identifies the action ('Cancel'), the target resource ('a DRAFT invoice'), and the resulting status ('Cancelled'). It distinguishes itself from create_credit_note by explicitly limiting cancellation to draft invoices and by stating that issued documents cannot be cancelled through this tool.

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

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

The description provides explicit when-to-use guidance: use it only for draft invoices. It names the alternative create_credit_note for issued documents and explains the confirm:true preview/action pattern, leaving no ambiguity about invocation behavior.

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?

The description adds meaningful behavioral context beyond the annotations: it performs an external provider refresh, reconciles into the database, is 'internal plumbing,' and normally completes automatically after issue_invoice. It also warns against proactive use and user-facing mention, which is critical behavioral guidance not present in the annotations.

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

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

The description is front-loaded with 'Maintenance tool' and immediately states the purpose. Every sentence earns its place: purpose, internal plumbing context, explicit prohibitions, and exact usage conditions. There is no fluff or redundancy.

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

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

Given the single well-documented parameter, existing output schema, and annotations, the description is complete. It covers what the tool does, when to use it, when not to use it, and the context of normal operation (after issue_invoice), leaving no required guidance 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 input schema already provides 100% coverage with invoice_id described as 'The issued invoice UUID.' The description does not add additional parameter-level detail beyond contextualizing it as the issued document whose certification is refreshed. This meets the baseline for full schema coverage but adds no extra 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?

The description states a specific verb and resource: 'refresh an issued document's fiscal certification state from the certification provider and reconcile it into the database.' It clearly labels the tool as a maintenance tool and distinguishes it from normal business operations like issue_invoice.

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 guidance is explicit and thorough: 'NEVER call this proactively, and never bring certification up with the user. Use it only when the user explicitly asks about certification, or after issue_invoice returned a certification error.' It names the related sibling (issue_invoice) and gives precise conditions for invocation.

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?

The description discloses the write effect of creating an invoice, the preview mode when confirm is false, and the lifecycle context. This goes well beyond the minimal annotations and provides clear expectations.

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 concise and well-structured, with three short sentences that front-load the core purpose and then add necessary usage nuance. No unnecessary words or redundancy.

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

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

Given the simple two-parameter schema and the presence of an output schema, the description covers the necessary context: source state, conversion behavior, preview/apply distinction, and the follow-up lifecycle step.

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 describes both parameters well, including the Accepted quote UUID and the confirm behavior. The description largely repeats these details rather than adding new parameter-specific meaning.

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 tool creates a new Draft invoice from an Accepted quote, with line items copied and source_quote_id set for traceability. This distinguishes it from related tools like create_invoice or accept_quote.

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 specifies the prerequisite of an Accepted quote and explains the confirm:true behavior for applying vs previewing. It also points to issue_invoice for the next lifecycle step, though it does not explicitly contrast with create_invoice or reject_quote.

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?

Description adds meaningful behavioral context by clarifying that a VAT/tax id is not needed at creation time but will be required later for B2B billing. This supplements the annotations and does not contradict them.

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 concise sentences with the primary purpose front-loaded. There is no redundant information or unnecessary detail.

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 simple flat parameter structure and presence of an output schema, the description provides sufficient context for correct usage, including the notable tax_id timing caveat.

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

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

The schema already describes all 10 parameters with 100% coverage. The description adds extra meaning to the tax_id parameter by explaining that it is required later for B2B billing, which is not evident from the schema alone.

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?

Clearly states the action ('create') and the resource ('customer company for the tenant'), distinguishing it from sibling tools like update_company, get_company, list_companies, and delete_company.

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 verb 'create' implies when to use the tool, and the note about tax_id being required later for B2B billing provides useful context. However, it does not explicitly mention alternatives or 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.

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

The description discloses that the credit note is IMMUTABLE and IRREVERSIBLE, and that it is LEGALLY BINDING. This goes beyond the destructiveHint annotation by adding specific legal and fiscal implications, fully informing the agent of consequences.

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

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

The description is compact yet comprehensive, using clear formatting and capitalization for key warnings. Every sentence serves a purpose—purpose, legality, immutability, and confirmation requirement—without redundancy.

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

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

Given the output schema exists, the description correctly avoids describing return values. It covers the operational context (preview vs. execute), eligibility (Sent/Paid), and legal consequences, making the tool fully understandable in isolation.

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?

Both parameters are described with meaningful detail: invoice_id specifies 'Sent/Paid invoice' (eligible states), and confirm explains that true triggers creation, while false/omitted yields preview. This adds actionable semantics beyond the raw 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 clearly states the action: cancel a Sent or Paid invoice by issuing a credit note. It specifies the target resource (invoice) and the mechanism (credit note/avoir), leaving no ambiguity about the tool's purpose.

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 instructs that explicit user approval is required before calling with confirm:true, and explains that without confirm it returns a preview. This gives clear when-to-use and when-not-to-use guidance, including the legal caveat.

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 minimal (readOnlyHint=false, destructiveHint=false), so the description carries the full burden. It discloses critical behavior: creation means issuance, drafts are opt-in, VAT is server-computed, and the fiscal scenario/client snapshot is frozen at creation with legal_name used for printing.

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 front-loaded with the core purpose and workflow, then adds dense but relevant caveats about drafts, VAT, and snapshot freezing. Every sentence earns its place with 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?

Given the 7-parameter schema, output schema, and many sibling tools, the description covers what an agent needs to call the tool correctly: the approval flow, draft condition, VAT rules, and snapshot semantics. Remaining details like date format and enums are already in the schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema, especially around tax_rate ('never ask the user for a VAT rate') and the legal_name snapshot behavior that affects what appears on the invoice.

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 ('create an invoice for a company, with line items') and immediately clarifies the key product nuance: creating means issuing, with a draft only when explicitly requested. This distinguishes it from sibling tools like issue_invoice and create_quote.

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

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

It gives explicit workflow guidance: show the user a summary after the call and call issue_invoice with confirm:true on approval, while keeping a draft only when the user wants to review/edit first. It also tells the agent what not to do: never ask for a VAT rate.

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 only declare readOnlyHint=false and destructiveHint=false. The description adds meaningful behavioral context beyond those: VAT is computed server-side, provisions use their own number series, and once paid they become a client credit. This gives the agent insight into side effects and constraints not covered by 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 a single compact paragraph with no redundancy. Each sentence adds a distinct piece of information: purpose, state, VAT rule, and number series. It is front-loaded with the core action and efficiently packs constraints without verbosity.

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 complexity (8 params, 4 required, nested items), the description covers the full workflow context: draft creation, VAT handling, matter attachment, and relationship to sibling tools (send_provision, list_companies). Since an output schema exists, return values need not be explained. The description is complete for an agent to invoke 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 covers all parameters with descriptions, but the description adds extra semantics: tax_rate is explicitly flagged as 'OMIT - do NOT ask' with conditions for setting, and matter_id is noted as 'omit for a standalone retainer, normal case.' These go beyond the schema and improve parameter understanding.

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?

Clearly states the tool creates a provision document in Draft status for a company, optionally attached to a matter, and explicitly distinguishes it from sending (use send_provision). The verb 'Create' and resource 'provision' are specific, and the mention of 'NOT issued or certified' removes ambiguity.

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?

Provides explicit guidance on when NOT to use this tool (for issuing) and directs to send_provision. It also instructs the agent to never ask for a VAT rate, explaining when to set tax_rate (only when user explicitly states). These are clear, actionable instructions with no ambiguity.

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?

It discloses useful server-side defaults for issue/due/valid dates and the non-certification nature of quotes. However, it does not describe side effects, validation behavior, or the fact that the created quote remains a draft (beyond the title), and it contains an inaccurate 'requires a matter id' claim.

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

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

The description is short, front-loaded, and contains no redundant wording. It conveys the most important facts in two sentences.

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 output schema exists, return values need not be explained, but the description omits guidance on related workflow steps (e.g., send/accept/convert) and contains a requirement contradiction with the schema. It is adequate but not 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?

The schema already describes all parameters in detail, and the description adds only default-date behavior. It incorrectly claims a matter id is required when the schema marks matter_id as optional, which undermines parameter understanding.

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 the core action clearly: 'Create a Draft quote (devis) for a company.' It also distinguishes quotes from fiscal documents, making the tool's purpose easy to understand.

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

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

It gives some guidance by noting the draft state and that quotes are not fiscal documents, but it does not explicitly contrast this with related sibling tools such as send_quote or convert_quote_to_invoice, nor does it state when to prefer this tool.

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 already declare destructiveHint=true and readOnlyHint=false. The description adds valuable behavior: it's a soft-delete (reversible), it has a two-phase preview/confirm flow, and it is blocked under certain conditions. This significantly exceeds what annotations alone 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?

Two sentences, front-loaded with the core action, then the blocking condition and confirm behavior. Zero filler and each 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?

With an output schema present, return format is covered. The description covers the essential behavioral details: soft-delete, blocking condition, and the preview/confirm mechanism. 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?

Schema description coverage is 100%, and both parameters already have clear descriptions (company_id as UUID, confirm with its preview/delete semantics). The tool description adds no new parameter meaning beyond restating the confirm behavior, so it stays at the baseline for full schema coverage.

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 the specific verb 'soft-delete' and identifies the resource as a 'client company', which immediately distinguishes it from other delete tools like delete_invoice. It also states the blocking condition (contacts linked), adding precision beyond a generic '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?

The description explains the prerequisite condition: deletion is blocked when contacts are still linked. This gives an agent guidance on when the operation will fail, though it doesn't explicitly name alternatives or contrast with other delete tools. The confirm:true requirement is also a clear usage guideline.

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?

Beyond the destructiveHint annotation, the description reveals that the operation is 'Irreversible from the user's view' and details the confirmation step, providing additional transparency about the side effects and safety mechanism.

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

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

The description is compact, using two sentences to convey the primary action, the specific condition (Draft), and the confirm behavior. It is well-structured and free of unnecessary detail.

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?

The description gives sufficient context for the operation, including the preview behavior and irreversibility. It does not mention what happens for non-Draft invoices, but that is not essential for completing the task, and the output schema provides return information.

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?

Both parameters (invoice_id and confirm) have complete descriptions in the schema, covering their meanings and usage. The tool description does not add extra semantic detail beyond what is already provided in the schema, 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 it soft-deletes a Draft invoice, specifying the exact verb and resource. This distinguishes it from sibling tools like cancel_invoice or delete_invoice_item, and the condition 'Draft' further narrows its scope.

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 mentions the condition 'Draft' and explains the preview vs. actual delete behavior via the confirm flag. While it doesn't directly compare to alternatives like cancel_invoice, the condition and behavior are sufficient for an agent to decide when to use this tool.

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?

The destructive nature is disclosed through annotations and reinforced by the description, which also clarifies that only the billing profile is affected and the company remains intact. The confirm flag behavior is transparent.

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 with no superfluous content. The essential information about destructive scope and confirmation requirement is delivered efficiently.

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

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

For a destructive tool with a confirmation parameter, the description covers the action, the scope limitation, and the exact usage of the confirm flag. It is self-contained and sufficient for an agent to invoke it correctly.

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

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

Both parameters are fully described in the schema, and the description adds crucial behavioral meaning to confirm by explaining the actual-delete vs preview distinction. This goes beyond the schema's basic 'Must be true to delete' explanation.

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 tool removes a company's invoicing defaults and explicitly notes the company itself is untouched, distinguishing it from delete_company. The verb and resource are 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 explicitly instructs to call with confirm:true to actually delete and without it to preview, providing direct usage guidance for the key parameter. This leaves no ambiguity about how to invoke the destructive action safely.

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?

Goes beyond the destructiveHint annotation by explaining that totals are recalculated automatically, that item IDs come from get_invoice/add_invoice_item, and that confirm:true is required for actual deletion while omission returns a preview.

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

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

The description is compact and logically ordered: action, automatic side effect, ID source, and confirmation requirement. No redundant or vague wording.

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?

Covers the key workflow aspects including deletion guard and preview return, but does not explicitly state the success return shape or error scenarios, though the preview mention gives partial output context.

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?

Both parameters are fully described in the schema, and the description adds practical context for item_id sourcing and the boolean confirm semantics (delete vs preview).

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?

Clearly states the specific action 'Remove a line item from a Draft invoice', identifies the source of item IDs, and explains the confirm/preview behavior, which distinguishes it from related invoice/item tools.

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

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

Provides clear conditions for use (Draft invoices only) and explains the confirm flag behavior, but does not explicitly contrast with sibling tools such as update_invoice_item or delete_invoice.

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?

The description aligns with the readOnlyHint annotation ('Fetch' implies no side effects) and openWorldHint=false. It discloses the scope of returned data, and no contradictions exist.

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

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

The description is a single concise sentence, front-loaded with the action and resource, and includes necessary details without 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?

The output schema exists, so return values are defined externally. The description lists key fields included, and for a read-only operation with a closed world hint, no additional context (like error cases or permissions) is necessary.

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 single parameter company_id has a helpful description including format (UUID) and a cross-reference to list_companies for resolution. This fully covers the required parameter with additional context.

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 tool fetches one customer company, with a specific verb and resource. It lists the included data fields (legal identity, VAT/SIREN, etc.), distinguishing it from list_companies (multiple) and update_company (modify).

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

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

The description implies usage for retrieving a single company by ID, and the parameter hint 'use list_companies to resolve' gives guidance. However, it does not explicitly contrast with list_companies or other retrieval tools, leaving some room for ambiguity in a large sibling set.

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 already declare readOnlyHint=true. The description adds a useful behavioral detail: it returns a null-shaped error if the invoice is not visible to the caller, and it specifies the returned content (line items, client, totals). This goes beyond annotations without contradicting them.

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 sentence that is front-loaded with the core action and scope, with no wasted words. 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 simple get-by-id operation with an output schema present, the description covers the essential return content and error behavior. 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?

Schema description coverage is 100% — the only parameter (invoice_id) is fully documented in the schema with its type and description. The tool description adds no additional meaning about the parameter, so baseline 3 applies.

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

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

The description states a specific verb (Fetch), resource (a single invoice by id), and scope (including line items, client, and totals). It clearly distinguishes from siblings like list_invoices (plural) and get_invoice_pdf (PDF output).

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

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

The description implies usage when you have an invoice id and want the full invoice object, but it does not explicitly mention alternatives or when not to use it. No sibling routing or exclusionary context is provided.

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?

Beyond the readOnlyHint annotation, the description discloses that profiles are created lazily and returns {profile: null} when none exists. This adds behavioral context that is not present in the annotations or schema, helping the agent anticipate edge cases without contradicting the annotation.

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

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

The description is a single, focused sentence that front-loads the core purpose and then adds the null-return nuance in a second short sentence. There is no redundant information, and every phrase contributes to understanding the tool's behavior.

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 only one parameter, a clear output schema, and the description covering the null case and lazy creation, the tool is fully specified for an agent to call correctly. The description adds essential context (lazy creation) that is not inferable from the schema or annotations, making it 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?

The schema provides 100% coverage for company_id, including a description referencing list_companies for resolution. The description does not add any extra parameter-specific semantics beyond what the schema already documents, so a 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 tool retrieves per-company invoicing defaults (payment terms, delivery channel, custom invoice prefix), which is specific and distinct from sibling tools like get_company or get_invoice. It also clarifies the return value when no profile exists, removing ambiguity about behavior.

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

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

The description implies usage for reading invoicing defaults per company but does not explicitly contrast with alternatives such as upsert_invoice_client_profile or delete_invoice_client_profile. While the context suggests it is the read-only counterpart, the description lacks explicit when-to-use or when-not-to-use guidance.

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?

The readOnlyHint annotation already signals no mutation, and the description adds meaningful behavioral details: server-side rendering, workspace branding, Factur-X embedding for certified invoices, draft behavior, and a 1-hour expiry. No side effects or auth details are mentioned, but the provided information is sufficient.

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 concise, information-dense sentences with no redundant content. Each sentence adds a distinct piece of value: the core return value, behavior by invoice type, and draft handling.

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?

Covers key edge cases (imported vs. issued, drafts, certification) and describes the output nature. Since an output schema is present, the lack of explicit return-value details is acceptable, though error conditions are not mentioned.

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 only parameter invoice_id is documented in the schema, and the description adds context about invoice visibility and applicability to drafts and issued documents. This makes the parameter's role clear beyond the minimal schema 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?

Clearly states it returns a temporary signed download URL for an invoice PDF, with a specific action and resource. It distinguishes itself from get_invoice by focusing on the PDF artifact rather than invoice data.

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?

Provides situational guidance: works for any visible document, explains differing behavior for imported vs. issued invoices, and clarifies how drafts are handled. It does not explicitly compare to sibling get_invoice, but the context makes the appropriate use case clear.

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?

The description discloses the key behavior of returning null for both fields when the invoice is not part of a chain, which goes beyond the readOnlyHint annotation. It does not mention error handling or edge cases, but for a simple read operation the null-return behavior is sufficient transparency.

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

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

The description is a single well-structured sentence with no redundant words. It efficiently conveys the purpose and output conditions without unnecessary detail.

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?

The description explains the output semantics (original and replacement links, with null behavior) but does not mention the output schema structure or error cases. Since the tool has an output schema (per context signals) that is not shown, the description leaves a small gap about the exact return format. Overall, it is mostly complete for a simple read-only 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?

The single parameter invoice_id has a clear description ('The invoice UUID to inspect') and a precise format with a regex pattern. This fully explains the parameter's meaning and constraints, achieving 100% schema description coverage.

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 tool's function: to return the rectification chain for a given invoice, explicitly defining the original and replacement links. This is unambiguous and distinct from sibling tools like rectify_invoice (which modifies) and get_invoice (which retrieves invoice details).

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 what the tool returns and the conditions under which outputs are null, but it does not explicitly state when to use this tool versus alternatives. It implies usage when needing to inspect rectification links, but lacks direct guidance on when not to use it or which sibling would be more appropriate.

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?

The readOnlyHint annotation already indicates the operation is safe, so the bar is lower. The description adds useful behavioral details beyond the annotation, such as the period applying to payment dates for collected figures and point-in-time evaluation for outstanding/overdue, and the default to the current month. No contradictions with 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 compact, forming two sentences with a colon-delimited list of metrics. It is efficient and avoids fluff, though the first sentence is dense with multiple comma-separated items, making it slightly harder to parse quickly than a more structured list.

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 an output schema present, the description does not need to detail return values. It covers the primary context: aggregate figures, the metrics included, and the default time period. It does not mention potential edge cases (e.g., empty periods, timezone handling), but these are not critical for basic usage.

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 covers both parameters with descriptions (period start/end, inclusive, defaults). The tool description adds context about how these parameters affect the different metrics (e.g., collected by payment date, outstanding point-in-time), which slightly enriches the parameter semantics beyond the schema.

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

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

The description clearly states the tool aggregates revenue figures and enumerates the specific metrics (collected, outstanding, overdue, documents issued, draft count, net credit-note effect). This distinguishes it from sibling tools like list_invoices or get_invoice, which return raw records rather than summaries.

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 the tool (for summary-level revenue metrics over a period) but does not explicitly mention alternatives or when not to use it. The context is clear enough from the aggregate nature and the default period, but it lacks explicit disambiguation from similar reporting tools.

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?

The readOnlyHint annotation already signals no side effects, and the description reinforces this by repeating 'read-only' and adding that changes must happen in the app. No rate limits or auth details are given, but the annotation lowers the bar for additional behavioral disclosure.

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 with no redundancy. It front-loads the read-only nature and then lists the included setting categories, providing maximum information in minimal space.

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?

The description is complete enough for a zero-parameter read-only tool: it names the resource (tenant invoicing settings) and the main content areas. It does not detail the output schema, but the absence of parameters and the clear snapshot framing make the behavior predictable.

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, so no parameter-level documentation is needed. The baseline for zero-parameter tools is 4, and the description gives sufficient context about what the returned settings snapshot will contain.

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 tool's purpose as retrieving a read-only snapshot of tenant invoicing settings and enumerates the specific categories included. The title further reinforces this by naming the operation and its read-only nature.

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

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

The description implies when to use it—when a read-only view of settings is needed—and explicitly notes that settings can only be changed from the app, which directs users away from attempting modifications via the API. It does not explicitly contrast with sibling tools, but the unique scope makes misuse unlikely.

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 indicate this is not read-only and not destructive. The description adds useful context about preserving the invoice number and excluding line items, though it does not detail write-specific side effects beyond the import intent.

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, front-loads the core purpose, and immediately communicates key exclusions and the alternative tool. No unnecessary detail.

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 parameter schema fully documents each field and the description clarifies the migration use case and boundary with create_invoice, the tool is well contextualized. An output schema exists, so return-value details are not required.

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?

All 10 parameters are described in the schema with defaults, enums, and helpful hints such as 'use list_companies to resolve'. The tool description reinforces the overall purpose but adds little beyond the already high schema coverage.

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 ('Import'), a clear resource ('historical/external invoice'), and distinguishes it from create_invoice. It also clarifies the preservation of the external invoice number and the absence of line items.

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 states when to use the tool ('for migrating past invoices issued outside Kema Invoice') and when not to use it ('NOT for creating new invoices'), including the alternative tool name.

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 already mark destructiveHint=true. The description adds crucial context beyond annotations: irreversibility under French law, status transition to Sent/Créée, fiscal certification being internal plumbing, and the mandated user communication pattern (what to tell the user, what never to mention). This is high-value behavioral disclosure.

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

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

Front-loaded with the core purpose and legal consequence, then the must-have workflow. Long sentences carry a lot, but every clause earns its place. Minor redundancy: 'IRREVERSIBLE' repeats destructiveHint, but it's substantive enough.

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?

Complete for a destructive legal-action tool. Covers prerequisites (Draft state, approval), the confirm gate, side effects (status, certification), and post-call user communication strategy. Output schema exists, so return details need not be repeated. Nothing an agent needs to avoid a critical mistake 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 coverage is 100% and descriptions for both parameters are exact. The description adds a critical semantic layer—the confirm:true vs preview distinction is explained in the tool description, not just the schema, clarifying the safety-critical usage. Full value beyond 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?

States the specific verb ('Issue'), the resource ('a Draft invoice'), and the legal effect with exact product terminology ('Créer la facture'), distinguishing it from sibling tools like create_invoice, cancel_invoice, or create_credit_note. Clear differentiation.

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?

Explicit when-to-use guidance: call after showing summary and getting explicit approval; use confirm:true to issue, omit for preview; maps directly to the schema. Though it doesn't enumerate alternatives, the workflow is precise. Could name siblings, but the condition is unambiguous.

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?

The readOnlyHint annotation already covers the read-only nature, and the description's use of 'List' aligns with that. The description goes beyond annotations by explaining what 'available' means (not applied to final invoices), adding domain context. However, it does not explicitly state side-effect-free behavior, but that is implied and consistent with the annotation.

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 concise yet informative, explaining both the resource and the parameter behavior in a few sentences. No redundant or vague wording; all sentences add 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 the single optional parameter and the existence of an output schema (not shown but implied), the description provides sufficient context to call the tool correctly. It covers the default case, the filter case, and the intended usage sequence. No missing critical information for a simple list operation.

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

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

The schema description covers matter_id fully, explaining its purpose (restrict to a matter) and the default when omitted. The description reinforces this by stating the normal case. 100% parameter coverage with meaningful explanation.

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 specific action ('List') and the resource ('paid provisions' not yet applied to final invoices), and clarifies the domain meaning ('deductible client credit'). It also distinguishes the tool from siblings like apply_provisions_to_invoice by specifying the filter behavior.

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 explains the single optional parameter (matter_id) and its default behavior (standalone retainers, the normal case). It also directly advises to use this tool before apply_provisions_to_invoice, giving clear when-to-use guidance.

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?

The annotation readOnlyHint=true already establishes that this is a read-only operation. The description adds context about the scope ('authenticated tenant's client companies'), which is useful. No side effects or auth details are needed beyond what the annotation provides.

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 extremely concise and well-structured. Two sentences cover purpose and usage without any unnecessary words 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?

The description is complete for an agent to understand when and why to call this tool. It includes the output fields and the practical use case. Since an output schema exists, return value details are not required in the description.

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 no parameters, so the baseline is 4. The description does not need to elaborate on parameters, and the mention of the output fields (name, email, VAT/tax id, country) indirectly clarifies what the list will contain, which is sufficient.

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

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

The description clearly states the action ('List'), the resource ('client companies'), and includes the relevant fields. It also distinguishes itself from sibling tools like get_company by indicating its purpose of resolving a company ID before other lookups.

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 a specific use case ('resolve a company id before other lookups'), which gives clear guidance on when to use it. It does not explicitly mention alternatives, but the primary context is well-communicated.

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?

The readOnlyHint annotation already communicates no side effects, and the description adds useful behavioral details such as default ordering, filtering options, and pagination. It does not describe the response format, but the output schema covers that.

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

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

The description is a single, compact sentence that conveys the core purpose, ordering, filtering capabilities, and pagination. No redundant wording or unnecessary detail is present.

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 output schema and full parameter descriptions, the description covers all necessary context: what is listed, the ordering, available filters, and pagination. No critical information 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?

All five parameters have descriptions in the schema, so the baseline is met. The description summarizes filtering and pagination but does not add meaning beyond what each parameter's own description already 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?

Clearly states the tool lists invoices for the authenticated tenant, with a specific ordering (most recent first). The scope and resource type are unambiguous, and it is easily distinguished from sibling tools like get_invoice or list_companies.

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 the tool (when a list of invoices is needed) but does not explicitly contrast it with alternatives like get_invoice for single records or other list tools. It gives no direct guidance on when not to use this tool.

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?

The readOnlyHint annotation covers side-effect transparency, and the description adds that only successful calls are logged. It does not mention error handling or edge cases, but the annotation suffices for this read-only 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 a single, focused sentence with no redundant information. It efficiently conveys the tool's purpose and output 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 simple read-only log tool, the description is complete: it explains what entries look like and the ordering (newest first). The output schema is present, so no additional context is needed.

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 only parameter, limit, is fully described in the schema with constraints (1-50) and a default (20). The schema coverage is 100%, providing complete semantic clarity for the caller.

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 tool's function: listing the tenant's recent agent activity log. It specifies the resource (MCP tool calls) and distinguishes it from sibling tools that perform other 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 implies usage for auditing or reviewing agent actions, but does not explicitly state when to use it versus alternatives. Since no direct alternative exists among the sibling tools, the guidance is adequate but not fully explicit.

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?

Beyond annotations (readOnlyHint false, destructiveHint false), the description adds that the payment date defaults to now, but it does not disclose side effects such as idempotency, whether already-paid invoices error, or whether any related records are updated.

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

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

The description is a single, direct sentence with no redundant phrasing, making it 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 state-change tool, the description covers the essential intent and parameter semantics. It does not describe the return value or error conditions, but given the output schema exists and the action is straightforward, this is adequate.

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?

Both parameters have clear descriptions: invoice_id is identified as the Sent or Overdue invoice UUID, and paid_at includes format and default behavior. This fully compensates for the schema's technical patterns.

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 (Mark) and the target resource (a Sent or Overdue invoice as Paid). It distinguishes this from siblings like cancel_invoice or issue_invoice by specifying the state transition.

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

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

The description implies when to use it (on Sent or Overdue invoices) but does not explicitly mention preconditions like verifying the current state or that it should not be used on already-paid invoices. It does clarify the optional payment date default.

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?

The description explains the main side effect (creates a client credit) and implies a write operation. It does not mention reversibility or other potential effects, but annotations are sparse (readOnly=false, destructive=false), so the description carries the burden and covers the key behavior well.

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 clear, tight sentences with no redundant wording. Efficiently conveys purpose, conditions, and consequence.

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 simple two-parameter schema and the sibling context, the description is complete. It explains the outcome (credit) and the relationship to apply_provisions_to_invoice, leaving no ambiguity about the tool's role.

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 adds default behavior for paid_at (defaults to now) and identifies invoice_id as the provision UUID. The schema already provides detailed format and descriptions for both parameters, so the description adds marginal but useful context beyond the schema.

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

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

Clearly states the action (mark as paid), the target (provision), the applicable statuses (Sent/Overdue), and the resulting effect (becomes client credit). Distinguishes it from sibling tools like mark_invoice_paid.

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 defines when to use (for Sent/Overdue provisions) and explains the consequential credit that can be applied via apply_provisions_to_invoice. Provides enough context to select this tool over 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?

The description discloses the tool's mutation behavior (creates a new invoice, marks the original as Rectified only upon confirmation), the preview-vs-create distinction via the confirm parameter, and the server-side VAT determination. This goes beyond the sparse annotations (readOnlyHint false, destructiveHint false) to give a concrete picture of what happens when the tool is called.

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 slightly long but each sentence carries essential operational or fiscal information. It front-loads the primary purpose and confirm semantics, then details parameters. No waste, but the repeated emphasis on VAT rules and defaults could be trimmed without losing critical guidance.

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

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

Given that an output schema exists (per context signals), the description need not detail return values. It covers invocation, parameters, defaults, and side effects, leaving no significant gaps for an agent to call the tool correctly. Minor omission: it doesn't explicitly state the output format of the preview, but this is acceptable since the output schema is expected to cover it.

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?

Every parameter is described with meaningful details beyond the schema. For example, the tax_rate parameter explicitly warns 'OMIT - do NOT ask the user for a VAT rate' and explains server-side rules; line_type is explained with billable/visual/text distinctions; items and notes have default-copy behavior. This fully compensates for any schema gaps.

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

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

The description clearly states the tool creates a rectifying invoice for a Sent or Paid invoice, distinguishes it from other invoice operations by specifying it creates a NEW Draft pre-filled from the original, and explains the legal linkage and marking of the original. This is a specific verb+resource combination that leaves no ambiguity about what the tool does.

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 explains when to use the tool (for rectifying sent/paid invoices) and the critical confirm behavior: 'Call with confirm:true to create; without it, returns a preview.' It also clarifies the effect on the original invoice, giving the agent clear guidance on invocation and expected consequences.

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?

Description transparently reveals the destructive nature ('ends the quote's lifecycle') and the preview mechanism when confirm is false. This aligns with the destructiveHint annotation and adds meaningful behavioral context beyond the schema.

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 concise sentences with no redundant or vague wording. Every sentence carries essential information about the action, effect, and confirm behavior.

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 parameter set (quote_id, confirm) plus output schema, the description sufficiently explains the purpose, effect, and preview mode. No additional context is needed to call 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 already provides full descriptions for both parameters (quote_id: 'The Sent quote UUID'; confirm: 'Must be true to reject. Omit/false to preview only.'). The description repeats the confirm semantics without adding new detail, so no additional value beyond 100% schema coverage.

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?

Description clearly states the action ('Mark a Sent quote as Rejected') and the resource ('Sent quote'), with the consequential effect 'ends the quote's lifecycle'. It distinguishes from sibling actions like accept_quote by targeting rejection.

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 concrete usage instructions for the confirm parameter ('Call with confirm:true to apply; without it, returns a preview'). It defines when to apply versus preview, though it does not explicitly compare to alternative quote-related tools.

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?

The description discloses key side effects: recalculation of invoice totals and the provision becoming available for reuse. It does not mention error conditions or permission requirements, but given the simple nature of the operation and that annotations provide limited detail, the description covers the primary behavioral outcomes well.

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 with no redundant information. It directly states the action, the target, the restriction, and the result, 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?

The description covers the essential context: the draft restriction, the calculation update, and the provision reuse. It does not specify the return value or handle non-draft cases, but for a straightforward operation these omissions are minor and the description is sufficiently complete for typical use.

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?

Both parameters have clear descriptions in the input schema ('The Draft final invoice UUID' and 'The provision UUID to detach'), providing full coverage. The tool description does not add extra meaning beyond what the schema already conveys, 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 action 'Detach a provision from a DRAFT final invoice' and the effect 'recalculate its advances_total / amount_due'. It distinguishes this from sibling tools like 'apply_provisions_to_invoice' by specifying the removal action and the draft-invoice constraint.

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

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

The description implies usage for draft invoices only and notes that the provision becomes available again, but it does not explicitly contrast with alternatives or state when not to use it. This leaves some ambiguity for an agent deciding between removal and other invoice modification functions.

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?

The description reveals that the tool sets a new display order and that the order must be full ('every item id'). It does not mention validation behavior, error handling, or whether it replaces the entire order, but the core behavior is transparent. Annotations confirm it is a write operation (readOnlyHint false).

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

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

The description is concise, consisting of two clear sentences. It avoids redundancy and directly explains the action and key usage requirements.

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 parameters, the description and schema together provide sufficient context for usage. The description explains how to obtain item IDs and the requirement for a full order. It could mention error conditions but is otherwise 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?

The input schema provides descriptions for both parameters and nested fields, achieving 100% schema coverage. The description adds semantic value by clarifying that the order must be complete and that item IDs should come from specific sources, going beyond the schema text.

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 tool's purpose: 'Set the display order of an invoice's line items.' It is specific and distinct from sibling tools like update_invoice_item or get_invoice.

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 usage guidance: 'Pass the full desired order' and indicates where item IDs come from ('get_invoice or add_invoice_item'). It implies this is for reordering multiple items, though it does not explicitly contrast with updating individual items.

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?

The description goes well beyond the annotations, disclosing irreversibility, legal binding under French law, the internal fiscal certification 'plumbing,' and the expectation to hide implementation details from the user. It also explains the preview behavior when confirm is not true. This is rich behavioral context with no contradiction to the destructiveHint annotation.

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 longer than average but each sentence adds distinct value: purpose, legal consequence, approval step, preview behavior, and internal user-communication constraints. The emphasis via caps is purposeful, though some redundancy exists between 'IRREVERSIBLE' and the later prohibition on mentioning immutability.

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 output schema exists wet and the annotations flag destructiveness, the description covers all essential operational context: what the tool does, how to preview, the irreversible consequence, and how to communicate results to the user. Nothing an agent needs to safely invoke this tool is missing.

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

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

The schema already documents confirm and invoice_id with 100% coverage eslint. The description adds key semantics: confirm must be true to issue and otherwise returns a preview, which is essential for safe invocation. The invoice_id parameter is adequately described as 'The Draft provision UUID' in both schema and 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 verb and resource: 'Issue a Draft provision: the legal act of creating it.' It clarifies the effect (status Sent, PROV series) and distinguishes the tool from a mere draft creation by emphasizing finality. The title 'Issue provision (LEGALLY BINDING)' reinforces the unique act this tool performs.

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 operational guidance: always show details and get approval before calling with confirm:true, and use confirm:false/omitted to preview. It does not explicitly contrast with siblings like create_provision or apply_provisions_to_invoice, but the workflow guidance for this specific call is unambiguous and actionable.

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 already indicate readOnlyHint=false and destructiveHint=true, so the description doesn't need to restate mutation. It adds useful context: no certification involved, and French B2B validation. However, it doesn't disclose potential side effects or reversibility beyond the state change. Given annotations cover the safety profile, the added context justifies a 3.

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 primary action is front-loaded, and the validation note is concise. Every sentence adds value.

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

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

For a single-parameter tool with an output schema present, the description covers the key aspects: the state transition, the client-facing nature, the absence of certification, and the French validation condition. It's complete enough for an agent to call it correctly without additional details.

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% – the quote_id parameter already has a clear description ('The Draft quote UUID.'). The tool description adds no extra parameter-level detail. Baseline 3 applies because the schema handles parameter documentation.

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: 'Transition a Draft quote to Sent (the client-facing state).' It clearly identifies the resource (quote) and the state change, and adds a clarifying note that no certification is involved, distinguishing it from certification-related tools. It also mentions French B2B validation, which further specifies the tool's scope.

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 some usage context (French validation applies when tenant is French) but does not explicitly differentiate from sibling tools like convert_quote_to_invoice or reject_quote. The when-to-use is implied (when you want to send a draft quote) but no alternatives are named or excluded.

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?

The description explicitly states 'Only provided fields change', which clarifies the partial update behavior. This goes beyond the annotations (readOnlyHint false, destructiveHint false) by explaining the update semantics. It does not mention potential side effects, but the core behavior is well described.

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 long, with no redundant information. It efficiently conveys the purpose, the partial update behavior, and a practical use case, making it well-structured and easy to absorb.

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?

The description includes all essential context: the action (update), the target (existing company), the fields involved, the partial update rule, and a real-world scenario (invoice certification). Combined with the full schema descriptions and annotations, nothing critical is missing for an agent to decide when and how to invoke this 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?

The schema already provides descriptions for all 11 parameters (100% coverage), so the parameter semantics are fully handled by the schema. The description mentions the key field categories but does not add meaning beyond what the schema already states, hence a baseline score of 3.

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 tool updates an existing company and lists the specific fields (name, contact info, address, VAT number, SIREN). This distinguishes it from create_company, delete_company, and get_company, making the purpose 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 when to use the tool, especially noting that fixing VAT/SIREN/address is often required before invoice certification. It does not explicitly contrast with sibling tools, but the partial update behavior and use case provide strong practical guidance.

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?

The description transparently indicates a write operation (update) and the constraint on Draft status. It does not contradict the annotations (readOnlyHint=false, destructiveHint=false), and the side effect of rebuilding the client snapshot is captured in the parameter description.

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, concise and directly to the point. It includes the essential scope and constraint without unnecessary elaboration.

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 that an output schema exists and all parameters are well-documented, the description covers the necessary context for correct usage. It communicates the key restriction (Draft-only) and the fields involved, which is sufficient for this straightforward update operation.

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

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

All parameters are fully described in the schema with coverage at 100%, so the baseline is 3. The description adds only a brief summary of field types ('dates, payment terms, notes, or reassign the company') without providing additional meaning beyond the schema.

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

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

The description clearly states the verb 'Update', the resource 'invoice', and the specific scope 'Draft invoice'. It also lists the fields that can be updated, making it unambiguous and distinct from sibling tools like create_invoice or issue_invoice.

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 that only Draft invoices can be modified and that Sent/certified invoices are immutable, providing a clear condition for when to use this tool. It does not explicitly compare to alternatives, but the scope is distinct enough.

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