Server Quality Checklist

Tool Scores

• get_invoice_payment_statusA
  4.3/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, so the agent knows this is a read operation. The description reinforces this by stating 'Read-only — this reports on collections, it does not record one.' However, it adds little beyond the annotation, merely elaborating the read-only nature. With annotations covering safety, a score of 3 is appropriate.

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

  Conciseness5/5

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

  The description is three sentences, front-loaded with purpose and return values, then usage guidelines. No wasted words.

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

  Completeness5/5

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

  Despite no output schema, the description lists all returned fields (invoiceTotalAmount, paidAmount, unpaidAmount, paid flag) and gives example queries. It covers parameter count and usage context adequately.

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

  Parameters3/5

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

  Input schema coverage is 100% with descriptions for all three parameters (number, seriesName, companyVatCode). The description does not add additional meaning beyond what the schema already provides, so baseline 3 applies.

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

  Purpose5/5

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

  The description clearly states the tool answers whether an invoice is paid and returns specific amounts (invoiceTotalAmount, paidAmount, unpaidAmount) and a paid flag. It uses specific verbs ('answer', 'returns') and clearly distinguishes itself from sibling tools like create_payment.

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

  Usage Guidelines5/5

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

  The description explicitly provides example questions ('has invoice FF 120 been paid?', 'how much does this client still owe?') and advises to use it after create_payment to confirm effects. It also directs users to create_payment for recording payments, giving clear when-to-use and 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.

• create_paymentA
  4.4/5.0
  Behavior4/5

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

  The description explains behavioral consequences: settling invoices updates their payment status, confirmable with get_invoice_payment_status. It also notes that this does not issue an invoice. Annotations already indicate it's not read-only and not destructive, which aligns. No contradictions.

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

  Conciseness5/5

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

  The description is concise (three paragraphs) and front-loaded with the main purpose. Each paragraph adds essential information: usage trigger, invoice handling, type guidance, and distinction from create_invoice. No unnecessary words or repetitions.

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

  Completeness4/5

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

  Given the tool's complexity (17 parameters, nested objects) and lack of output schema, the description covers key aspects: when to use, how to handle invoices, type selection, and relationship to invoices. It doesn't detail every parameter, but the schema compensates. The description is sufficient for an agent to correctly invoke the tool.

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

  Parameters3/5

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

  Schema coverage is 100% with detailed descriptions for each parameter. The description adds value by explaining the purpose of invoices, the meaning of type values, and conditions for seriesName. However, it doesn't cover every parameter beyond what the schema provides, so it provides moderate additional guidance.

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

  Purpose5/5

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

  The description clearly states the verb ('Record money received from a client') and the resource (payment). It distinguishes itself from create_invoice by explicitly stating 'This does not issue an invoice; use create_invoice for that.' The title 'Record a payment' aligns with the description.

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

  Usage Guidelines5/5

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

  The description gives explicit usage guidance: 'Use this when the user says a customer has paid.' It explains when to pass invoices vs. leave empty, and advises to ask the user rather than guessing for the type. It also mentions an alternative tool (create_invoice) for issuing invoices.

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

• create_reverse_invoiceA
  4.4/5.0
  Behavior4/5

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

  Annotations set readOnlyHint=false and destructiveHint=false. The description adds that this creates a new fiscal document and that both documents remain and cancel out, which is useful context. It does not contradict annotations, and the confirmation warning adds transparency. However, it could mention side effects like potentially affecting accounting periods.

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

  Conciseness5/5

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

  The description is four sentences long, front-loaded with purpose and usage guidance. Every sentence adds value, and there is no unnecessary repetition or fluff.

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

  Completeness4/5

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

  The description covers when to use, alternatives, and a confirmation warning. Given the lack of output schema, it could be more complete by briefly stating what the response contains or if any side effects occur (e.g., immediate posting to accounting). However, it is fairly complete for the tool's complexity.

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

  Parameters3/5

  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 each parameter. The description adds minor context (e.g., 'into the same series', fallback defaults) but does not significantly enhance understanding of parameter usage beyond the schema.

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

  Purpose5/5

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

  The description clearly states the tool issues a storno invoice that reverses an existing invoice in full into the same series. It uses a specific verb ('Issue') and resource ('storno invoice'), and distinguishes it from siblings like cancel_invoice and delete_invoice.

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

  Usage Guidelines5/5

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

  The description explicitly states when to use (invoice too old to delete, needs to appear in books) and when not to (use cancel_invoice for voiding, or issue a new invoice with negative quantities for partial corrections). It also advises confirming with the user before calling.

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

• get_estimate_invoicesA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, and the description reinforces that it is read-only. It adds context about checking invoices, but no additional behavioral traits beyond what annotations convey.

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

  Conciseness5/5

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

  Only three sentences, front-loaded with purpose and usage. No unnecessary information.

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

  Completeness4/5

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

  Given no output schema, the description explains what an empty result means and implies the result is a list of invoices. Adequate for a read-only list tool.

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

  Parameters3/5

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

  Schema description coverage is 100%, so parameters are fully described in the schema. The description does not add further details about parameters, so baseline 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the purpose: 'Check whether a proforma has already been invoiced, and which invoices came out of it.' It uses specific verbs and resources, and distinguishes from sibling tools like create_invoice_from_estimate.

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

  Usage Guidelines5/5

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

  Provides explicit guidance: 'Call this before create_invoice_from_estimate to avoid double-invoicing' and answers specific questions. Tells what an empty result means.

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

• cancel_estimateA
  4.5/5.0
  Behavior4/5

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

  Annotations indicate destructive and idempotent. Description adds that it's reversible, keeps the number, and prevents series gaps, which is useful behavioral context beyond annotations.

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

  Conciseness5/5

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

  Two succinct paragraphs with clear structure: first explains what it does, second gives usage guidance. No unnecessary words.

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

  Completeness5/5

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

  For a simple tool with 3 params and no output schema, the description covers behavior, reversibility, and differentiation from key siblings. Complete for the context.

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

  Parameters3/5

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

  Schema coverage is 100% with detailed descriptions. The description does not add parameter-level details, but baseline 3 is appropriate as schema already covers all parameters.

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

  Purpose5/5

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

  The description states 'Void a proforma' with clear verb and resource, and distinguishes from siblings like delete_estimate by explaining that it marks as cancelled and keeps the number.

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

  Usage Guidelines5/5

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

  Explicitly states when to use ('when a quote is withdrawn or the customer declines') and when to use delete_estimate instead, providing clear differentiation.

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

• cancel_paymentA
  4.5/5.0
  Behavior4/5

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

  Annotations provide destructiveHint=true and idempotentHint=true. The description adds behavioral nuance: the receipt keeps its number, is marked cancelled, and series has no gap. This goes beyond annotations but could be more detailed about reversibility or post-void state.

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

  Conciseness5/5

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

  Two short paragraphs: first explains action and effect, second gives usage with clear alternatives. Every sentence adds value with no redundancy.

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

  Completeness5/5

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

  Despite no output schema, the description fully covers the tool's purpose, behavior, and context. Sibling tools are named for disambiguation, and annotations cover safety semantics. Nothing essential is missing.

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

  Parameters3/5

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

  Schema coverage is 100% with all parameters described. The description adds no new parameter details beyond the schema, which is acceptable. Baseline 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states the tool voids a receipt without removing it, distinguishing it from deletion tools. It specifies the verb 'void' and the resource 'receipt', and differentiates from siblings like delete_payment and delete_receipt.

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

  Usage Guidelines5/5

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

  Explicit guidance: 'Use this when a receipt was issued in error.' And it specifies when not to use: for card/bank transfer collections use delete_payment, to remove entirely use delete_receipt. This provides excellent decision support.

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

• create_invoiceA
  4.5/5.0
  Behavior4/5

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

  The description discloses that an issued invoice generally cannot be deleted afterwards, which is critical behavioral context beyond the annotations. It also mentions the return format. However, it does not elaborate on authentication or rate limits, but given the annotations' limited scope, this 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.

  Conciseness5/5

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

  The description is five sentences with no fluff, front-loading the purpose and return value, followed by prerequisites, exclusions, and consequences. Every sentence adds essential information.

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

  Completeness5/5

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

  Given the tool's complexity (30 parameters, nested objects, no output schema), the description covers purpose, return type, prerequisites, exclusions, and a critical post-condition (inability to delete). The schema handles parameter details, leaving the description to fill contextual gaps, which it does effectively.

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

  Parameters3/5

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

  The input schema has 100% coverage with descriptions for all parameters. The description adds some high-level guidance (e.g., using list_taxes for valid tax values), but does not add significant per-parameter meaning beyond what the schema provides.

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

  Purpose5/5

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

  The description clearly states the tool issues a new invoice for a normal sale, specifying the resource (invoice in SmartBill) and action (create). It also distinguishes itself from sibling tools like create_invoice_from_estimate and create_reverse_invoice by explicitly stating what not to use it for.

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

  Usage Guidelines5/5

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

  The description provides explicit guidance on when to use the tool (normal sale) and when not to (invoice from proforma, reverse invoice). It also advises using list_taxes and list_series beforehand, and instructs to confirm details with the user and use isDraft for unsettled cases.

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

• create_invoice_from_estimateA
  4.5/5.0
  Behavior4/5

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

  Annotations indicate readOnlyHint=false and destructiveHint=false. The description adds that the tool links documents and reports the proforma as invoiced, and warns against re-sending client/line items. It also specifies the return format. This adds useful behavioral context beyond annotations, though it could mention if the action is reversible or any permission requirements.

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

  Conciseness4/5

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

  The description is three sentences plus a short paragraph. It is front-loaded with the main purpose, followed by usage guidelines, and then parameter clarifications. No redundant information; every sentence serves a purpose. Could be slightly more compact but is already efficient.

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

  Completeness4/5

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

  For a tool with 10 parameters (1 required) and no output schema, the description covers purpose, behavioral effects, parameter hints, and return format. It provides sufficient context for an AI to decide when to use and how to invoke it. Missing explicit return value details beyond { series, number, url }, but that is enough.

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

  Parameters4/5

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

  Schema coverage is 100%, but the description adds meaning by explaining that client and line items are copied from the proforma (so not to be sent) and that seriesName is for the invoice while estimateSeriesName/estimateNumber identify the source. This clarifies the role of parameters beyond their schema descriptions.

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

  Purpose5/5

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

  The description clearly states the action (issue an invoice), the source (from a proforma/estimate), and distinguishes it from the sibling create_invoice by emphasizing that it links documents. The verb 'issue' and resource 'invoice from proforma' are specific.

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

  Usage Guidelines5/5

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

  Explicitly advises preferring this tool over create_invoice when a proforma exists, and warns against manually rebuilding the invoice. It also notes that client and line items are copied, so they should not be re-sent. This provides clear when-to-use and 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.

• delete_estimateA
  4.5/5.0
  Behavior4/5

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

  Annotations already indicate destructiveHint=true; description adds irreversibility and number reuse details. No contradiction. Adds context beyond annotations.

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

  Conciseness5/5

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

  Three concise sentences front-load key information with zero waste. Efficient and clear structure.

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

  Completeness5/5

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

  Complete description for an irreversible mutation tool with series constraints. No output schema needed; all behavioral and usage details are covered.

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

  Parameters3/5

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

  Schema covers 100% of parameters with descriptions. Description does not add additional parameter information beyond what schema provides.

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

  Purpose5/5

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

  Clearly states the tool permanently removes a proforma and frees its number. Distinguishes from cancel_estimate by specifying it only works for the last in a series.

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

  Usage Guidelines5/5

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

  Explicitly states when to use (last proforma only) and when not to (earlier ones), recommends cancel_estimate as alternative, and advises user confirmation.

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

• delete_invoiceA
  4.5/5.0
  Behavior4/5

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

  Description adds value beyond annotations by noting irreversibility ('no restore') and warning about fiscal document destruction. Annotations already declare destructiveHint=true and idempotentHint=true; the description supplements but does not contradict. Idempotency is not explained, but overall transparency is strong.

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

  Conciseness5/5

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

  The description is three concise paragraphs: main action, usage constraints with alternatives, and a final warning. Every sentence provides essential information without redundancy, well front-loaded.

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

  Completeness5/5

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

  For a destructive financial tool with constraints, the description covers the core action, conditions, alternatives, and user confirmation requirement. No output schema exists, but the explanation suffices 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.

  Parameters3/5

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

  All parameters are described in the schema (100% coverage), so the description's role is limited. It mentions 'invoice number' without series prefix, which matches the schema. No additional semantic value beyond what the schema provides, earning a baseline score of 3.

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

  Purpose5/5

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

  The description states 'Permanently remove an invoice, freeing its number for reuse.' This provides a specific verb-resource pair and distinguishes itself from siblings like cancel_invoice and create_reverse_invoice by highlighting the effect of number reuse.

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

  Usage Guidelines5/5

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

  Explicitly states the condition for use ('only for the LAST invoice in a series') and provides alternatives ('cancel_invoice' and 'create_reverse_invoice') with clear instructions for uncertain cases, fulfilling explicit when-to-use and 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.

• get_fiscal_receipt_textA
  4.5/5.0
  Behavior4/5

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

  The description adds behavioral context beyond the readOnlyHint annotation by specifying that the tool is read-only ('Read-only'), fetches decoded plain text, and requires the SmartBill id (not series/number). This provides useful operational details.

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

  Conciseness5/5

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

  The description is three sentences with no waste. The first sentence states the core purpose, the second adds usage guidance, and the third clarifies the identifier. It is front-loaded and every sentence earns its place.

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

  Completeness5/5

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

  Given the tool has only 2 parameters (one required), no output schema, and annotations providing readOnlyHint, the description adequately describes the output, input semantics, and usage. It is complete for the complexity level.

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

  Parameters4/5

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

  The input schema already has good descriptions (100% coverage) for both parameters. The description further clarifies the 'id' parameter by emphasizing it is the internal SmartBill id, not series/number, adding value beyond the schema.

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

  Purpose5/5

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

  The description clearly states the verb 'Fetch', the resource 'fiscal receipt (bon fiscal)', and the identifier type 'SmartBill id'. It distinguishes from siblings by specifying that series and number are not the right input, making the purpose 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.

  Usage Guidelines4/5

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

  The description explicitly states when to use the tool ('inspect or reprint') and when not to ('if you only have those [series and number], this is not the right tool'). It provides clear context for appropriate usage, though it does not name a specific alternative tool.

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

• get_invoice_pdfA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, so the read-only nature is known. The description adds further detail about return format (path or base64) and the ability to force one via 'as' parameter, which goes beyond what annotations provide.

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

  Conciseness4/5

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

  The description is concise with about four sentences covering purpose, usage, return format, and alternative tool. It is front-loaded with the primary action. Could be slightly more structured, but overall efficient.

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

  Completeness4/5

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

  Given the tool has well-documented parameters (100% schema coverage) and no output schema, the description sufficiently describes the return types (path or base64) and the ability to force format. No missing critical information for agent invocation.

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

  Parameters4/5

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

  Schema covers all 4 parameters with descriptions, so baseline is 3. The description adds value by explaining the 'as' parameter's purpose and default behavior, and implies usage of other parameters (e.g., invoice number), elevating it above baseline.

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

  Purpose5/5

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

  The description uses specific verb 'Fetch' and clearly identifies the resource as 'PDF of an already-issued invoice'. It distinguishes the tool from its sibling 'send_document_email' by stating its purpose for when the user wants the document itself.

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

  Usage Guidelines5/5

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

  The description explicitly states when to use: 'for when the user wants the document itself'. It also provides an exclusion criterion: 'to send the invoice to the client by email, use send_document_email instead'. This clearly guides the agent on tool selection.

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

• restore_estimateA
  4.6/5.0
  Behavior5/5

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

  Annotations provide idempotentHint=true and destructiveHint=false. Description adds key behavioral context: undoes cancel_estimate, cannot restore deleted ones, and puts back into normal state. No contradiction 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.

  Conciseness5/5

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

  Two concise sentences with no wasted words. Clear and front-loaded with the core action and limitations.

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

  Completeness4/5

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

  For a simple tool with no output schema, description covers purpose, usage guidelines, and a key limitation. Omits mention of precondition (estimate must be cancelled) but it's implied. Slightly incomplete but adequate.

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

  Parameters3/5

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

  Schema coverage is 100%, and description does not add any parameter-level details beyond what the schema already provides. Baseline 3 is appropriate.

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

  Purpose5/5

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

  Description clearly states 'undo cancel_estimate and put a cancelled proforma back into its normal state', specifying verb (restore), resource (cancelled estimate), and differentiating from deletion. It distinguishes from sibling tools like cancel_estimate and delete_estimate.

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

  Usage Guidelines5/5

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

  Explicitly says 'Use this when a quote was voided by mistake and is live again' and clarifies when not to use: 'It cannot bring back a proforma that was deleted'. Provides clear context and alternatives.

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

• cancel_invoiceA
  4.7/5.0
  Behavior5/5

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

  Beyond annotation hints (idempotent, destructive), the description adds that the document stays in the system, keeps its number, and is marked cancelled to avoid series gaps. It also mentions reversibility via restore_invoice and warns that it changes the status of a real fiscal document.

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

  Conciseness5/5

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

  The description is concise, using three short paragraphs. The first clearly defines the action, the second provides usage context, and the third gives a critical user confirmation warning. Every sentence adds value.

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

  Completeness5/5

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

  Given the tool's simplicity (3 parameters, no output schema) and high schema coverage, the description covers all necessary behavioral aspects: what happens on cancellation, reversibility, alternatives, and user safety. It is complete for correct agent invocation.

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

  Parameters3/5

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

  Schema coverage is 100% with clear parameter descriptions. The description does not add extra meaning to parameters, so a baseline score of 3 is appropriate per guidelines.

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

  Purpose5/5

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

  The description clearly states it voids an invoice, specifies the effect (keeps number, marked cancelled, no gap), and distinguishes from sibling tools delete_invoice and create_reverse_invoice. The verb 'void' and the term 'anulare' add specificity.

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

  Usage Guidelines5/5

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

  Explicitly tells when to use (invoice issued in error) and when not to, naming specific alternatives (delete_invoice for last in series, create_reverse_invoice for storno). Also instructs to confirm with the user before calling, which is crucial for a destructive operation.

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

• delete_receiptA
  4.7/5.0
  Behavior5/5

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

  Description says 'Permanently remove' and 'Irreversible', matching the destructiveHint and idempotentHint annotations. No contradiction.

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

  Conciseness5/5

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

  Three concise sentences, each important: purpose, alternatives, and user confirmation. Front-loaded.

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

  Completeness5/5

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

  Covers purpose, alternatives, and user guidance. With annotations and full schema, no gaps remain.

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

  Parameters3/5

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

  Input schema already provides full descriptions for all 3 parameters (100% coverage). Description adds minimal extra meaning beyond identifying receipt by series and number.

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

  Purpose5/5

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

  Clearly states it permanently removes a receipt, and distinguishes from cancel_payment and delete_payment for other cases.

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

  Usage Guidelines5/5

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

  Explicitly tells when to use alternatives (cancel_payment for voided records, delete_payment for other payment types) and advises user confirmation.

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

• get_estimate_pdfA
  4.7/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true. Description adds key details: return format varies by server (path or base64) and how to force a specific format via 'as' parameter. Discloses behavior beyond annotations.

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

  Conciseness5/5

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

  Three sentences, front-loaded with purpose and read-only status. Every sentence adds value: purpose, return format behavior, alternative tool. No wasted words.

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

  Completeness5/5

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

  For a read-only fetch tool with 100% parameter coverage and readOnlyHint, the description fully addresses usage, return types, and alternatives. No gaps identified.

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

  Parameters4/5

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

  Schema coverage is 100%, baseline 3. Description adds context for 'as' parameter: explains default behavior and how to force file or base64. Provides additional meaning beyond enum labels.

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

  Purpose5/5

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

  Clear verb 'Fetch the PDF' with specific resource 'already-issued proforma'. Explicitly states read-only nature and distinguishes from sending via email. Differentiates from siblings like send_document_email.

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

  Usage Guidelines5/5

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

  States when to use: 'when the user wants the document itself'. Provides explicit alternative: 'To send...by email, use send_document_email instead'. No ambiguity.

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

• list_stocksA
  4.7/5.0
  Behavior4/5

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

  Annotations provide readOnlyHint: true, and description adds value by explaining read-only nature, date behavior, and defaults. No contradictions, but the description doesn't disclose pagination or return format, which would have made it a 5.

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

  Conciseness5/5

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

  Two concise sentences with no redundancy. The purpose is front-loaded, and every sentence adds value. No wasted words.

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

  Completeness5/5

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

  Given no output schema, the description adequately explains return value (stock levels) and covers all usage contexts. The tool has few parameters and no nested objects, so completeness is high.

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

  Parameters4/5

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

  Schema coverage is 100%, but the description adds meaning by explaining parameter defaults and behavior (e.g., 'Omitting warehouseName covers every warehouse; omitting date reports today'). This goes beyond the schema's descriptions.

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

  Purpose5/5

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

  The description clearly states 'Read stock levels as of a date' with optional narrowing by warehouse or product. This is a specific verb+resource combination that distinguishes the tool from sibling tools focused on invoices, payments, etc.

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

  Usage Guidelines5/5

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

  Explicitly states when to use: 'to answer how many do we have left?', 'check availability before invoicing with useStock', or 'report stock as it stood on a past date'. Also explains defaults for omitted parameters, providing clear guidance.

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

• list_taxesA
  4.7/5.0
  Behavior5/5

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

  Declares 'Read-only and cheap' which aligns with annotation readOnlyHint=true. Adds contextual insight: rates change over time and differ per account, justifying read-only nature.

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

  Conciseness5/5

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

  Two concise sentences in first paragraph for purpose, then usage instructions. No fluff, every sentence adds value.

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

  Completeness5/5

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

  Despite no output schema, description specifies output format (name/percentage pairs). Also provides usage context and caveats, making it complete for a listing tool.

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

  Parameters3/5

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

  Schema coverage is 100% with a description for companyVatCode. Description doesn't add new meaning beyond schema, so baseline of 3 is appropriate.

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

  Purpose5/5

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

  Description explicitly states verb 'list', resource 'VAT rates', and output format 'name/percentage pairs'. Distinguishes from sibling tools by specifying its purpose.

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

  Usage Guidelines5/5

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

  Explicitly instructs to call before create_invoice or create_estimate when uncertain about rates, and to copy returned values verbatim. Also warns against using remembered values due to variation.

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

• restore_invoiceA
  4.7/5.0
  Behavior5/5

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

  Annotations already indicate idempotent and non-destructive; the description adds that it is an undo operation with specific limitations (no effect on non-cancelled, no restore for deleted), which complements annotations well.

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

  Conciseness5/5

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

  Three sentences with no wasted words: first sentence states core action, second gives usage context, third clarifies edge cases. Well-structured and front-loaded.

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

  Completeness5/5

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

  Given full parameter coverage and annotations, the description covers purpose, usage, and limitations completely. No output schema is needed for a state-changing tool; the behavior is fully described.

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

  Parameters3/5

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

  Schema coverage is 100%, so baseline 3 applies. The description does not add any parameter detail beyond the schema, but the schema itself is sufficiently descriptive.

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

  Purpose5/5

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

  The description clearly states the verb 'undo cancel_invoice' and the resource 'cancelled invoice', and distinguishes from siblings like cancel_invoice and delete_invoice by specifying it only works on cancelled invoices, not deleted ones.

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

  Usage Guidelines5/5

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

  The description explicitly states when to use ('when an invoice was voided by mistake and should count again') and when not to use ('no effect on never-cancelled', 'cannot bring back deleted'). This provides clear context and exclusions.

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

• delete_paymentA
  4.8/5.0
  Behavior5/5

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

  Description explicitly states 'Irreversible', aligning with destructiveHint=true. Adds behavioral context about undoing create_payment and identification strategies beyond annotations.

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

  Conciseness4/5

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

  Well-structured: definition, consequence, usage scenarios, alternatives. All sentences are informative; no fluff. Slightly long but fully justified.

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

  Completeness5/5

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

  Complete for a delete tool with 8 params and no output schema. Covers identification, prerequisites, irreversibility, and sibling differentiation.

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

  Parameters4/5

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

  Schema coverage is 100% (baseline 3). Description adds value by clarifying which parameters are needed when (e.g., clientCif not needed if invoice known) and how to identify a payment.

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

  Purpose5/5

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

  Clearly states the tool removes non-receipt payments (card, bank transfer, etc.) and explicitly distinguishes from receipt-related siblings.

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

  Usage Guidelines5/5

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

  Provides explicit when-to-use (undo wrong payments), when-not-to-use (receipts use cancel_payment/delete_receipt), and identification methods. Also advises confirming with user.

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

• create_estimateA
  4.9/5.0
  Behavior5/5

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

  Annotations only indicate non-read-only and non-destructive. Description adds that it creates a non-fiscal document, returns series/number/url, and is part of a lifecycle (estimate → invoice). No contradictions.

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

  Conciseness5/5

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

  Three sentences, front-loaded with purpose and return value, then usage guidance. Every sentence adds value; no wasted words.

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

  Completeness5/5

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

  For a tool with 21 parameters and no output schema, the description explains return value, lifecycle (create → convert), and links to related tools. It is sufficiently complete given the complexity.

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

  Parameters4/5

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

  Schema coverage is 100%, so baseline is 3. Description adds useful contextual guidance (e.g., 'As with invoices, call list_taxes for valid VAT rates'), but does not repeat schema descriptions. This raises it slightly above baseline.

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

  Purpose5/5

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

  Clearly states it issues a proforma (estimate), not a fiscal invoice, and specifies return structure. Distinguishes from create_invoice by contrasting use cases.

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

  Usage Guidelines5/5

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

  Explicitly says when to use (customer needs approval/payment before invoicing, user asks for quote/offer/proforma) and when to use create_invoice instead (final sale). Also advises using create_invoice_from_estimate after acceptance and calling list_taxes for VAT rates.

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

• list_seriesA
  4.9/5.0
  Behavior5/5

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

  Discloses 'read-only and cheap' beyond the readOnlyHint annotation, adding cost context that helps the agent prioritize.

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

  Conciseness5/5

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

  Three sentences, front-loaded with purpose, each sentence contributing specific guidance. No waste.

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

  Completeness5/5

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

  Given 2 optional params, no output schema, and read-only nature, the description fully covers what the tool does and when to use it.

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

  Parameters4/5

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

  Schema coverage is 100%, so baseline 3. The description adds value by noting companyVatCode falls back to SMARTBILL_VAT_CODE, which is not in schema.

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

  Purpose5/5

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

  The description clearly states it lists document series on the account with their next numbers, distinguishing it from sibling tools that are write-oriented or more specific.

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

  Usage Guidelines5/5

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

  Explicitly tells when to call: when needing a seriesName, after unknown-series errors, and to answer next invoice number. Also advises against guessing.

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

• send_document_emailA
  4.9/5.0
  Behavior5/5

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

  Discloses that the tool sends real email and instructs to 'confirm the recipient with the user first.' Annotations only indicate non-readonly and non-destructive, but the description adds crucial behavioral warning about irreversible action.

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

  Conciseness5/5

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

  The description is concise and well-structured: starts with core purpose, then usage guidelines, parameter tips, and an alternative. Every sentence adds value with no redundancy.

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

  Completeness4/5

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

  Covers most aspects thoroughly, but lacks any mention of return values or success/failure responses. Given no output schema, a brief note on what the tool returns (e.g., confirmation) would make it fully complete.

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

  Parameters5/5

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

  Adds meaning beyond the schema by explaining that omitting 'to', 'subject', or 'bodyText' uses defaults, and that plain text is acceptable with encoding handled automatically. Schema coverage is 100%, but the description enriches understanding with practical usage guidance.

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

  Purpose5/5

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

  The description clearly states the action: 'Send an invoice or proforma that already exists to the client by email, with the PDF attached by SmartBill.' It specifies the resource (existing document) and verb (send via email), and distinguishes from sibling tools like create_invoice which issue documents.

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

  Usage Guidelines5/5

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

  Explicitly tells when to use ('when the user asks to send or resend a document') and when not to: 'To email a document at the moment it is issued instead, set sendEmail: true on create_invoice or create_estimate rather than calling this afterwards.' This provides clear alternatives and context.

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